|
1 | 1 | Contributing to Apache Traffic Server |
| 2 | +===================================== |
| 3 | + |
| 4 | +All contributions to the **ATS** project should be done via a Github Pull |
| 5 | +Request (aka _PR_). If you are having an issue, but no code available yet, you |
| 6 | +should file a Github Issue instead, which later will be linked to a new _PR_. |
| 7 | + |
| 8 | +In general, all changes that are to be committed should have a Github |
| 9 | +_PR_. There are some reasonable exceptions to this, but we should stick to the |
| 10 | +Github workflow as agreed upon. |
| 11 | + |
| 12 | + |
| 13 | +New Issues process replacing old Jira |
2 | 14 | ------------------------------------- |
| 15 | + |
| 16 | +1. If there is an issue/feature, an existing Jira Ticket, and no code, then |
| 17 | + create a Github _Issue_. Copy the relevant information into the Github |
| 18 | + _Issue_ and request the Jira Ticket to be closed. Hopefully this use case |
| 19 | + won’t happen very often. |
| 20 | + |
| 21 | +2. If there is an issue/feature and no code, then create a Github _Issue_. |
| 22 | + When there is code later, create a Github Pull Request and reference the |
| 23 | + Github _Issue_. |
| 24 | + |
| 25 | +3. If there is an issue/feature and code, then create a Github Pull Request. |
| 26 | + If there is an existing Jira Ticket or Github _Issue_ refer to the Ticket |
| 27 | + or _Issue_ in the _PR_. Creating a Github _Issue_ is not required for a |
| 28 | + Github Pull Request. |
| 29 | + |
| 30 | + |
| 31 | +Making a good PR or Issue |
| 32 | +------------------------- |
| 33 | + |
| 34 | +Since Github _PRs_ and _Issues_ are now our primary way of tracking both code |
| 35 | +changes and outstanding issues, it's important the we wall play nicely. Here |
| 36 | +are a few simple rules to follow: |
| 37 | + |
| 38 | +1. Always branch off the master branch, unless you are requesting a subsequent |
| 39 | + backport _PR_. |
| 40 | + |
| 41 | +2. Make the subject line short (< 50 characters), but reasonably descriptive. |
| 42 | + |
| 43 | +3. When filing a _PR_, without a previous _Issue_ describing the problem, |
| 44 | + please write something explaining the problem as part of the Description. |
| 45 | + |
| 46 | +4. When filing an _Issue_, you should of course describe the problem, as well |
| 47 | + as any details such as platform, versions of software etc. used. |
| 48 | + |
| 49 | +5. Make sure you set the appropriate _Milesstone_, _Labels_, _Assignees_ and |
| 50 | + _Reviewers_. |
| 51 | + |
| 52 | +6. If the _PR_ is a backport, or intended to be backported, please make sure to |
| 53 | + add the **Backport** label. |
| 54 | + |
| 55 | +7. If the _PR_ is a Work-In-Progress, and not ready to commit, mark it with the |
| 56 | + **WIP** label. |
| 57 | + |
| 58 | +8. Make sure you run **clang-format** before making the _PR_. This is easiest |
| 59 | + done with e.g. "make clang-format", which works on OSX and Linux. |
| 60 | + |
| 61 | +9. When making backports, make sure you mark the _PR_ for the appropriate |
| 62 | + Github branch (e.g. **6.2.x**). |
| 63 | + |
| 64 | +10. If you are making backports to an LTS branch, remember that the job of |
| 65 | + merging such a _PR_ is the duty of the release manager. |
| 66 | + |
| 67 | + |
| 68 | +Merging a PR |
| 69 | +------------ |
| 70 | + |
| 71 | +Only committers can merge a _PR_ (obviously), and any committer is allowed to |
| 72 | +merge any _PR_ after review. A few requirements before merging must be met: |
| 73 | + |
| 74 | +* Never, _ever_, merge a _PR_ which did not pass all the Jenkins build jobs! |
| 75 | + |
| 76 | +* Make sure all attributes on the _PR_ and issue is satisfied, such as |
| 77 | + Milestone and Labels. |
| 78 | + |
| 79 | +* Only merge a _PR_ that have at least one review approval, and no pending |
| 80 | + requested changes. |
| 81 | + |
| 82 | +* Make sure the _PR_ is for the _master_ branch, only the RM should merge |
| 83 | + backport requested for her or his release branch. |
| 84 | + |
| 85 | +* If there is also an open _Issue_ associated with the _PR_, make sure to |
| 86 | + close the _Issue_ as well. |
| 87 | + |
| 88 | +Miscellaneous |
| 89 | +------------- |
| 90 | + |
| 91 | +Once your Github branch has been merged, it is safe to delete it from your |
| 92 | +private repository. |
0 commit comments