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
|
.. tags:: development
Contribute
==========
All contributions are welcome in ``sphinx-tags``! All contributors and
maintainers are expected to follow the `PSF Code of Conduct
<https://github.com/psf/community-code-of-conduct>`__.
If you want to point out existing problems or suggest enhancements to code or
documentation, please `open an issue on GitHub
<https://github.com/melissawm/sphinx-tags/issues>`__.
If you want to submit a Pull Request with a patch or new feature, make sure you
follow the guide below.
Pull request guidelines
-----------------------
1. **Set up your development environment**
After cloning this repo and activating a virtual environment manager such as
`venv` or `conda`, use
::
python -m pip install -e ".[dev,sphinx]"
To build the documentation locally, use
::
sphinx-build docs docs/_build/html
2. **Hack away!**
3. **Style checks**
``sphinx-tags`` uses `pre-commit <https://pre-commit.com/>`__, and code is
formatted according to `black <https://github.com/psf/black>`__. To make sure
your code conforms to this style, you can:
- Setup pre-commit for your local clone::
pre-commit install
- Run pre-commit::
pre-commit run --all
- Re-add any changed files to your staging area and run pre-commit again to
make sure any fixes are applied to your code.
4. **Test Coverage**
For any new or changed behavior, please add unit test coverage. See notes in
`conftest.py <https://github.com/melissawm/sphinx-tags/tree/main/test/conftest.py>`__
for details on testing setup.
To run tests, use::
pytest
5. **Commit your changes and send your pull request as usual.**
Releases
--------
``sphinx-tags`` uses `flit <https://github.com/pypa/flit>`__ to manage releases.
To cut a new release:
1. Make sure the version string in ``src/sphinx_tags/__init__.py`` is updated
with the release number you want.
2. Run ``git tag <version>``, and ``git push origin --tags`` to update the tags
on GitHub.
3. This will trigger a `GitHub Action <https://github.com/melissawm/sphinx-tags/actions>`__
that will build and publish the new release to PyPI. Verify that it completed
successfully.
4. A new `GitHub release <https://github.com/melissawm/sphinx-tags/releases>`__
will be created automatically. Update the release description as needed.
|
