1 | # Contributing to node-bunyan
|
2 |
|
3 | Thanks for using node-bunyan and for considering contributing to it! Or perhaps
|
4 | you are just here to get a sniff for what is going on with node-bunyan
|
5 | development.
|
6 |
|
7 |
|
8 | ## How you can help
|
9 |
|
10 | If you want to help me here, great! Thank you! Some ideas:
|
11 |
|
12 | - Do you have experience with and/or recommendations for a good automated
|
13 | testing service? Ideally I'd like support for Mac, Linux, SmartOS, and maybe
|
14 | Windows. Also, support for node.js versions 0.10 up to whatever the current
|
15 | latest is. Are those too tall an order? What's more, Bunyan is meant to work
|
16 | (at least partially) in the browser. Is there a good service for that?
|
17 | Please discuss on [issue #342](https://github.com/trentm/node-bunyan/issues/342).
|
18 |
|
19 | - Fielding issues labelled with "[Type-Question][Type-Question]", if you are familiar
|
20 | with Bunyan and know how to answer them, would be great.
|
21 |
|
22 | - If you want to dive into code, but aren't *that* familiar with node-bunyan,
|
23 | then [issues labelled with Experience-Easy][Experience-Easy] are a good
|
24 | place to start.
|
25 |
|
26 | - [Once I've made a once over
|
27 | triaging](https://github.com/trentm/node-bunyan/issues/335) and consolodating
|
28 | issues and PRs, volunteering for issues in a particular
|
29 | [component](#component) with which you have familiarity would be great.
|
30 |
|
31 | [Type-Question]: https://github.com/trentm/node-bunyan/issues?q=is%3Aopen+is%3Aissue+label%3AType-Question
|
32 |
|
33 |
|
34 | ## Trent's Biased Rules for Code
|
35 |
|
36 | In the hope that it makes it easier to get PRs into Bunyan, here is my biased
|
37 | list of what I typically want. Submitting a PR without all of these is
|
38 | *totally fine*! The only side-effect is that it may take longer for me to
|
39 | provide feedback on it and merge it. I'll politely request missing pieces.
|
40 |
|
41 |
|
42 | - Please follow existing code style. Contributed code must pass `make check`.
|
43 | (Note: I intended to [change to eslint
|
44 | soon](https://github.com/trentm/node-bunyan/issues/341), so currently `make
|
45 | check` might be a moving target.)
|
46 |
|
47 | - Any user visible change in behaviour should almost certainly include an
|
48 | update to the docs. Currently the "docs" is the README.md.
|
49 |
|
50 | - Adding a test case for code changes is **stronly recommended**, else I
|
51 | can't easily promise to not break your fix/feature later. If you don't
|
52 | grok the test suite, please ask. We can use it to form the basis for a
|
53 | "test/README.md".
|
54 |
|
55 | - Typically a code change should have an associated issue or PR. This allows
|
56 | addition of follow-up issues, discussion, test data, etc. to be associated
|
57 | with the commit. Just using GitHub pull requests makes this easy.
|
58 |
|
59 | - All but the most trivial code changes should have an addition to the
|
60 | [changelog](./CHANGES.md). The audience for the changelog is *Bunyan users*.
|
61 | However, because rebasing longer-lived PRs against master is a pain
|
62 | with a change to CHANGES.md, please **do not include a CHANGES.md change
|
63 | in your PR. Instead suggest a CHANGES.md addition in a comment on the
|
64 | PR.**
|
65 |
|
66 | - Good commit messages, please:
|
67 | - The first line should be a succinct summary of the issue or fix. A
|
68 | good candidate is to just cut 'n paste the issue title, if there is one.
|
69 | - If the commit is for a particular issue/PR (see previous rule), please
|
70 | list the issue number in the commit message. E.g. "Fixes #123" or "Related
|
71 | to #234".
|
72 | - The audience for commit messages is *Bunyan developers*.
|
73 |
|
74 |
|
75 | ## Pull Request Lifecycle
|
76 |
|
77 | (Language adapted from
|
78 | [terraform](https://github.com/hashicorp/terraform/blob/master/CONTRIBUTING.md).)
|
79 |
|
80 | - You are welcome to submit your pull request for commentary or review before it
|
81 | is fully completed. Please prefix the title of your pull request with "[WIP]"
|
82 | to indicate this. It's also a good idea to include specific questions or items
|
83 | you'd like feedback on.
|
84 |
|
85 | - Once you believe your pull request is ready to be merged, you can remove any
|
86 | "[WIP]" prefix from the title and a core team member will review. See
|
87 | Trent's Biased Rules above to help ensure that your contribution will be
|
88 | merged quickly.
|
89 |
|
90 | - Trent or, if things go well, a node-bunyan maintainer will look over your
|
91 | contribution and either provide comments letting you know if there is anything
|
92 | left to do. Please be patient. Unfortunately, I'm not able to carve out
|
93 | a *lot* of time for Bunyan development and maintenance.
|
94 |
|
95 | - Once all outstanding comments and checklist items have been addressed, your
|
96 | contribution will be merged. Merged PRs will be included in the next
|
97 | node-bunyan release.
|
98 |
|
99 | - In some cases, we might decide that a PR should be closed. We'll make sure to
|
100 | provide clear reasoning when this happens.
|
101 |
|
102 |
|
103 | ## Issue labels
|
104 |
|
105 | The point of issue labeling for node-bunyan is to help answer "what should be
|
106 | worked on now? what can be left for later?" I don't want issue labelling to
|
107 | become a burden for anyone, so (a) don't feel obliged to add them yourself and
|
108 | (b) I'm happy to reevaluate their usage.
|
109 |
|
110 | Bunyan shall have categories of [issue
|
111 | labels](https://github.com/trentm/node-bunyan/labels) named "$category-$value".
|
112 | An issue should have max *one* label from each set. Users of Google Code's
|
113 | dearly departed issue tracker may remember this kind of thing. This is a
|
114 | poorman's version of structured issue tracker metadata.
|
115 |
|
116 | I'm inclined to *not* do priorities right now. *Possibly* we'll use GitHub
|
117 | milestones to basically set targets for upcoming releases. But otherwise my
|
118 | sense is that for smaller OSS projects, assigning prios will get in the way.
|
119 | If people would think it helpful, I'd consider "Difficulty-" or "Experience-"
|
120 | categories (a la Rust's "E-" labels) to mark easier and intermediate tasks
|
121 | that someone interested but maybe not very familiar with Bunyan might want
|
122 | to tackle.
|
123 |
|
124 | For now, here are the various labels and their purpose:
|
125 |
|
126 | ### Meta
|
127 |
|
128 | - needstriage: Temporary label to help me do a single triage pass through all
|
129 | current open issues and PRs.
|
130 | See [#335](https://github.com/trentm/node-bunyan/issues/335)
|
131 | where I'm working through this.
|
132 |
|
133 | ### Type
|
134 |
|
135 | Color: green
|
136 |
|
137 | - Type-Unknown: If it is still unclear or undecided if an issue is an intended
|
138 | feature (perhaps arguing for better docs or examples to avoid confusion) or a
|
139 | bug, I will use this category.
|
140 | - Type-Question: Asking a question on Bunyan usage, about the project, etc.
|
141 | - Type-Bug: A bug in Bunyan's behaviour.
|
142 | - Type-Improvement: A new feature or other improvement.
|
143 | - Type-Doc: Issues with Bunyan's documentation.
|
144 | - Type-Task: A project task to be done.
|
145 |
|
146 | TODO: consider Type-Unknown for the "unclear if bug or feature" tickets.
|
147 |
|
148 | ### Component
|
149 |
|
150 | Color: blue
|
151 |
|
152 | - Component-Project: Project meta stuff like testing, linting, build, install,
|
153 | etc.
|
154 | - Component-CLI: The `bunyan` command-line tool.
|
155 | - Component-Lib: catch-all for other library stuff
|
156 | - Component-LibRotation: The bunyan library's log rotation support.
|
157 | - Component-LibBrowser: Bunyan's handling/support for running in the browser.
|
158 | - Component-LibFlush: A separate component for collecting the tickets related
|
159 | to closing/flushing bunyan streams on process shutdown.
|
160 |
|
161 | The point of components is to find like issues to help with reference, search
|
162 | and resolving them. If no component fits an issue/PR, then don't add a label.
|
163 |
|
164 | ### Resolution
|
165 |
|
166 | Color: red
|
167 |
|
168 | - Resolution-WontFix
|
169 | - Resolution-Duplicate
|
170 | - Resolution-Fixed: Also used to indicate "doc written", "question answered",
|
171 | "feature implemented".
|
172 | - Resolution-CannotRepro: After some reasonable attempt by maintainers to
|
173 | reproduce a bug report, I want it to be non-controversial to close it
|
174 | and mark it with this. If given more info by someone able to repro, we
|
175 | can happy re-open issues.
|
176 |
|
177 | ### Experience
|
178 |
|
179 | Color: yellow
|
180 |
|
181 | - Experience-Easy: Relatively little experience with node-bunyan should be
|
182 | required to complete this issue.
|
183 | - Experience-NeedsTest: Typically added to an issue or PR that needs a test
|
184 | case. Someone familiar enough with node-bunyan's test suite could tackle this.
|
185 | - Experience-Hard: At a guess, this is a thorny issue that requires known
|
186 | node-bunyan well, knowing node.js well, requires design review or all of
|
187 | these.
|
188 |
|
189 | One of the "Experience-\*" labels can optionally be put on an issue or PR to
|
190 | indicate what kind of experience a contributor would need with node-bunyan
|
191 | (and/or node.js) to complete it. For example, if you're looking for somewhere to
|
192 | start, check out the [Experience-Easy][Experience-Easy] tag. This category idea
|
193 | is borrowed from [rust's E-\* labels][rust-issue-triage].
|
194 |
|
195 | [Experience-Easy]: https://github.com/trentm/node-bunyan/issues?q=is%3Aopen+is%3Aissue+label%3AExperience-Easy
|
196 | [rust-issue-triage]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#issue-triage
|
197 |
|
198 |
|
199 | ## Acknowledgements
|
200 |
|
201 | Anything good about this document is thanks to inspiration from
|
202 | [rust](https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md) and, more
|
203 | recently
|
204 | [terraform](https://github.com/hashicorp/terraform/blob/master/CONTRIBUTING.md).
|
205 | Anything bad about it, is my fault.
|