|
| 1 | +# Contributor Guide |
| 2 | + |
| 3 | +## Open Discussion |
| 4 | + |
| 5 | +The most important part of an open source project is *open discussion*. If a developer, user, or other contributor has |
| 6 | +a question, comment, suggestion, or concern about any part of this project, **please speak up**: create an issue or add |
| 7 | +a comment to an existing issue or pull request. |
| 8 | + |
| 9 | +This policy especially affects the emoji described below. Any user or contributor may freely use these symbols to |
| 10 | +clarify intent during discussions. Questions and concerns from first-time contributors matter just as much as questions |
| 11 | +and concerns from the original project developers. |
| 12 | + |
| 13 | +## License |
| 14 | + |
| 15 | +The code in this repository is licensed under the [Apache License, Version 2.0](LICENSE.md). |
| 16 | + |
| 17 | +## Labels |
| 18 | + |
| 19 | +This project uses many labels for categorizing issues and pull requests. |
| 20 | + |
| 21 | +| Label | Meaning on Issue | Meaning on Pull Request | |
| 22 | +| --- | --- | --- | |
| 23 | +| bug | The issue concerns a bug in the code | The issue concerns a bug in the code | |
| 24 | +| enhancement | The issue is an improvement to the code | The pull request is an improvement to the code | |
| 25 | +| question | The issue is a question | Normally not applicable (see comments if observed on a pull request) | |
| 26 | +| help wanted | The issue is currently being discussed, and a decision for implementation has not yet been decided | The pull request is waiting on code review(s) | |
| 27 | +| pull request | A pull request intended to address the issue has been created, but not yet merged | n/a | |
| 28 | +| do not merge | n/a | The pull request should not be merged at this time. This could indicate a work-in-progress, a problem in the implementation code, or cases where the pull request depends on (is blocked by) another issue or pull request which has not been addressed. | |
| 29 | +| in progress | A developer is currently working on the issue | A developer is currently making updates to the code in the pull request | |
| 30 | +| fixed | The issue has been resolved | The pull request describes a new issue (i.e. no separate issue exists), and the content of the pull request was merged to fix the issue | |
| 31 | +| duplicate | Another issue or pull request contains the original report for this topic | Another pull request was submitted to correct the issue. This is generally only applied to pull requests after another pull request to correct the issue is merged. | |
| 32 | +| wontfix | The issue will not be corrected. The current behavior could be by design, out of scope, or cannot be changed due to the breaking changes policy for the project (see comments for details). | The pull request will not be merged due to a fundamental issue (see description for this label on issues) | |
| 33 | + |
| 34 | +## Emoji |
| 35 | + |
| 36 | +GitHub provides several emoji which can be included in many areas of the site, especially including comments on issues |
| 37 | +and pull requests. To reduce confusion during evaluation of a pull request, the following emoji convey special intent. |
| 38 | + |
| 39 | +* :question: (`:question:`) Indicates a question. This emoji comes with **no strings attached**, which means it's fine |
| 40 | + to simply answer the question in another comment without making any changes to code. |
| 41 | + |
| 42 | + In general, pull requests with an unanswered question will not be merged until *someone* addresses it. This could be |
| 43 | + the original creator of the issue or pull request, another contributor to the project, or even the person who asked |
| 44 | + the question. |
| 45 | + |
| 46 | +* :exclamation: (`:exclamation:`) Indicates a problem with the code which will need to be addressed before changes can |
| 47 | + be merged into `master`. This *may* be accompanied by a specific suggestion for how to change the code. Any |
| 48 | + contributor is completely welcome to open a discussion regarding alternative solutions, even if the originally |
| 49 | + proposed change has already been made. |
| 50 | + |
| 51 | + Every active contributor to a project is likely to use the :exclamation: emoji (or similar) due to a simple |
| 52 | + misunderstanding or oversight in their evaluation. **This is absolutely fine.** If you notice a case like this, simply |
| 53 | + add a comment to clarify the intent and the exclamation can be considered resolved. |
| 54 | + |
| 55 | + Pull requests with an unresolved exclamation will not be merged until they are addressed by either a change in the |
| 56 | + code or a detailed explanation. While it is possible for code with an exclamation to be merged, this will usually only |
| 57 | + occur if *all* of the following conditions hold: |
| 58 | + |
| 59 | + * The rationale is fully and clearly explained |
| 60 | + * The code corrects an issue that is likely to affect users |
| 61 | + * All other proposed solutions are either too time-consuming to implement or are equally (or more) problematic |
| 62 | + |
| 63 | +* :bulb: (`:bulb:`) Indicates an idea or suggestion regarding a potential change in the code. These items will not |
| 64 | + necessarily block the inclusion of code into the `master` branch, especially in cases where suggestions are trivial |
| 65 | + and no other issues were found during code review. |
| 66 | + |
| 67 | + In certain trivial cases (e.g. a simple formatting change), a core contributor on the project may make the suggested |
| 68 | + change themselves in the process of merging a pull request. Like the :exclamation: emoji, :bulb: suggestions invite |
| 69 | + open discussion about alternative solutions from any contributor. |
0 commit comments