| 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 |