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
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
.. include:: ../../.github/CONTRIBUTING.rst
First-time setup
~~~~~~~~~~~~~~~~
- You need to install `Python`_ 3 which is required for building docs.
For example, Python 3.11.
Then, `create and activate a virtual environment`_.
And install `tox`_.
- `Install git`_
- `Configure git`_:
1. Please, identify yourself::
$ git config --global user.name "firstname lastname"
$ git config --global user.email yourname@example.com
* Use the address bound to your GitHub account so that the commits would be linked to your profile.
2. Choose an editor for Git::
$ git config --global core.editor vim
- Create and log in to a `GitHub`_ account
- `Fork`_ Cheroot to your GitHub account by clicking the Fork button
- `Clone`_ your fork locally::
$ git clone https://github.com/{username}/cheroot
$ cd cheroot
* Also, you can `clone`_ fork using `ssh`_::
$ git clone git@github.com:{username}/cheroot.git
$ cd cheroot
- To create a new `branch`_ and switch to it::
$ git checkout -b patch/some_fix
.. _create and activate a virtual environment: https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments
.. _Python: https://www.python.org/
.. _Install git: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
.. _Configure git: https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup
.. _GitHub: http://github.com
.. _Fork: https://help.github.com/articles/fork-a-repo/
.. _Clone: https://help.github.com/articles/cloning-a-repository/
.. _ssh: https://help.github.com/articles/connecting-to-github-with-ssh/
.. _branch: https://www.atlassian.com/git/tutorials/using-branches
Write your code
~~~~~~~~~~~~~~~
- Please, use `PEP 8`_
.. _PEP 8: https://pep8.org/
Once you finished coding, you are recommended to do the following steps:
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
- Run tests with `tox`_
Run one test with Python3.11::
$ tox -e py311 -- cheroot/test/test_name.py
**``tox``** — Run all tests using the Python version where `python` command
currently points to which is specified in ``tox`` settings::
envlist = python
minversion = 3.21.0
Run linters and all tests against several Python interpreters::
$ tox -e pre-commit,py310,py37 # etc.
- Run the `pre-commit`_ linting suite::
$ tox -e pre-commit
- `git add`_ your files
- `Write good`_ `commit messages`_ when checking in your changes to Git
- `Push`_ and `create a pull request`_
.. _tox: https://tox.readthedocs.io/en/latest/
.. _pre-commit: https://github.com/pre-commit/pre-commit
.. _git add: https://git-scm.com/docs/git-add
.. _Write good: https://chris.beams.io/posts/git-commit/
.. _commit messages: https://git-scm.com/docs/git-commit
.. _Push: https://git-scm.com/docs/git-push
.. _create a pull request: https://help.github.com/articles/creating-a-pull-request/
Building the docs
~~~~~~~~~~~~~~~~~
To build the docs from a checked out source, run::
$ tox -e build-docs
Open the documentation:
.. tabs::
.. tab:: GNU/Linux
::
$ xdg-open build/html/index.html
.. tab:: macOS
::
$ open build/html/index.html
.. tab:: Windows
Please, open ``build/html/index.html`` in your browser.
Also, one can serve docs using a built-in static files server.
This is preferable because of possible CSRF issues.::
$ python3 -m http.server --directory build/html/ 8000
After that, you can open `http://localhost:8000/ <http://localhost:8000/>`_ in your browser.
Read more about `Sphinx`_.
.. _Sphinx: https://www.sphinx-doc.org
.. include:: ../changelog-fragments.d/README.rst
|
