Version Control#

Version control is essential to managing the development process, allowing multiple developers to work on code simultaneously, track changes, and maintain a history of the project. It enables collaboration, safeguards against errors, and helps manage releases and bug fixes effectively.

This project follows the GitHub Flow branching strategy. This lightweight workflow is both simple and fast. Below, we will explain the key steps for contributing to this project using GitHub Flow, as well as references to other branching strategies, their pros, and cons. You’ll also find instructions for handling longer feature development, merge conflicts, and patches to maintenance branches.

Note

We assume developers are already at least a little familiar with using git and GitHub. If this is not the case for you, there are many online tutorials to help you learn git.

Branching Strategies#

Several branching strategies are used in software development, each with its pros and cons. Below are a few common ones:

  • Git Flow: Git Flow is a comprehensive branching strategy with separate branches for features, releases, hotfixes, and development. It’s well-suited for larger projects with multiple releases but can be overly complex for smaller teams.

    • Pros: Clear separation between development, releases, and hotfixes.

    • Cons: Complicated branching structure, especially for smaller projects.

  • Trunk-Based Development: This approach involves a single main branch with frequent small merges directly to it. Developers create short-lived feature branches and merge back quickly.

    • Pros: Simplifies version control, encourages continuous integration.

    • Cons: Requires careful management to avoid breaking changes on main.

  • GitHub Flow: A simpler model, ideal for projects using continuous delivery. Development happens in short-lived feature or bug branches that are merged back into main via pull requests.

    • Pros: Simple, easy to use, integrates well with CI/CD.

    • Cons: Lacks formal support for maintaining multiple concurrent releases.

For this project, we use GitHub Flow, which is explained in detail below. Interested parties can read more about any of these branching strategies here.

Project Workflow#

The BATMODS-lite project uses GitHub Flow as its version control model due to its simplicity and proven success in other scientific packages like SciPy and Cantera. The workflow emphasizes short-lived feature branches, as shown in the figure below, that each address a single bug fix or feature addition.

GitHub flow diagram.

Key Features#

  1. Main Branch:

    main is the default branch that contains the latest stable developer code. It reflects the current state of development and should always be functional.

  2. Release Branches:

    Each release has its own maintenance branch, e.g., v1.1.x. These branches should only receive bug fixes and are not meant for new feature development.

  3. Feature and Bugfix Branches:

    New features or bug fixes should be developed on separate branches off main. The naming conventions are:

    • Feature branches: feature/description-issue

    • Bugfix branches: bugfix/description-issue

You should attempt to use prefixes for all branches. For example, use feature and bugfix for branches adding a feature or fixing a bug, respectively. For anything else, use an appropriate and intuitive prefix, like docs, chore, or maint for documentation or maintenance tasks. Also, if an issue number is relevant, include it in the branch name, as demonstrated above. Use dashes between works as needed and try to keep to shorter names. The issue can always be referenced in cases where more information is needed.

The main repository only hosts the main and release branches. Users should fork the main repo and clone the fork to get a local copy:

git clone https://github.com/<username>/batmods-lite.git

You will likely also want to setup a remote to the upstream repository for dealing with merge conflicts and version patches, as discussed below. To set up an upstream remote use:

git remote add upstream https://github.com/NatLabRockies/batmods-lite.git

Bug Fixes#

Always prioritize fixing bugs in the main branch first. This project is in the early development stages and has not yet reached v1.0.x. Until this milestone is reached, only the latest stable release and the development (main) branch will have bug fixes applied. Patches will not be backported to older versions under any circumstances. Starting with v1.0.x, we will maintain all releases for at least one year after their initial release. During this time, critical bug fixes will be backported to all maintained releases.

If you are patching main, follow the directions in the New Features section. Otherwise, to patch a bug on a previous release, follow these steps:

  1. Fetch the release branches and create a new branch off the release:

    git fetch upstream
