xref: /trafficserver/CONTRIBUTING.md (revision 924f15cb)
1Contributing to Apache Traffic Server
2=====================================
3
4All contributions to the **ATS** project should be done via a Github Pull
5Request (aka _PR_). If you are having an issue, but no code available yet, you
6should file a Github Issue instead, which later will be linked to a new _PR_.
7
8In 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
10Github workflow as agreed upon.
11
12
13New Issues process replacing old Jira
14-------------------------------------
15
161. 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
212. 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
253. 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
31Making a good PR or Issue
32-------------------------
33
34Since Github _PRs_ and _Issues_ are now our primary way of tracking both code
35changes and outstanding issues, it's important the we wall play nicely. Here
36are a few simple rules to follow:
37
381. Always branch off the master branch, unless you are requesting a subsequent
39   backport _PR_.
40
412. Make the subject line short (< 50 characters), but reasonably descriptive.
42
433. When filing a _PR_, without a previous _Issue_ describing the problem,
44   please write something explaining the problem as part of the Description.
45
464. 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
495. Make sure you set the appropriate _Milesstone_, _Labels_, _Assignees_ and
50   _Reviewers_.
51
526. If the _PR_ is a backport, or intended to be backported, please make sure to
53   add the **Backport** label.
54
557. If the _PR_ is a Work-In-Progress, and not ready to commit, mark it with the
56   **WIP** label.
57
588. 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
619. When making backports, make sure you mark the _PR_ for the appropriate
62   Github branch (e.g. **6.2.x**).
63
6410. 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
68Merging a PR
69------------
70
71Only committers can merge a _PR_ (obviously), and any committer is allowed to
72merge 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
88Miscellaneous
89-------------
90
91Once your Github branch has been merged, it is safe to delete it from your
92private repository.
93