|
| 1 | +# Maintainer's guide |
| 2 | + |
| 3 | +This guide is intended for maintainers — anybody with commit access to this repository. |
| 4 | + |
| 5 | +*Note:* This guide is a living standard; |
| 6 | +that is, it is meant to *describe* the project's maintenance practices, |
| 7 | +rather than *prescribe* them. |
| 8 | +As a maintainer, you're expected to refer to it for clarifications |
| 9 | +about the collaborative workflows of the project, |
| 10 | +but also to propose changes to it |
| 11 | +that you feel would make it more useful |
| 12 | +as a guideline for current and future maintainers. |
| 13 | + |
| 14 | +We use the [git flow methodology](http://nvie.com/posts/a-successful-git-branching-model/) for |
| 15 | +managing this repository. At a glance, this means: |
| 16 | + |
| 17 | +- a **master** branch. This branch MUST be releasable at all times. Commits and merges against |
| 18 | + this branch MUST contain only bugfixes and/or security fixes. Maintenance releases are tagged |
| 19 | + against master. |
| 20 | +- a **develop** branch. This branch contains *new features*, and will either become the next minor |
| 21 | + (feature) release or next major release. Typically, major releases are reserved for backwards |
| 22 | + *incompatible* changes, but can also be used to signal major new features. |
| 23 | + |
| 24 | +## I. Branch Naming Conventions |
| 25 | + |
| 26 | +- In addition to master and develop branches, these are the standards for features, fixes, chores and releases, |
| 27 | + 1. **features** All feature branches must be created under **feat/**, |
| 28 | + 2. **bug-fixes** All fixes must be created under **fix/**, |
| 29 | + 3. **chores** Ad-hoc tasks that are not features, minor housekeeping, maintenance tasks should be created under **chores/** |
| 30 | + 4. Avoid branches being grouped under your usernames |
| 31 | + |
| 32 | +## II. Handling PRs |
| 33 | + |
| 34 | +- When creating a PR, you should: |
| 35 | + 1. Clearly describe the intent of the PR |
| 36 | + 2. Describe the solution in detail with links to the original issue and any related issues that it might fix or close. |
| 37 | + 3. GitHub Draft PRs are a great way to get CI or human feedback on work that isn't yet ready to merge. PRs can be created as drafts and converted to normal PRs once the CI passes. More information about GitHub Draft PRs: https://github.blog/2019-02-14-introducing-draft-pull-requests/ |
| 38 | + |
| 39 | + |
| 40 | +- PRs should be merged once they |
| 41 | + 1. **pass the automated tests** (GitHub Actions, CLA signing, etc.), |
| 42 | + 2. have the **review comments addressed**, |
| 43 | + 3. get **approved reviews by two maintainers**, (the second maintainer can merge immediately after approving) and |
| 44 | + 4. have been open for at least **24 hours** unless the changes are trivial |
| 45 | + |
| 46 | +- To merge a pull request, it must have at least: |
| 47 | + |
| 48 | + - one approval for simple documentation fixes |
| 49 | + - two approvals for everything else |
| 50 | + |
| 51 | +- When merging a PR, you should: |
| 52 | + |
| 53 | + 1. Use the **merge strategy that produces a clean Git history**: ["Squash and merge"](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-merges#squash-and-merge-your-pull-request-commits) commits and ensure the resulting commit message is: |
| 54 | + - descriptive |
| 55 | + - sentence case |
| 56 | + - If instead the PR author took the time to craft individual, informative messages for each commit, then use the `Rebase and merge` method,to honor that work and preserve the history of the changes. |
| 57 | + - For less clear-cut cases, a simple heuristic you can follow is that if there are more "dirty" commits than "clean" commits,then prefer squash, else do a rebase. |
| 58 | + |
| 59 | + 2. Ensure [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) are used in the PR. When properly annotated, the commit messages will automatically update the changelog. |
| 60 | + |
| 61 | + |
| 62 | +- If a PR fails to get a review from a second maintainer after a few days, the first maintainer should ping others for review. If it still lingers around for **over a week without a second maintainer’s approval**,the first maintainer can go ahead and merge it. |
| 63 | + |
| 64 | +- If the only issues holding up a merge are **trivial fixes** |
| 65 | + (typos, syntax errors, etc.), and the author doesn't respond in a day or two, |
| 66 | + **maintainers can make the necessary changes themselves**, |
| 67 | + and proceed with the merge process. |
| 68 | + |
| 69 | +- If a PR **stops getting feedback from the submitter** and is marked as stale |
| 70 | + by [probot-stale](../.github/workflows/stale.yml), |
| 71 | + any maintainer can choose to take over the PR |
| 72 | + and make the necessary changes to get the content ready for merging. |
| 73 | + |
| 74 | +- **Avoid merging your own PRs** unless approved by other maintainers. |
0 commit comments