The final section of the README is for if you want to get involved by making acode contribution.

To install in development mode, use the following:

$git clone git+https://github.com/cthoyt/pystow.git$cd pystow$uv --preview pip install -e.

Alternatively, install using pip:

$UV_PREVIEW=1 python3 -m pip install -e.

Note that this requires settingUV_PREVIEW mode enabled until the uv buildbackend becomes a stable feature.

This project usescruft to keep boilerplate (i.e., configuration, contributionguidelines, documentation configuration) up-to-date with the upstreamcookiecutter package. Install cruft with eitheruv tool install cruft orpython3 -m pip install cruft then run:

$cruft update

More info on Cruft's update command is availablehere.

After cloning the repository and installingtox withuv tool install tox --with tox-uv orpython3 -m pip install tox tox-uv, theunit tests in thetests/ folder can be run reproducibly with:

$tox -e py

Additionally, these tests are automatically re-run with each commit in aGitHub Action.

The documentation can be built locally using the following:

$git clone git+https://github.com/cthoyt/pystow.git$cd pystow$tox -e docs$open docs/build/html/index.html

The documentation automatically installs the package as well as thedocs extraspecified in thepyproject.toml.sphinx plugins liketexext can be added there. Additionally, they need to be added to theextensions list indocs/source/conf.py.

The documentation can be deployed toReadTheDocs usingthis guide. The.readthedocs.yml YAML file contains all the configurationyou'll need. You can also set up continuous integration on GitHub to check notonly that Sphinx can build the documentation in an isolated environment (i.e.,withtox -e docs-test) but also thatReadTheDocs can build it too.

1. Log in to ReadTheDocs with your GitHub account to install the integration athttps://readthedocs.org/accounts/login/?next=/dashboard/
2. Import your project by navigating tohttps://readthedocs.org/dashboard/importthen clicking the plus icon next to your repository
3. You can rename the repository on the next screen using a more stylized name(i.e., with spaces and capital letters)
4. Click next, and you're good to go!

Zenodo is a long-term archival system that assigns a DOIto each release of your package.

1. Log in to Zenodo via GitHub with this link:https://zenodo.org/oauth/login/github/?next=%2F. This brings you to a pagethat lists all of your organizations and asks you to approve installing theZenodo app on GitHub. Click "grant" next to any organizations you want toenable the integration for, then click the big green "approve" button. Thisstep only needs to be done once.
2. Navigate tohttps://zenodo.org/account/settings/github/, which lists all ofyour GitHub repositories (both in your username and any organizations youenabled). Click the on/off toggle for any relevant repositories. When youmake a new repository, you'll have to come back to this

After these steps, you're ready to go! After you make "release" on GitHub (stepsfor this are below), you can navigate tohttps://zenodo.org/account/settings/github/repository/cthoyt/pystow to see theDOI for the release and link to the Zenodo record for it.

You only have to do the following steps once.

1. Register for an account on thePython Package Index (PyPI)
2. Navigate tohttps://pypi.org/manage/account and make sure you have verifiedyour email address. A verification email might not have been sent by default,so you might have to click the "options" dropdown next to your address to getto the "re-send verification email" button
3. 2-Factor authentication is required for PyPI since the end of 2023 (see thisblog post from PyPI).This means you have to first issue account recovery codes, then set up2-factor authentication
4. Issue an API token fromhttps://pypi.org/manage/account/token

You have to do the following steps once per machine.

$uv tool install keyring$keyringset https://upload.pypi.org/legacy/ __token__$keyringset https://test.pypi.org/legacy/ __token__

Note that this deprecates previous workflows using.pypirc.

After installing the package in development mode and installingtox withuv tool install tox --with tox-uv orpython3 -m pip install tox tox-uv, runthe following from the console:

$tox -e finish

This script does the following:

1. Usesbump-my-version toswitch the version number in thepyproject.toml,CITATION.cff,src/pystow/version.py, anddocs/source/conf.py tonot have the-dev suffix
2. Packages the code in both a tar archive and a wheel usinguv build
3. Uploads to PyPI usinguv publish.
4. Push to GitHub. You'll need to make a release going with the commit where theversion was bumped.
5. Bump the version to the next patch. If you made big changes and want to bumpthe version by minor, you can usetox -e bumpversion -- minor after.

1. Navigate tohttps://github.com/cthoyt/pystow/releases/new to draft a newrelease
2. Click the "Choose a Tag" dropdown and select the tag corresponding to therelease you just made
3. Click the "Generate Release Notes" button to get a quick outline of recentchanges. Modify the title and description as you see fit
4. Click the big green "Publish Release" button

This will trigger Zenodo to assign a DOI to your release as well.