Skip to content

Commit 0070857

Browse files
jspaaksjspaaks
authored
Merge pull request #191 from NLeSC/82-githooks
Add pre-commit githook, add README.dev.rst in generated package
2 parents b8ce771 + c129cc0 commit 0070857

3 files changed

Lines changed: 194 additions & 0 deletions

File tree

‎{{cookiecutter.project_name}}/.githooks/pre-commit‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
#!/bin/sh
2+
3+
echo "Script $0 triggered ..."
4+
5+
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
6+
echo "Starting prospector analysis using configuration from .prospector.yml..."
7+
8+
# quietly run prospector
9+
prospector 1>/dev/null
10+
11+
# use return code to abort commit if necessary
12+
if [ $? != "0" ]; then
13+
echo "Commit aborted. Run 'prospector' to see the errors."
14+
exit 1
15+
fi
16+
17+
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
18+
echo "Starting isort analysis using configuration from setup.cfg..."
19+
20+
# recursively run isort on {{ cookiecutter.package_name }}/ directory, don't try to automatically fix anything
21+
isort --recursive --check-only {{ cookiecutter.package_name }}
22+
23+
if [ $? != "0" ]; then
24+
echo "Commit aborted."
25+
echo " Run 'isort --recursive --check-only --diff {{ cookiecutter.package_name }}' to see what's wrong."
26+
echo " Run 'isort --recursive {{ cookiecutter.package_name }}' to let isort fix problems automatically."
27+
exit 1
28+
fi
29+
30+
echo "Pre-commit checks completed successfully."
31+
exit 0

‎{{cookiecutter.project_name}}/README.dev.rst‎

Lines changed: 160 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,160 @@
1+
``{{ cookiecutter.package_name }}`` developer documentation
2+
=====================================
3+
4+
If you're looking for user documentation, go `here <README.md>`_.
5+
6+
|
7+
|
8+
9+
Development install
10+
-------------------
11+
12+
.. code:: shell
13+
14+
# Create a virtual environment, e.g. with
15+
python3 -m venv env
16+
17+
# activate virtual environment
18+
source env/bin/activate
19+
20+
# make sure to have a recent version of pip and setuptools
21+
pip install --upgrade pip setuptools
22+
23+
# (from the project root directory)
24+
# install {{ cookiecutter.package_name }} as an editable package
25+
pip install --no-cache-dir --editable .
26+
# install development dependencies
27+
pip install --no-cache-dir --editable .[dev]
28+
29+
Afterwards check that the install directory is present in the ``PATH``
30+
environment variable.
31+
32+
Running the tests
33+
-----------------
34+
35+
Running the tests requires an activated virtual environment with the development tools installed.
36+
37+
.. code:: shell
38+
39+
# unit tests
40+
pytest
41+
pytest tests/
42+
43+
Running linters locally
44+
-----------------------
45+
For linting we will use [prospector](https://pypi.org/project/prospector/) and to sort imports we will use [isort](https://pycqa.github.io/isort/).
46+
Running the linters requires an activated virtual environment with the development tools installed.
47+
48+
.. code:: shell
49+
50+
# linter
51+
prospector
52+
53+
# recursively check import style for the {{ cookiecutter.package_name }} module only
54+
isort --recursive --check-only {{ cookiecutter.package_name }}
55+
56+
# recursively check import style for the {{ cookiecutter.package_name }} module only and show
57+
# any proposed changes as a diff
58+
isort --recursive --check-only --diff {{ cookiecutter.package_name }}
59+
60+
# recursively fix import style for the {{ cookiecutter.package_name }} module only
61+
isort --recursive {{ cookiecutter.package_name }}
62+
63+
You can enable automatic linting with ``prospector`` and ``isort`` on commit by enabling the git hook from
64+
``.githooks/pre-commit``, like so:
65+
66+
.. code:: shell
67+
68+
git config --local core.hooksPath .githooks
69+
70+
Versioning
71+
----------
72+
73+
Bumping the version across all files is done with bump2version, e.g.
74+
75+
.. code:: shell
76+
77+
bump2version major
78+
bump2version minor
79+
bump2version patch
80+
81+
Making a release
82+
----------------
83+
84+
Preparation
85+
^^^^^^^^^^^
86+
87+
1. Update the ``CHANGELOG.md``
88+
2. Verify that the information in ``CITATION.cff`` is correct, and that ``.zenodo.json`` contains equivalent data
89+
3. Make sure the version has been updated.
90+
4. Run the unit tests with ``pytest tests/``
91+
92+
PyPI
93+
^^^^
94+
95+
In a new terminal, without an activated virtual environment or an `env` directory:
96+
97+
.. code:: shell
98+
99+
# prepare a new directory
100+
cd $(mktemp -d --tmpdir {{ cookiecutter.package_name }}.XXXXXX)
101+
102+
# fresh git clone ensures the release has the state of origin/main branch
103+
git clone {{ cookiecutter.repository }} .
104+
105+
# prepare a clean virtual environment and activate it
106+
python3 -m venv env
107+
source env/bin/activate
108+
109+
# make sure to have a recent version of pip and setuptools
110+
pip install --upgrade pip setuptools
111+
112+
# install runtime dependencies and publishing dependencies
113+
pip install --no-cache-dir .
114+
pip install --no-cache-dir .[publishing]
115+
116+
# clean up any previously generated artefacts
117+
rm -rf {{ cookiecutter.package_name }}.egg-info
118+
rm -rf dist
119+
120+
# create the source distribution and the wheel
121+
python setup.py sdist bdist_wheel
122+
123+
# upload to test pypi instance (requires credentials)
124+
twine upload --repository-url https://test.pypi.org/legacy/ dist/*
125+
Visit https://test.pypi.org/project/{{cookiecutter.package_name}} and verify that your package was uploaded successfully.
126+
Keep the terminal open, we'll need it later.
127+
128+
In a new terminal, without an activated virtual environment or an `env` directory:
129+
130+
.. code:: shell
131+
132+
cd $(mktemp -d --tmpdir {{ cookiecutter.package_name }}-test.XXXXXX)
133+
134+
# prepare a clean virtual environment and activate it
135+
python3 -m venv env
136+
source env/bin/activate
137+
138+
# make sure to have a recent version of pip and setuptools
139+
pip install --upgrade pip setuptools
140+
141+
# install from test pypi instance:
142+
python3 -m pip -v install --no-cache-dir \
143+
--index-url https://test.pypi.org/simple/ \
144+
--extra-index-url https://pypi.org/simple {{ cookiecutter.package_name }}
145+
146+
Check that the package works as it should when installed from pypitest.
147+
148+
Then upload to pypi.org with:
149+
150+
.. code:: shell
151+
152+
# Back to the first terminal,
153+
# FINAL STEP: upload to PyPI (requires credentials)
154+
twine upload dist/*
155+
156+
GitHub
157+
^^^^^^
158+
159+
Don't forget to also make a release on GitHub. If your repository uses the GitHub-Zenodo integration this will also
160+
trigger Zenodo into making a snapshot of your repository and sticking a DOI on it.

‎{{cookiecutter.project_name}}/setup.cfg‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,9 @@ dev =
5757
sphinx
5858
sphinx_rtd_theme
5959
recommonmark
60+
publishing =
61+
twine
62+
wheel
6063

6164
[coverage:run]
6265
branch = True

0 commit comments

Comments
 (0)