Configuring Services

This section details how the services leveraged by this project need to be configured. If you have just rendered a new project and followed the instructions that were given, you should have already done the following. For reference - or in case you are looking to configure a fork of a project - we repeat those instructions here.

Note

The following instructions are only for owners/maintainers of this codebase. Developers don’t need to worry about any of this unless they are setting up a fork of the project.

  1. GitHub

    To work with this codebase, you will require a GitHub account (go here to get one).

    Branch permissions for the main project repository should be configured to only permit merges from pull requests. To do so, navigate to Settings->Branches->Add branch ruleset and:

    • give the Ruleset whatever name you’d like (e.g. Protect Main)

    • set Enforcement status to Active

    • add a Target Branch targeting criteria by pattern and type main

    • select Require a pull request before merging

    • select Require status checks to pass and add Run all build and unit tests from GitHub Actions as a required check

    This will ensure that all CI/CD tests pass before a merge to the main branch can be made.

    Note

    The following secrets do not need to be configured if you do not want to use these services. If left unconfigured, the corresponding functionality will simply be ignored.

    Several (optional) secrets need to be configured by navigating to Settings->Secrets->Actions and adding the following:

    • To host the project documentation on Read the Docs (see below), the following secrets need to be set (see below for where to find these values):

      • RTD_WEBHOOK_TOKEN, and

      • RTD_WEBHOOK_URL

    • To make code releases available on the Python Package Index (see below), then the following secret needs to be set (see below for where to find this value):

      • PYPI_TOKEN,

    • To test code releases with the Test Python Package Index (see below), then the following secret needs to be set (see below for where to find this value):

      • TEST_PYPI_TOKEN,

  2. Read the Docs

    To (optionally) publish this project’s documentation you will need a RTD account (go here to get one). Configure it as follows:

    • Ensure that your GitHub account has been connected to RTD. This is done automatically if you log into RTD with your GitHub credentials. If you logged in with your email, navigate to <login_id>->Settings->Connected Services by clicking on Connect Your Accounts and click Connect to GitHub. You know your account is linked if it is listed below under Active Services.

    • Return to your RTD landing page by clicking on your account name at the top. Click Import a Project. Your GitHub repository should be listed here (you may need to refresh the list if it has been created recently). Import it.

    • To obtain RTD_WEBHOOK_TOKEN, navigate to <Account>->Settings->API Tokens on Read the Docs and create a new token.

    • To obtain RTD_WEBHOOK_URL, use the RTD API v3 builds endpoint for your project:

      https://readthedocs.org/api/v3/projects/<project-slug>/versions/latest/builds/

      where <project-slug> is the URL-friendly identifier for your project on Read the Docs — visible in your browser’s address bar when you are on your project’s RTD page (e.g. https://readthedocs.org/projects/my-project/ has slug my-project). It is also shown in the Admin section of your RTD project.

    Once properly configured, the documentation for this project should build automatically on RTD every time you generate a new release.

  1. The Python Package Index (PyPI)

    To (optionally) publish releases of this project’s code you will need a PyPI account (go here to get one). To (optionally) generate test releases, you will need a TestPyPI account. They operate the same way and can both be configured as follows:

    • An API token will need to be created and added to your GitHub project as PYPI_TOKEN (as detailed above). This can be generated from the PyPI UI by navigating to Account Settings->Add API Token. In the first instance - before the project exists on your account - generate a token with Entire Account scope. Once the project has been published for a first time to PyPI, the initial token can be deleted and a new one generated with an project scope selected to be that of the project. Make sure to update the GitHub secret value once you have done so.

    • Repeat this process for TestPyPI if you want to be able to generate test releases, adding it as a secret to your GitHub repo with the name TEST_PYPI_TOKEN

    Note

    To create a test release, flag it as a pre-release through the GitHub interface when you generate a release, and it will be published on test.PyPI.org rather than PyPI.org. If this token is not defined, publication will not happen on either, if this option is flagged.

    Warning

    Although poetry can be used to directly publish this project to PyPI, users should not do this. The proper way to publish the project is through the GitHub interface, which leverages the GitHub Workflows of this project to ensure the enforcement of project standards before a new version can be created.