Proposed git workflow

The main design goal for this workflow is to help us ensure that all commits in the main branch are fully tested and verified releases. Therefore, users who choose to use IBCDFO via clone could use any of the commits on main for their important research. However, we do not intend to support previous releases and, therefore, hope that users will always start with the latest commit on main. Users who cannot use the latest commit should contact developers to determine an acceptable workaround.

git Submodule Updates

• Each git submodule is only to be set to commits on that repository's main branch that were the product of rigorous review and testing
• Updates to git submodules should only occur in dedicated PRs with review and in accord with the following git workflow.
• All gatekeepers are to be included in that review so that, at the very least, they are aware of the proposed change and can inform other interested parties of all such changes.
• Possible reviews of such PRs
  • Look at hash of submodule via the GitHub web interface in both main and in the related feature branch to confirm desired change
  • Review contents of change as seen in GitHub PR interface
  • Reviewers to
    • create a new IBCDFO clone and set to latest commit on feature branch,
    • follow installation instructions to pull down and set all submodules,
    • confirm correct submodule installation, and
    • run tox tasks locally.
  • Review in GitHub action logs that the correct submodule versions are being installed.

Main Branch: Production-Ready Code

• Contains thoroughly tested, stable, and optimized code.
• Receives updates only after extensive testing.
• The main branch will be protected. Only normal releases and hotfixes for critical bugs are allowed to go directly to main.

Develop Branch: Pre-Production Integration

The develop branch is an "infinite lifetime branch" that serves as the primary branch for work that has advanced enough that developers believe that it should likely be included in a release. In particular, it is where new features are tested before being brought into main and serves as a staging area where code is integrated and refined.

• The branch will be protected and it should only be updated by merging in feature branches via PR.
• Every effort will be taken to ensure develop does not contain abandoned work (which should not be pulled into main)

Feature Branch Workflow

Creation

• Feature branches are created off of and merged into the develop branch.
• Each branch is focused on a specific idea or feature with names following feature/<feature-name>, bugfix/<bugname>, docs/<documentation-change>, testing/<testing-name>
• Features are developed and tested in isolation on their respective branches.

Merge into Develop

• Feature branches are subject to review prior to their merging into develop
  • All GitHub actions that confirm basic testing and code formatting requirements must be passing
  • Feature branches must include tests covering any new functionality
  • Acceptable and up-to-date documentation
• Make PRs early in the development cycle and mark them as drafts. This allows for better discussions of work and captures these discussions.

Release Procedure

• Ensure any hotfixes that might be on main are pulled into develop.
• The developers responsible for the release will update the contents of develop to get it in shape so that the release is made by merging develop directly into main via PR.
• Merges into main must be reviewed and approved by another developer.
  • Review documentation and examples are sufficient, consistent, and correct.
  • Extra testing is run on the release branch including running optimizations on additional functions and using increased optimization budgets to test tail behavior where many issues arise.
• All merge commits on main should include a tag or version number. We use semantic versioning.
• When main is updated, update packages on PyPI (and elsewhere) as needed.