Contributing to TeachBooks

We welcome any kind of contributions to our software, from simple comment or question to a full fledged pull request. Please read and follow our Code of Conduct.

A contribution can be one of the following cases:

  1. you have a question;

  2. you think you may have found a bug (including unexpected behavior);

  3. you want to make some kind of change to the code base (e.g. to fix a bug, to add a new feature, to update documentation).

  4. you want to make a release

The sections below outline the steps in each case.

You have a question

  1. use the search functionality here to see if someone already filed the same issue;

  2. if your issue search did not yield any relevant results, make a new issue;

  3. apply the “Question” label; apply other labels when relevant.

You think you may have found a bug

  1. use the search functionality here to see if someone already filed the same issue;

  2. if your issue search did not yield any relevant results, make a new issue, making sure to provide enough information to the rest of the community to understand the cause and context of the problem. Depending on the issue, you may want to include:

    • the SHA hashcode of the commit that is causing your problem;

    • some identifying information (name and version number) for dependencies you’re using;

    • information about the operating system;

  3. apply relevant labels to the newly created issue.

You want to make some kind of change to the code base

  1. (important) announce your plan to the rest of the community before you start working. This announcement should be in the form of a (new) issue;

  2. (important) wait until some kind of consensus is reached about your idea being a good idea;

  3. if needed, fork the repository to your own Github profile and create your own feature branch off of the latest main commit (typically the stable or develop branch). While working on your feature branch, make sure to stay up to date with the main branch by pulling in changes, possibly from the ‘upstream’ repository (follow the instructions here and here);

  4. install package main and dev dependencies. See the Set up a development environment below.

  5. make sure the existing documentation can still by generated without warnings by running cd docs && sphinx-build source/ _build/.

  6. add your own tests (if necessary), and make sure they run when you run the test suite (using the command pytest).

  7. make sure your additions pass the static code analysis. You can run it locally with the command ruff check.

  8. make sure your code is formatted correctly. You can run the formatter locally with the command ruff format.

  9. update or expand the documentation; Please add Google Style Python docstrings.

  10. push your feature branch to (your fork of) the TeachBooks repository on GitHub;

  11. create the pull request, e.g. following the instructions here.

In case you feel like you’ve made a valuable contribution, but you don’t know how to write or run tests for it, or how to generate the documentation: don’t let this discourage you from making the pull request; we can help you! Just go ahead and submit the pull request, but keep in mind that you might be asked to append additional commits to your pull request.

Set up a development environment

As the package and its dependencies are installed using pip in the Deploy Book Workflow (the GitHub Action for building books), it is best to do the same with a development environment. Begin by cloning the repository and creating a new branch from the appropriate branch and/or commit.

The creation of the development environment should be something like this:

conda deactivate         # Only needed if you have conda
python3 -m venv venv     # Create a virtual environment
source venv/bin/activate # or 'venv\Scripts\activate' on Windows
pip install -e .[dev]
pip show teachbooks      # confirm local installation is used

Using option pip install -e is editable mode, which updates the teachbooks module in the venv as it is edited.

Windows Users

The installation of the package using editable mode can take a long time on Windows. This is recognizable via the command line interface when the package installation process appears to be stuck while installing the teachbooks package. The reason is most likely due to malware scanners on organization-owned/managed computers. To resolve this there are several options:

  1. Disable (temporarily) the “Realtime malware protection” on your machine.

  2. Stop and start the installation process several times.

  3. Delete your environment and create it from scratch again.

In general, the Setuptools manual can be a useful reference in case you run into issues here. Otherwise, as you can probably already guess, the most effective solution for this (and perhaps many of your other open source software problems) is to switch to a Linux OS.

Use a development environment

The instructions above will create a venv in the root directory of the package repository, however, it may also be important to test unreleased improvements to the source code by building a book in another repository.

To test the package on an book with source code in ./book/ stored outside of the teachbooks repo will require using the relative path to the venv (PATH_TO_TEACHBOOKS_REPO):

source PATH_TO_TEACHBOOKS_REPO/venv/bin/activate
pip install -r requirements.txt
teachbooks build book/

Alternatively, one could use one of the test books in ./tests/. In fact, this is where tests should be added if making a new contribution to the package.

You want to make a release

This section is for maintainers of the package.

  1. Checkout HEAD of stable branch with git checkout stable and git pull.

  2. Determine what new version (major, minor or patch) to use. Package uses semantic versioning.

  3. Because the stable branch is protected, you need to create a new branch with git checkout -b release-<version>.

  4. Set new version in pyproject.toml file in project section.

  5. Update CHANGELOG.md with changes between current and new version.

  6. Make sure all tests passed by running pytest.

  7. Commit & push changes to GitHub.

  8. Create a pull request, review it, wait for actions to be green and merge the pull request.

  9. Wait for GitHub actions on stable branch to be completed and green.

  10. Create a GitHub release

    • Use version as title and tag version.

    • As description use intro text from README.md (to give context) and changes from CHANGELOG.md

  11. Verify

    1. Has stable ReadTheDocs been updated?

    2. Has the Github publish action successfully uploaded the archives to PyPI?

    3. Can new version be installed with pip using pip install teachbooks==<new version>?

  12. Celebrate

Releases and Versioning

Semantic numbering is used: vA.B.C, where patches advance C and minor releases advance B. Releases in the GitHub Repository deploy automatically to PyPI once a tag is created and the pyproject.toml file is updated with the new version number. Minor releases will be merged into the stable branch (including those below v1.0.0); patches may be incorporated in develop or stable.

As described above, a Pull Request should be created when making a contribution. A draft Pull Request may be set up between the develop and stable branches to preview updates for the next minor or major release.

If a release must be available on PyPI but it is not desired for it to be available as the primary release, use the numbering vA.B.Cbn, where n is an increasing number starting from 1. The specific version can be installed via pip using pip install teachbooks==A.B.Cbn. A tag defining this type of release may be used on any branch.