1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
|
# Contributing
Thank you for your interest in contributing to installer. We welcome all
contributions and greatly appreciate your effort!
## Code of Conduct
Everyone interacting in the pip project's codebases, issue trackers, chat rooms,
and mailing lists is expected to follow the [PyPA Code of Conduct][coc].
[coc]: https://www.pypa.io/en/latest/code-of-conduct/
## Bugs and Feature Requests
If you have found any bugs or would like to request a new feature, please do
check if there is an existing issue already filed for the same, in the project's
GitHub [issue tracker]. If not, please file a new issue.
If you want to help out by fixing bugs, choose an open issue in the [issue
tracker] to work on and claim it by posting a comment saying "I would like to
work on this.". Feel free to ask any doubts in the issue thread.
While working on implementing the feature, please go ahead and file a pull
request. Filing a pull request early allows for getting feedback as early as
possible.
[issue tracker]: https://github.com/pradyunsg/installer/issues
## Pull Requests
Pull Requests should be small to facilitate easier review. Keep them
self-contained, and limited in scope. Studies have shown that review quality
falls off as patch size grows. Sometimes this will result in many small PRs to
land a single large feature.
Checklist:
1. All pull requests _must_ be made against the `main` branch.
2. Include tests for any functionality you implement. Any contributions helping
improve existing tests are welcome.
3. Update documentation as necessary and provide documentation for any new
functionality.
## Development
[nox] is used to simplify invocation and usage of all the tooling used during
development.
[nox]: https://github.com/theacodes/nox
### Code Convention
This codebase uses the following tools for enforcing a code convention:
- [black] for code formatting
- [isort] for import sorting
- [mypy] for static type checking
- [pre-commit] for managing all the linters
To run all the linters:
```sh-session
$ nox -s lint
```
[black]: https://github.com/psf/black
[isort]: https://github.com/timothycrosley/isort
[mypy]: https://github.com/python/mypy
[pre-commit]: https://pre-commit.com/
### Testing
This codebase uses [pytest] as the testing framework and [coverage] for
generating code coverage metrics. We enforce a strict 100% test coverage policy
for all code contributions, although [code coverage isn't everything].
To run all the tests:
```sh-session
$ nox -s test
```
nox has been configured to forward any additional arguments it is given to
pytest. This enables the use of [pytest's rich CLI].
```
$ # Using file name
$ nox -s test -- tests/*.py
$ # Using markers
$ nox -s test -- -m unit
$ # Using keywords
$ nox -s test -- -k "basic"
```
[pytest]: https://docs.pytest.org/en/stable/
[coverage]: https://coverage.readthedocs.io/
[code coverage isn't everything]:
https://bryanpendleton.blogspot.com/2011/02/code-coverage-isnt-everything-but-its.html
[pytest's rich cli]:
https://docs.pytest.org/en/latest/usage.html#specifying-tests-selecting-tests
### Documentation
This codebase uses [Sphinx] for generating documentation.
To build the documentation:
```sh-session
$ nox -s docs
```
[sphinx]: https://www.sphinx-doc.org/
|
