node-bunyan#335: start a contributing howto
This commit is contained in:
Trent Mick
parent
4619d33b57
commit
42d2f657fe
1 changed files with 198 additions and 0 deletions
198
CONTRIBUTING.md
Normal file
198
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,198 @@
|
|||
# Contributing to node-bunyan
|
||||
|
||||
Thanks for using node-bunyan and for considering contributing to it! Or perhaps
|
||||
you are just here to get a sniff for what is going on with node-bunyan
|
||||
development.
|
||||
|
||||
|
||||
## How you can help
|
||||
|
||||
If you want to help me here, great! Thank you! Some ideas:
|
||||
|
||||
- Do you have experience with and/or recommendations for a good automated
|
||||
testing service? Ideally I'd like support for Mac, Linux, SmartOS, and maybe
|
||||
Windows. Also, support for node.js versions 0.10 up to whatever the current
|
||||
latest is. Are those too tall an order? What's more, Bunyan is meant to work
|
||||
(at least partially) in the browser. Is there a good service for that?
|
||||
TODO: start an issue for this.
|
||||
|
||||
- Fielding issues labelled with ["Type-Question"](#type) if you are familiar
|
||||
with Bunyan and know how to answer them would be great.
|
||||
|
||||
- If you want to dive into code, but aren't *that* familiar with node-bunyan,
|
||||
then [issues labelled with Experience-Easy](Experience-Easy) is a good
|
||||
place to start.
|
||||
|
||||
- [Once I've made a once over
|
||||
triaging]https://github.com/trentm/node-bunyan/issues/335) and consolodating
|
||||
issues and PRs, volunteering for issues in a particular
|
||||
[component](#component) with which you have familiarity would be great.
|
||||
|
||||
|
||||
## Trent's Biased Rules for Code
|
||||
|
||||
In the hope that it makes it easier to get PRs into Bunyan, here is my biased
|
||||
list of what I typically want. Submitting a PR without all of these is
|
||||
*totally fine*! The only side-effect is that it may take longer for me to
|
||||
provide feedback on it and merge it. I'll politely request missing pieces.
|
||||
|
||||
|
||||
- Please follow existing code style. Contributed code must pass `make check`.
|
||||
(Note: I intended to change to eslint soon, so currently `make check` might
|
||||
be a moving target. TODO: link to ticket for that.)
|
||||
|
||||
- Any user visible change in behaviour should almost certainly include an
|
||||
update to the docs. Currently the "docs" is the README.md.
|
||||
|
||||
- Adding a test case for code changes is **stronly recommended**, else I
|
||||
can't easily promise to not break your fix/feature later. If you don't
|
||||
grok the test suite, please ask. We can use it to form the basis for a
|
||||
"test/README.md".
|
||||
|
||||
- Typically a code change should have an associated issue or PR. This allows
|
||||
addition of follow-up issues, discussion, test data, etc. to be associated
|
||||
with the commit. Just using GitHub pull requests makes this easy.
|
||||
|
||||
- All but the most trivial code changes should have an addition to the
|
||||
[changelog](./CHANGES.md). The audience for the changelog is *Bunyan users*.
|
||||
However, because rebasing longer-lived PRs against master is a pain
|
||||
with a change to CHANGES.md, please **do not include a CHANGES.md change
|
||||
in your PR. Instead suggest a CHANGES.md addition in a comment on the
|
||||
PR.**
|
||||
|
||||
- Good commit messages, please:
|
||||
- The first line should be a succinct summary of the issue or fix. A
|
||||
good candidate is to just cut 'n paste the issue title, if there is one.
|
||||
- If the commit is for a particular issue/PR (see previous rule), please
|
||||
list the issue number in the commit message. E.g. "Fixes #123" or "Related
|
||||
to #234".
|
||||
- The audience for commit messages is *Bunyan developers*.
|
||||
|
||||
|
||||
## Pull Request Lifecycle
|
||||
|
||||
(Language adapted from
|
||||
[terraform](https://github.com/hashicorp/terraform/blob/master/CONTRIBUTING.md).)
|
||||
|
||||
- You are welcome to submit your pull request for commentary or review before it
|
||||
is fully completed. Please prefix the title of your pull request with "[WIP]"
|
||||
to indicate this. It's also a good idea to include specific questions or items
|
||||
you'd like feedback on.
|
||||
|
||||
- Once you believe your pull request is ready to be merged, you can remove any
|
||||
"[WIP]" prefix from the title and a core team member will review. See
|
||||
Trent's Biased Rules above to help ensure that your contribution will be
|
||||
merged quickly.
|
||||
|
||||
- Trent or, if things go well, a node-bunyan maintainer will look over your
|
||||
contribution and either provide comments letting you know if there is anything
|
||||
left to do. Please be patient. Unfortunately, I'm not able to carve out
|
||||
a *lot* of time for Bunyan development and maintenance.
|
||||
|
||||
- Once all outstanding comments and checklist items have been addressed, your
|
||||
contribution will be merged. Merged PRs will be included in the next
|
||||
node-bunyan release.
|
||||
|
||||
- In some cases, we might decide that a PR should be closed. We'll make sure to
|
||||
provide clear reasoning when this happens.
|
||||
|
||||
|
||||
## Issue labels
|
||||
|
||||
The point of issue labeling for node-bunyan is to help answer "what should be
|
||||
worked on now? what can be left for later?" I don't want issue labelling to
|
||||
become a burden for anyone, so (a) don't feel obliged to add them yourself and
|
||||
(b) I'm happy to reevaluate their usage.
|
||||
|
||||
Bunyan shall have categories of [issue
|
||||
labels](https://github.com/trentm/node-bunyan/labels) named "$category-$value".
|
||||
An issue should have max *one* label from each set. Users of Google Code's
|
||||
dearly departed issue tracker may remember this kind of thing. This is a
|
||||
poorman's version of structure issue tracker metadata.
|
||||
|
||||
I'm inclined to *not* do priorities right now. *Possibly* we'll use GitHub
|
||||
milestones to basically set targets for upcoming releases. But otherwise my
|
||||
sense is that for smaller OSS projects, assigning prios will get in the way.
|
||||
If people would think it helpful, I'd consider "Difficulty-" or "Experience-"
|
||||
categories (a la Rust's "E-" labels) to mark easier and intermediate tasks
|
||||
that someone interested but maybe not very familiar with Bunyan might want
|
||||
to tackle.
|
||||
|
||||
For now, here are the various labels and their purpose:
|
||||
|
||||
### Meta
|
||||
|
||||
- needslabels: Temporary label to help me work through labelling all current
|
||||
open issues and PR.
|
||||
See [#335](https://github.com/trentm/node-bunyan/issues/335)
|
||||
where I'm working through this.
|
||||
- needstriage: Temporary label to help me do a single triage pass through all
|
||||
current open issues and PRs.
|
||||
See [#335](https://github.com/trentm/node-bunyan/issues/335)
|
||||
where I'm working through this.
|
||||
|
||||
### Type
|
||||
|
||||
Color: green
|
||||
|
||||
- Type-Question
|
||||
- Type-Bug
|
||||
- Type-Feature
|
||||
- Type-Doc
|
||||
- Type-Task
|
||||
|
||||
### Component
|
||||
|
||||
Color: blue
|
||||
|
||||
- Component-CLI: The `bunyan` command-line tool.
|
||||
- Component-Rotation: The bunyan library's log rotation support.
|
||||
- Component-Browser: Bunyan's handling/support for running in the browser.
|
||||
- Component-Library: catch-all for other library stuff
|
||||
- Component-Project: Project meta stuff like testing, linting, etc.
|
||||
|
||||
The point of components is to find like issues to help with reference, search
|
||||
and resolving them. If no component fits an issue/PR, then don't add a label.
|
||||
|
||||
### Resolution
|
||||
|
||||
Color: red
|
||||
|
||||
- Resolution-WontFix
|
||||
- Resolution-Duplicate
|
||||
- Resolution-Fixed: Also used to indicate "doc written", "question answered",
|
||||
"feature implemented".
|
||||
- Resolution-CannotRepro: After some reasonable attempt by maintainers to
|
||||
reproduce a bug report, I want it to be non-controversial to close it
|
||||
and mark it with this. If given more info by someone able to repro, we
|
||||
can happy re-open issues.
|
||||
|
||||
### Experience
|
||||
|
||||
Color: yellow
|
||||
|
||||
- Experience-Easy: Relatively little experience with node-bunyan should be
|
||||
required to complete this issue.
|
||||
- Experience-NeedsTest: Typically added to an issue or PR that needs a test
|
||||
case. Someone familiar enough with node-bunyan's test suite could tackle this.
|
||||
- Experience-Hard: At a guess, this is a thorny issue that requires known
|
||||
node-bunyan well, knowing node.js well, requires design review or all of
|
||||
these.
|
||||
|
||||
One of the "Experience-\*" labels can optionally be put on an issue or PR to
|
||||
indicate what kind of experience a contributor would need with node-bunyan
|
||||
(and/or node.js) to complete it. For example, if you're looking for somewhere to
|
||||
start, check out the [Experience-Easy][Experience-Easy] tag. This category idea
|
||||
is borrowed from [rust's E-\* labels](rust-issue-triage).
|
||||
|
||||
[Experience-Easy]: https://github.com/trentm/node-bunyan/issues?q=is%3Aopen+is%3Aissue+label%3AExperience-Easy
|
||||
[rust-issue-triage]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#issue-triage
|
||||
|
||||
|
||||
## Acknowledgements
|
||||
|
||||
Anything good about this document is thanks to inspiration from
|
||||
[rust](https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md) and, more
|
||||
recently
|
||||
[terraform](https://github.com/hashicorp/terraform/blob/master/CONTRIBUTING.md).
|
||||
Anything bad about it, is my fault.
|
||||
Loading…
Reference in a new issue