UNPKG

8.95 kBMarkdownView Raw
1# Contributing to node-bunyan
2
3Thanks for using node-bunyan and for considering contributing to it! Or perhaps
4you are just here to get a sniff for what is going on with node-bunyan
5development.
6
7
8## How you can help
9
10If 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
36In the hope that it makes it easier to get PRs into Bunyan, here is my biased
37list 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
39provide 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
105The point of issue labeling for node-bunyan is to help answer "what should be
106worked on now? what can be left for later?" I don't want issue labelling to
107become 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
110Bunyan shall have categories of [issue
111labels](https://github.com/trentm/node-bunyan/labels) named "$category-$value".
112An issue should have max *one* label from each set. Users of Google Code's
113dearly departed issue tracker may remember this kind of thing. This is a
114poorman's version of structured issue tracker metadata.
115
116I'm inclined to *not* do priorities right now. *Possibly* we'll use GitHub
117milestones to basically set targets for upcoming releases. But otherwise my
118sense is that for smaller OSS projects, assigning prios will get in the way.
119If people would think it helpful, I'd consider "Difficulty-" or "Experience-"
120categories (a la Rust's "E-" labels) to mark easier and intermediate tasks
121that someone interested but maybe not very familiar with Bunyan might want
122to tackle.
123
124For 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
135Color: 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
146TODO: consider Type-Unknown for the "unclear if bug or feature" tickets.
147
148### Component
149
150Color: 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
161The point of components is to find like issues to help with reference, search
162and resolving them. If no component fits an issue/PR, then don't add a label.
163
164### Resolution
165
166Color: 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
179Color: 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
189One of the "Experience-\*" labels can optionally be put on an issue or PR to
190indicate 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
192start, check out the [Experience-Easy][Experience-Easy] tag. This category idea
193is 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
201Anything good about this document is thanks to inspiration from
202[rust](https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md) and, more
203recently
204[terraform](https://github.com/hashicorp/terraform/blob/master/CONTRIBUTING.md).
205Anything bad about it, is my fault.