git checkout -b bugfix/description-123 upstream/v1.1.x

  2. Work on your local branch to fix the bug. Commit and push back to your fork as needed:

    git add .
git commit -m "Resolved bug causing ... (#123)"
git push origin bugfix/description-123

  3. Submit a pull request (PR) targeting the specific release branch (e.g., v1.1.x). Only bug fixes should be submitted to release branches – no new features. Make sure you fill out the pull request template and include more detail than was provided in your commit messages. After all continuous integration (CI) checks are passing, a reviewer will be assigned and will follow up according to the review process.

  4. If you opened a PR and any CI checks are failing, simply continue working on your branch and committing. All extra commits will automatically be added to the PR.

  5. After the PR is accepted and merged into the upstream repository, delete your new branch locally and in your GitHub repo:

    git checkout main
git branch -d bugfix/description-123
git push origin --delete bugfix/description-123
git fetch --prune

  6. Repeat this processes as necessary to patch additional older versions. Unfortunately, each version needs to be patched individually, which creates more work for developers, and is the reason we prioritize which (and how many) versions get patched. However, patches should never skip versions when applied to many. For example, if a patch is submitted for v1.1.x, then it should also be applied to v1.2.x and above (up to and including main), but it does not necessarily need to be submitted for v1.0.x. Before submitting patches for older versions, we recommend confirming with the development team. Some releases may no longer be eligible for new patch updates.

New Features#

New features should be added to branches off main. Before you branch off your local branch, make sure it is up-to-date with the upstream repo. You can either use the GitHub web interface to sync your fork with the upstream repository and then run:

git checkout main
git pull

or, if you setup the upstream remote, you can do this all in the command line using:

git fetch upstream
git checkout main
git merge upstream/main
git push origin main

You should never commit directly to a main branch, even including your local or forked main branch. Instead, your main branch should always either be synced with the upstream repo, or should simply be behind by some number of commits depending on the last time it was synced. After syncing, create a new branch. Your new branch should be named according to the directions above depending on whether it is a bug fix or for a new feature. Here we demonstrate a new feature:

git checkout -b feature/description-456

Once the new branch is created, follow the steps below to add your new feature:

  1. Work on your local branch to add the feature. Commit and push back to your fork as needed:

    git add .
git commit -m "Working new feature (#456)"
git push origin feature/description-456

  2. Submit a pull request targeting the upstream main branch. Make sure you fill out the pull request template and include more detail than was provided in your commit messages. After all CI checks are passing, a reviewer will be assigned and will follow up according to the review process.

  3. If you opened a PR and any CI checks are failing, simply continue working on your branch and committing. All extra commits will automatically be added to the PR.

  4. After the PR is accepted and merged into the upstream repository, delete your new branch locally and in your GitHub repo:

    git checkout main
git branch -d feature/description-456
git push origin --delete feature/description-456
git fetch --prune

Merge Conflicts#

If you’ve submitted a PR and are seeing merge conflicts you should take the following steps:

  1. Make sure your main branch is synced with the upstream remote:

    git fetch upstream
git checkout main
git merge upstream/main
git push main

  2. Rebase your local bug/feature branch onto main:

    git checkout feature/description-456
git rebase main

  3. Address merge conflicts as needed and continue the rebase:

    git rebase --continue

  4. Recommit and push as normal and verify the merge conflict in the PR gets removed. At this point, if you are still having issues, please leave a comment in the PR asking a core developer to help out.

Continuous Integration#

Every pull request is automatically tested using GitHub Actions. The CI workflow runs linting, spellchecking, and tests against all major operating systems and supported Python versions. Pull requests should only be merged when all tests pass unless a core developer explicitly makes an exception (e.g., for a soon-to-be-unsupported Python version).

Running tests locally is encouraged during development:

nox -s tests

Prior to commits and pushes, we also include a pre-commit session using nox that will run through these same tests AND will check for linting and misspellings. Use this prior to pushes and/or pull requests:

nox -s pre-commit

This ensures all tests pass before pushing any changes.