Skip to content

Latest commit

 

History

History
101 lines (68 loc) · 3.07 KB

CONTRIBUTING.rst

File metadata and controls

101 lines (68 loc) · 3.07 KB
Raw

Contributing

If you find errors, omissions, inconsistencies or other things that need improvement, please create an issue or a pull request at https://github.com/sfstoolbox/sfs-python/. Contributions are always welcome!

Development Installation

Instead of pip-installing the latest release from PyPI, you should get the newest development version from Github:

git clone https://github.com/sfstoolbox/sfs-python.git
cd sfs-python
python3 -m pip install --user -e .

... where -e stands for --editable.

This way, your installation always stays up-to-date, even if you pull new changes from the Github repository.

Building the Documentation

If you make changes to the documentation, you can re-create the HTML pages using Sphinx. You can install it and a few other necessary packages with:

python3 -m pip install -r doc/requirements.txt --user

To create the HTML pages, use:

python3 setup.py build_sphinx

The generated files will be available in the directory build/sphinx/html/.

To create the EPUB file, use:

python3 setup.py build_sphinx -b epub

The generated EPUB file will be available in the directory build/sphinx/epub/.

To create the PDF file, use:

python3 setup.py build_sphinx -b latex

Afterwards go to the folder build/sphinx/latex/ and run LaTeX to create the PDF file. If you don’t know how to create a PDF file from the LaTeX output, you should have a look at Latexmk (see also this Latexmk tutorial).

It is also possible to automatically check if all links are still valid:

python3 setup.py build_sphinx -b linkcheck

Running the Tests

You'll need pytest for that. It can be installed with:

python3 -m pip install -r tests/requirements.txt --user

To execute the tests, simply run:

python3 -m pytest

Creating a New Release

New releases are made using the following steps:

  1. Bump version number in sfs/__init__.py
  2. Update NEWS.rst
  3. Commit those changes as "Release x.y.z"
  4. Create an (annotated) tag with git tag -a x.y.z
  5. Clear the dist/ directory
  6. Create a source distribution with python3 setup.py sdist
  7. Create a wheel distribution with python3 setup.py bdist_wheel
  8. Check that both files have the correct content
  9. Upload them to PyPI with twine: python3 -m twine upload dist/*
  10. Push the commit and the tag to Github and add release notes containing a link to PyPI and the bullet points from NEWS.rst
  11. Check that the new release was built correctly on RTD and select the new release as default version