Maintainers Guide

Many thanks for your help maintaining our project! Without your contribution, development would be considerably slower and the user community left waiting longer.

This document complements the Contributor’s Guide by providing additional steps for integrating contributions into the project’s code base. As a maintainer, you are also a contributor, so please use the contributor guide when making changes in order to keep the development process open and consistent (note Developing Features as a Maintainer).

Be Courteous

Sometimes we need to meet contributors halfway. This means more work on our part but for benefit of the project and community. Please be courteous and patient.

If you are unable to respond fully to a pull request or issue in a timely manner, please let the contributor know that you will get to it as soon as you can.

Pull Request Review

Pull request review facilitates refinement of a contribution before it’s incorporated into the project. The goals are to ensure the contribution is consistent with the project’s design, is well-documented, and is well-tested. We are not looking for perfection, but rather that the contribution does what it is intended to do.

Though pull request review is required by the project’s GitHub branch protection rules, maintainers are allowed to bypass review. Having said this, we generally encourage review in all cases.

Here are steps to help with your pull request review:

  1. Start a GitHub review on the pull request.

  2. Check that the CI Workflow passes. Even if successful, check the workflow run logs for Ruff related messages. Though not required, we recommend these messages be addressed.

  3. New features or bug-fixes should include tests demonstrating the change.

  4. Review the diffs of code and related documentation.

  5. Check for compliance with our Commit Messages style.

  6. Submit the review.

When a pull request passes review, it is ready to be merged into the main branch.

Git and GitHub

We use a combination of git and GitHub features to version control and manage various aspects of our project. Generally, we prefer small, incremental changes that are easy to review and maintain.

Branch Management

The main branch is the releasable state. New work happens on feature branches and is rebased and merged into main via pull requests. Releases are cut from main using the CD Workflow.

Feature Branches

Any sort of change, including new features, documentation, refactors, and fixes, should be done on a feature branch to facilitate iterative collaboration. It can be helpful when feature branch names reference the issue and describes the feature, for example, 30-release-workflow.

Releases

When it’s time to create a new release, a project maintainer with repository write access, will manually dispatch the CD Workflow, which will run a series of automated tasks.

Branch Protection Rules

GitHub branch protection rules are used to help ensure the integrity of the codebase. The following rules are enforced on the main branch:

  • Require a pull request approval before merging

  • Require status checks to pass before merging

  • Require branches to be up to date before merging

  • Require conversation resolution before merging

  • Require linear history

The only protection rule maintainers are allowed to ignore is the “pull request approval” requirement. Having said this, we generally encourage review in all cases.

Secrets

A GitHub repository secret, containing the personal access token of one of the maintainers with write access, is required for the CD Workflow to complete. This token should be added to the project’s repository secrets with the name RELEASE_TOKEN. This authentication is used by Python Semantic Release to commit changes created during the release proces to the main branch.

Workflows

GitHub Actions are used for continuous integration and delivery.

CI Workflow

The CI workflow is run on each pull request and push to main branch. It performs the following steps:

  1. Formats code in src/ and tests/ using ruff. This check is strictly enforced and will fail the workflow.

  2. Analyzes code in src/ and tests/ using the project’s ruff configuration (see Code Format and Analysis). This check is not strictly enforced and will not fail the workflow. However, generally, Ruff recommendations should be followed.

  3. Runs tests in tests/ using Pytest. This check is strictly enforced and will fail the workflow.

  4. Builds the documentation (see Documentation Contributions). This check is strictly enforced and will fail the workflow.

CD Workflow

The CD workflow is run via workflow dispatch for releases. It performs the following steps:

  1. Runs Python Semantic Release to build the changelog, convert the distributions, bump the version number, and tag the release.

  2. Releases the package to PyPI.

Developing Features as a Maintainer

As a maintainer, when developing a new feature, you don’t have to fork the project repository to your personal GitHub, and submit pull requests via that route. Rather, you may create a feature branch in the project’s remote repository, and submit a pull request from there.

Dependency and Environment Management

This project uses uv to manage dependencies for development and distribution. uv keeps track of necessary packages and their versions, ensuring a consistent development environment.

Keeping Current with Science On Schema.Org

Project maintainers are responsible for ensuring mappings stay current with new SOSO conventions. Maintainers should monitor the Science-On-Schema.org GitHub repository and open a general notice as an issue on our GitHub whenever new changes may impact existing mappings and implementations. This issue serves as a collective call to action for the developer community, encouraging collaboration to update implementations.