1# Contributing to Linkerd2 #
2
3:balloon: Thanks for your help improving the project!
4
5## Getting Help ##
6
7If you have a question about Linkerd2 or have encountered problems using it,
8start by [asking a question in the forums][discourse] or join us in the
9[#linkerd2 Slack channel][slack].
10
11## Developer Certificate of Origin ##
12
13To contribute to this project, you must agree to the Developer Certificate of
14Origin (DCO) for each commit you make. The DCO is a simple statement that you,
15as a contributor, have the legal right to make the contribution.
16
17See the [DCO](DCO) file for the full text of what you must agree to.
18
19### Option 1: commit message signoffs ###
20
21One way to signify that you agree to the DCO for a commit is to add a line to
22the git commit message:
23
24```txt
25Signed-off-by: Jane Smith <jane.smith@example.com>
26```
27
28In most cases, you can add this signoff to your commit automatically with the
29`-s` flag to `git commit`. You must use your real name and a reachable email
30address (sorry, no pseudonyms or anonymous contributions).
31
32### Option 2: public statement ###
33
34If you've already made the commits and don't want to engage in git shenanigans
35to retroactively apply the signoff as above, there is another option: leave a
36comment on the PR with the following statement: "I agree to the DCO for all the
37commits in this PR."
38
39Note that this option also requires that your commits are made under your real
40name and a reachable email address.
41
42If you use this approach, the DCO bot will still complain, but maintainers will
43override the DCO bot at merge time.
44
45### Option 3: very simple changes ###
46
47Changes that are trivial (e.g. spelling corrections, adding to ADOPTERS.md,
48one-word changes) do not require a DCO signoff. Maintainers should feel free to
49override the DCO bot for these changes.
50
51## Submitting a Pull Request ##
52
53Do you have an improvement?
54
551. Submit an [issue][issue] describing your proposed change.
562. We will try to respond to your issue promptly.
573. Fork this repo, develop and test your code changes. See the project's
58 [README](README.md) for further information about working in this repository.
594. Submit a pull request against this repo's `main` branch.
60 - Include instructions on how to test your changes.
61 - If you are making a change to the user interface (UI), include a
62 screenshot of the UI before and after your changes.
635. Your branch may be merged once all configured checks pass, including:
64 - The branch has passed tests in CI.
65 - A review from appropriate maintainers (see
66 [MAINTAINERS.md](MAINTAINERS.md) and [GOVERNANCE.md](GOVERNANCE.md))
67
68## Committing ##
69
70We prefer squash or rebase commits so that all changes from a branch are
71committed to main as a single commit. All pull requests are squashed when
72merged, but rebasing prior to merge gives you better control over the commit
73message.
74
75### Commit messages ###
76
77Finalized commit messages should be in the following format:
78
79```txt
80Subject
81
82Problem
83
84Solution
85
86Validation
87
88Fixes #[GitHub issue ID]
89```
90
91#### Subject ####
92
93- one line, <= 50 characters
94- describe what is done; not the result
95- use the active voice
96- capitalize first word and proper nouns
97- do not end in a period — this is a title/subject
98- reference the GitHub issue by number
99
100##### Examples #####
101
102```txt
103bad: server disconnects should cause dst client disconnects.
104good: Propagate disconnects from source to destination
105```
106
107```txt
108bad: support tls servers
109good: Introduce support for server-side TLS (#347)
110```
111
112#### Problem ####
113
114Explain the context and why you're making that change. What is the problem
115you're trying to solve? In some cases there is not a problem and this can be
116thought of as being the motivation for your change.
117
118#### Solution ####
119
120Describe the modifications you've made.
121
122If this PR changes a behavior, it is helpful to describe the difference between
123the old behavior and the new behavior. Provide before and after screenshots,
124example CLI output, or changed YAML where applicable.
125
126Describe any implementation changes which are particularly complex or
127unintuitive.
128
129List any follow-up work that will need to be done in a future PR and link to any
130relevant GitHub issues.
131
132#### Validation ####
133
134Describe the testing you've done to validate your change. Give instructions for
135reviewers to replicate your tests. Performance-related changes should include
136before- and after- benchmark results.
137
138[discourse]: https://discourse.linkerd.io/c/linkerd2
139[issue]: https://github.com/linkerd/linkerd2/issues/new
140[slack]: http://slack.linkerd.io/
View as plain text