2. Git Usage

2.1. Git Workflow

Note

If merge conflicts exist that block the merging of a PR through the GitHub web interface, do not resolve the conflicts through the web interface, which might result in unwanted side effects. Rather, a gatekeeper should resolve the conflicts in a local clone, merge locally, and push.

Since we are currently standing this repository up, we are working with an informal git workflow. A minimal set of rules are

  1. No one should make direct commits to the main branch.

  2. Each addition and change should be made on a dedicated feature branch that is based off of the latest commit on the main branch. Try to group related changes together into a single branch so that you find a happy balance between a branch that is trivial in it’s simplicity and a branch that is a beast. Our goal is to have appropriately-sized branches that result in effective, clean reviews.

  3. At any point in time, there should be one and only one owner of a feature branch, which means that only that person can commit to that branch and push commits to the main repository. Ownership of the branch should be handed over to another developer by explicit communication only.

  4. Do not create branches off of other feature branches.

  5. If the contents of a feature branch are deemed good and ready for inclusion in the software, the branch’s developer should create a PR for merging the feature branch into main.

  6. If a PR is ready for review, the developer should first merge main into the feature branch if main has been updated since the feature branch was based off of it. This forces the integration of the new work in main to occur in the feature branch rather than in main, which we try to protect. Similarly, all merge conflict resolution occurs as subsequent commits on the feature branch rather than on main.

  7. If a PR is ready for review and synchronized with main, the branch developer should perform a self-review of the PR. Once completed, the PR must undergo a review by a different developer that is also a gatekeeper of the repository.

  8. Once the developer and the reviewers have converged on an acceptable set of changes, a gatekeeper will merge the branch into main and confirm that all actions pass on the associated merge commit.

Developers are encouraged to create PRs early during branch development to begin and record a dialogue with potential reviewers in the PR.

While its up to the reviewers’ discretion to determine what indicates a successful PR, typically merges should only proceed after confirming that all GitHub actions are passing on the latest commit of the feature branch.

2.2. GitHub Actions

All of the following actions run automatically on every push and pull request to main.

2.2.1. Documentation

  • Check Spelling — Checks a (potentially proper) subset of files in the repository for typographic errors using the typos tool with the typos.toml configuration file. Refer to the configuration to determine what files are being checked.

  • Check Links — Checks all .rst and .md files for broken URLs using the lychee tool. In addition to running on pushes and pull requests, this action runs on a regular schedule to catch links that break between contributions.

  • Build Sphinx Docs — Builds the OpenBT documentation in both HTML and PDF format using tox. The built documents are uploaded as a downloadable artifact so that contributors can review rendered documentation without needing a local build environment.

2.2.2. Python Package Testing

  • Test OpenBT Python Source Distribution — The primary test action. Builds a Python source distribution and tests it across a matrix of operating systems, MPI implementations, and Python versions to validate broad compatibility. This action additionally runs on published releases so that the source distribution built and tested by the action, which is stored as an artifact, can be manually uploaded to PyPI as the official release distribution.

  • Test OpenBT Developer-mode Installation — Tests editable installations (pip install -e .) on a reduced matrix. MPI is intentionally installed via pip rather than a system package manager to confirm that pip-installed MPI implementations work correctly.

  • Test OpenBT in Anaconda — Tests installation inside a conda environment across a matrix of operating systems and installs via pip a prebuilt Open MPI installation included in a Python package.

  • Measure OpenBT Python Coverage — Runs the full Python test suite with coverage measurement using tox and uploads the raw coverage file, XML report, and HTML report as artifacts.

2.2.3. C++ Tools Testing

  • Test OpenBT C++ Command Line Tools — Builds and tests the C++ command line tools directly across a matrix of operating systems and MPI implementations, independently of the Python package. Prints dynamic library linkage information for each built binary so that developers can verify the correct MPI implementation was linked. Since this action uses the build script recommended to users, it also confirms correct script functionality.