Branching Structure Guide

This project follows a structured branching strategy to manage different versions and stages of development efficiently. Here’s a breakdown of each main branch and its purpose.

Branches

Main Branch: main

The main branch represents the stable, production-ready version of the codebase. It contains the latest official release of the project. Code in main is fully tested and approved for production use.

  • Current Version: 2.4.3

  • Purpose: Serves as the default branch for stable releases.

  • Merge Strategy: Only merges from fully tested and verified branches (such as development) are allowed.

Development Branch: development

The development branch is where active development for minor versions takes place. Features, bug fixes, and improvements for the upcoming stable release are integrated here before they are fully tested and merged into main.

  • Current Version: 2.4.4 (in-progress)

  • Purpose: Acts as the integration branch for ongoing work and testing of the next stable release.

  • Merge Strategy: Developers create feature branches off development and merge completed features back into development after testing.

Feature Branch: dev-3.0.0

The dev-3.0.0 branch is dedicated to developing and testing major updates or changes that are not yet stable enough for integration with main. This branch includes work on significant new features and alterations, such as the introduction of new data sources and schema changes in the database.

  • Current Version: 3.0.0 (under development)

  • Purpose: Used for ongoing work on the next major version, which includes substantial updates like new data sources and modifications to the database schema.

  • Merge Strategy: Only merged into main after extensive testing and stability checks. May include code merged from development if the major version requires updates from minor releases.

  • Versioning Note: This branch was initially created from version 2.4.3. Any updates beyond 2.4.3 should be reflected in this branch to maintain continuity.

Documentation Branch: gh-pages

The gh-pages branch is a dedicated branch used exclusively for hosting the development documentation of the project. This branch is managed automatically by GitHub Actions, and its content is regenerated every time a new commit is pushed to the development branch.

  • Purpose: Hosts the HTML files generated by Sphinx for the developer documentation.

  • Restrictions:

    • Do Not Edit Directly: The branch is overwritten automatically during each deployment. Any manual changes to this branch will be lost.

    • All updates to the documentation must be made in the docs-dev directory on the development branch. The GitHub Actions workflow then builds and deploys these changes to the gh-pages branch.

  • Access: The documentation can be accessed at:

    [https://ritchielab.github.io/biofilter/](https://ritchielab.github.io/biofilter/)

Workflow for Updating Documentation

  1. Make changes to the documentation in the docs-dev directory in the development branch.

  2. Commit and push your changes to the development branch.

  3. GitHub Actions will automatically:

    • Build the documentation using Sphinx.

    • Deploy the generated HTML files to the gh-pages branch.

  4. Verify the updated documentation.

Workflow Summary

  1. Feature Development: All new features and bug fixes are developed in separate branches off of development.

  2. Testing and Integration: When a feature is complete, it is merged into development for testing and integration with other recent changes.

  3. Stable Release Preparation: Once the development branch is stable and ready for release, it is merged into main, creating an official, stable release.

  4. Major Version Development: Experimental or significant changes go into dev-3.0.0 until they are ready for production.

  5. Documentation Deployment: Updates to the docs-dev directory are built and deployed to the gh-pages branch automatically by GitHub Actions.

Branching Best Practices

  • Keep main stable: Only tested, production-ready code should be merged into main.

  • Use Feature Branches: For each new feature or fix, create a branch off development. This keeps development organized and easier to manage.

  • Document and Review Changes: Always document significant changes to the codebase. Use pull requests to review and approve changes before merging into shared branches.

  • Do Not Modify ``gh-pages`` Directly: Always update documentation in the docs-dev directory in the development branch.

Conclusion

By following this structure, we ensure that our project remains organized and that each branch serves a distinct purpose in the development workflow.