|
1 | | -## Maintainers Guide |
| 1 | +# Maintainers Guide |
2 | 2 |
|
3 | | -This guide is intended for maintainers — anybody with commit access to one or more Developer Technology repositories. |
| 3 | +This guide is intended for maintainers - anybody with commit access to one or |
| 4 | +more Code Pattern repositories. |
4 | 5 |
|
5 | | -## Methodology: |
| 6 | +## Methodology |
6 | 7 |
|
7 | | -A master branch. This branch MUST be releasable at all times. Commits and merges against this branch MUST contain only bugfixes and/or security fixes. Maintenance releases are tagged against master. |
| 8 | +This repository does not have a traditional release management cycle, but |
| 9 | +should instead be maintained as as a useful, working, and polished reference at |
| 10 | +all times. While all work can therefore be focused on the master branch, the |
| 11 | +quality of this branch should never be compromised. |
8 | 12 |
|
9 | | -A develop branch. This branch contains your proposed changes, |
10 | | - |
11 | | -The remainder of this document details how to merge pull requests to the repositories. |
| 13 | +The remainder of this document details how to merge pull requests to the |
| 14 | +repositories. |
12 | 15 |
|
13 | 16 | ## Merge approval |
14 | 17 |
|
15 | | -The project maintainers use LGTM (Looks Good To Me) in comments on the code review to |
16 | | -indicate acceptance. A change requires LGTMs from two of the members of the [si-journey-admins](https://github.com/orgs/IBM/teams/si-journey-admins) team. If the code is written by a member, the change only requires one more LGTM. |
| 18 | +The project maintainers use LGTM (Looks Good To Me) in comments on the pull |
| 19 | +request to indicate acceptance prior to merging. A change requires LGTMs from |
| 20 | +two project maintainers. If the code is written by a maintainer, the change |
| 21 | +only requires one additional LGTM. |
17 | 22 |
|
18 | 23 | ## Reviewing Pull Requests |
19 | 24 |
|
20 | | -We recommend reviewing pull requests directly within GitHub. This allows a public commentary on changes, providing transparency for all users. When providing feedback be civil, courteous, and kind. Disagreement is fine, so long as the discourse is carried out politely. If we see a record of uncivil or abusive comments, we will revoke your commit privileges and invite you to leave the project. |
| 25 | +We recommend reviewing pull requests directly within GitHub. This allows a |
| 26 | +public commentary on changes, providing transparency for all users. When |
| 27 | +providing feedback be civil, courteous, and kind. Disagreement is fine, so long |
| 28 | +as the discourse is carried out politely. If we see a record of uncivil or |
| 29 | +abusive comments, we will revoke your commit privileges and invite you to leave |
| 30 | +the project. |
21 | 31 |
|
22 | 32 | During your review, consider the following points: |
23 | 33 |
|
24 | | -## Does the change have impact? |
25 | | - |
26 | | -While fixing typos is nice as it adds to the overall quality of the project, merging a typo fix at a time can be a waste of effort. (Merging many typo fixes because somebody reviewed the entire component, however, is useful!) Other examples to be wary of: |
| 34 | +### Does the change have positive impact? |
27 | 35 |
|
28 | | -Changes in variable names. Ask whether or not the change will make understanding the code easier, or if it could simply a personal preference on the part of the author. |
| 36 | +Some proposed changes may not represent a positive impact to the project. Ask |
| 37 | +whether or not the change will make understanding the code easier, or if it |
| 38 | +could simply be a personal preference on the part of the author (see |
| 39 | +[bikeshedding](https://en.wiktionary.org/wiki/bikeshedding)). |
29 | 40 |
|
30 | | -Essentially: feel free to close issues that do not have impact. |
| 41 | +Pull requests that do not have a clear positive impact should be closed without |
| 42 | +merging. |
31 | 43 |
|
32 | | -## Do the changes make sense? |
| 44 | +### Do the changes make sense? |
33 | 45 |
|
34 | | -If you do not understand what the changes are or what they accomplish, ask the author for clarification. Ask the author to add comments and/or clarify test case names to make the intentions clear. |
| 46 | +If you do not understand what the changes are or what they accomplish, ask the |
| 47 | +author for clarification. Ask the author to add comments and/or clarify test |
| 48 | +case names to make the intentions clear. |
35 | 49 |
|
36 | | -At times, such clarification will reveal that the author may not be using the code correctly, or is unaware of features that accommodate their needs. If you feel this is the case, work up a code sample that would address the issue for them, and feel free to close the issue once they confirm. |
| 50 | +At times, such clarification will reveal that the author may not be using the |
| 51 | +code correctly, or is unaware of features that accommodate their needs. If you |
| 52 | +feel this is the case, work up a code sample that would address the pull |
| 53 | +request for them, and feel free to close the pull request once they confirm. |
37 | 54 |
|
38 | | -## Is this a new feature? If so: |
| 55 | +### Does the change introduce a new feature? |
39 | 56 |
|
40 | | -Does the issue contain narrative indicating the need for the feature? If not, ask them to provide that information. Since the issue will be linked in the changelog, this will often be a user's first introduction to it. |
| 57 | +For any given pull request, ask yourself "is this a new feature?" If so, does |
| 58 | +the pull request (or associated issue) contain narrative indicating the need |
| 59 | +for the feature? If not, ask them to provide that information. |
41 | 60 |
|
42 | | -Are new unit tests in place that test all new behaviors introduced? If not, do not merge the feature until they are! |
43 | | -Is documentation in place for the new feature? (See the documentation guidelines). If not do not merge the feature until it is! |
44 | | -Is the feature necessary for general use cases? Try and keep the scope of any given component narrow. If a proposed feature does not fit that scope, recommend to the user that they maintain the feature on their own, and close the request. You may also recommend that they see if the feature gains traction amongst other users, and suggest they re-submit when they can show such support. |
| 61 | +Are new unit tests in place that test all new behaviors introduced? If not, do |
| 62 | +not merge the feature until they are! Is documentation in place for the new |
| 63 | +feature? (See the documentation guidelines). If not do not merge the feature |
| 64 | +until it is! Is the feature necessary for general use cases? Try and keep the |
| 65 | +scope of any given component narrow. If a proposed feature does not fit that |
| 66 | +scope, recommend to the user that they maintain the feature on their own, and |
| 67 | +close the request. You may also recommend that they see if the feature gains |
| 68 | +traction among other users, and suggest they re-submit when they can show such |
| 69 | +support. |
0 commit comments