Debian Codegraph @

.github/CONTRIBUTING.md

raw
1 # How To Contribute
2
3 Thank you for considering contributing to *service-identity*!
4 It's people like *you* who make it such a great tool for everyone.
5
6 This document intends to make contribution more accessible by codifying tribal knowledge and expectations.
7 Don't be afraid to open half-finished PRs, and ask questions if something is unclear!
8
9 Please note that this project is released with a Contributor [Code of Conduct](https://github.com/pyca/service-identity/blob/main/.github/CODE_OF_CONDUCT.md).
10 By participating in this project you agree to abide by its terms.
11 Please report any harm to [Hynek Schlawack] in any way you find appropriate.
12
13
14 ## Workflow
15
16 - No contribution is too small!
17 Please submit as many fixes for typos and grammar bloopers as you can!
18 - Try to limit each pull request to *one* change only.
19 - Since we squash on merge, it's up to you how you handle updates to the `main` branch.
20 Whether you prefer to rebase on `main` or merge `main` into your branch, do whatever is more comfortable for you.
21 - *Always* add tests and docs for your code.
22 This is a hard rule; patches with missing tests or documentation won't be merged.
23 - Make sure your changes pass our [CI].
24 You won't get any feedback until it's green unless you ask for it.
25 For the CI to pass, the coverage must be 100%.
26 If you have problems to test something, open anyway and ask for advice.
27 In some situations, we may agree to add an `# pragma: no cover`.
28 - Once you've addressed review feedback, make sure to bump the pull request with a short note, so we know you're done.
29 - Don’t break backwards-compatibility.
30
31
32 ## Local Development Environment
33
34 You can (and should) run our test suite using [*tox*].
35 However, you’ll probably want a more traditional environment as well.
36
37 First, create a virtual environment so you don't break your system-wide Python installation.
38 We recommend using the Python version from the `.python-version-default` file in project's root directory.
39
40 If you're using [*direnv*](https://direnv.net), you can automate the creation of a virtual environment with the correct Python version by adding the following `.envrc` to the project root after cloning the repository:
41
42 ```bash
43 layout python python$(cat .python-version-default)
44 ```
45
46 If you're using tools that understand `.python-version` files like [*pyenv*](https://github.com/pyenv/pyenv) does, you can make it a link to the `.python-version-default` file.
47
48 ---
49
50 [Create a fork](https://github.com/pyca/service-identity/fork) of the *service-identity* repository and clone it:
51
52 ```console
53 $ git clone [email protected]:YOU/service-identity.git
54 ```
55
56 Or if you prefer to use Git via HTTPS:
57
58 ```console
59 $ git clone https://github.com/YOU/service-identity.git
60 ```
61
62 > **Warning**
63 > - **Before** you start working on a new pull request, use the "*Sync fork*" button in GitHub's web UI to ensure your fork is up to date.
64 > - **Always create a new branch off `main` for each new pull request.**
65 > Yes, you can work on `main` in your fork and submit pull requests.
66 > But this will *inevitably* lead to you not being able to synchronize your fork with upstream and having to start over.
67
68 Change into the newly created directory and after activating a virtual environment, install an editable version of *service-identity* along with its tests requirements:
69
70 ```console
71 $ cd service-identity
72 $ python -Im pip install --upgrade pip wheel # PLEASE don't skip this step
73 $ python -Im pip install -e '.[dev]'
74 ```
75
76 At this point,
77
78 ```console
79 $ python -Im pytest
80 ```
81
82 When working on the documentation, use:
83
84 ```console
85 $ tox run -e docs-watch
86 ```
87
88 ... to watch your files and automatically rebuild when a file changes.
89 And use:
90
91 ```console
92 $ tox run -e docs
93 ```
94
95 ... to build it once and run our doctests.
96
97 The built documentation can then be found in `docs/_build/html/`.
98
99 ---
100
101 To avoid committing code that violates our style guide, we strongly advise you to install [*pre-commit*] and its hooks:
102
103 ```console
104 $ pre-commit install
105 ```
106
107 This is not strictly necessary, because our [*tox*] file contains an environment that runs:
108
109 ```console
110 $ pre-commit run --all-files
111 ```
112
113 But it's way more comfortable to run it locally and catch avoidable errors before pushing them to GitHub.
114
115
116 ## Code
117
118 - Obey [PEP 8](https://www.python.org/dev/peps/pep-0008/) and [PEP 257](https://www.python.org/dev/peps/pep-0257/).
119 We use the `"""`-on-separate-lines style for docstrings with [Napoleon](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html)-style API documentation:
120
121 ```python
122 def func(x: str, y: int) -> str:
123 """
124 Do something.
125
126 Args:
127 x: A very important parameter.
128
129 y:
130 Another important parameter but one that doesn't fit a line so
131 it already starts on the next one.
132
133 Raises:
134 Exception: When Something goes wrong.
135
136 Returns:
137 A very important return value.
138 """
139 ```
140
141 - If you add or change public APIs, tag the docstring using `.. versionadded:: 16.0.0 WHAT` or `.. versionchanged:: 16.2.0 WHAT`.
142
143 - We follow [PEP 8](https://peps.python.org/pep-0008/) as enforced by [Ruff](https://ruff.rs/) with a line length of 79 characters.
144 As long as you run our full [*tox*] suite before committing, or install our [*pre-commit*] hooks (ideally you'll do both – see [*Local Development Environment*](#local-development-environment) above), you won't have to spend any time on formatting your code at all.
145 If you don't, [CI] will catch it for you – but that seems like a waste of your time!
146
147
148 ## Tests
149
150 - Write your asserts as `expected == actual` to line them up nicely:
151
152 ```python
153 x = f()
154
155 assert 42 == x.some_attribute
156 assert "foo" == x._a_private_attribute
157 ```
158
159 - To run the test suite, all you need is a recent [*tox*].
160 It will ensure the test suite runs with all dependencies against all Python versions just as it will in our [CI].
161 - Write [good test docstrings](https://jml.io/pages/test-docstrings.html).
162 - If you've changed or added public APIs, please update our type stubs (files ending in `.pyi`).
163
164
165 ## Documentation
166
167 - We use [Markdown] everywhere except in `docs/api.rst` and docstrings.
168
169 - Use [semantic newlines] in [*reStructuredText*] and [Markdown] files (files ending in `.rst` and `.md`):
170
171 ```markdown
172 This is a sentence.
173 This is another sentence.
174 ```
175
176 - If you start a new section, add two blank lines before and one blank line after the header, except if two headers follow immediately after each other:
177
178 ```markdown
179 Last line of previous section.
180
181
182 ## Header of New Top Section
183
184 ### Header of New Section
185
186 First line of new section.
187 ```
188
189
190 ### Changelog
191
192 If your change is noteworthy, there needs to be a changelog entry in [`CHANGELOG.md`](https://github.com/pyca/service-identity/blob/main/CHANGELOG.md), so our users can learn about it!
193
194 - The changelog follows the [*Keep a Changelog*](https://keepachangelog.com/en/1.0.0/) standard.
195 Please add the best-fitting section if it's missing for the current release.
196 We use the following order: `Security`, `Removed`, `Deprecated`, `Added`, `Changed`, `Fixed`.
197 - As with other docs, please use [semantic newlines] in the changelog.
198 - Make the last line a link to your pull request.
199 You probably have to open it first to know the number.
200 - Wrap symbols like modules, functions, or classes into backticks so they are rendered in a `monospace font`.
201 - Wrap arguments into asterisks like in docstrings:
202 `Added new argument *an_argument*.`
203 - If you mention functions or other callables, add parentheses at the end of their names:
204 `service-identity.func()` or `service-identity.Class.method()`.
205 This makes the changelog a lot more readable.
206 - Prefer simple past tense or constructions with "now".
207 For example:
208
209 * Added `service-identity.func()`.
210 * `service-identity.func()` now doesn't crash the Large Hadron Collider anymore when passed the *foobar* argument.
211
212
213 #### Example entries
214
215 ```markdown
216 - Added `service-identity.func()`.
217 The feature really *is* awesome.
218 [#1](https://github.com/pyca/service-identity/pull/1)
219 ```
220
221 or:
222
223 ```markdown
224 - `service-identity.func()` now doesn't crash the Large Hadron Collider anymore when passed the *foobar* argument.
225 The bug really *was* nasty.
226 [#1](https://github.com/pyca/service-identity/pull/1)
227 ```
228
229
230 [CI]: https://github.com/pyca/service-identity/actions
231 [Hynek Schlawack]: https://hynek.me/about/
232 [*pre-commit*]: https://pre-commit.com/
233 [*tox*]: https://tox.wiki/
234 [semantic newlines]: https://rhodesmill.org/brandon/2012/one-sentence-per-line/
235 [*reStructuredText*]: https://www.sphinx-doc.org/en/stable/usage/restructuredtext/basics.html
236 [Markdown]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax