Skip to content

Update versioning and branching documentation #2813

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
PooyaHekmati wants to merge 7 commits into
base: dev
Choose a base branch
from
+308 −144
Open

Update versioning and branching documentation #2813

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
2e140b9
update versioning and branching docs
PooyaHekmati Mar 4, 2026
ca2d8a7
Update changelog.md
PooyaHekmati Mar 4, 2026
c0e12d8
Merge branch 'dev' into version-hygene
PooyaHekmati Mar 4, 2026
64cbf9f
respond to comments
PooyaHekmati Mar 5, 2026
ccce466
Merge branch 'dev' into version-hygene
PooyaHekmati Mar 5, 2026
7033404
Merge branch 'dev' into version-hygene
PooyaHekmati Apr 13, 2026
c4dc18c
Update changelog.md
PooyaHekmati Apr 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 21 additions & 20 deletions changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,25 +32,26 @@ v1.0.0
- [2757](https://github.com/RuminantFarmSystems/RuFaS/pull/2757) - [minor change] [NoInputChange] [NoOutputChange] Updates version number in `pyproject.toml`.
- [2737](https://github.com/RuminantFarmSystems/RuFaS/pull/2737) - [minor change] [NoInputChange] [NoOutputChange] Update CONTRIBUTING.md file to provide forking guidelines for contributors.
- [2690](https://github.com/RuminantFarmSystems/RuFaS/pull/2690) - [minor change] [TaskManager] [NoInputChange] [NoOutputChange] Remove hard-coded name for output folder, use user-defined name instead.
- [2720](https://github.com/RuminantFarmSystems/MASM/pull/2720) - [minor change] [Emissions] [NoInputChange] [NoOutputChange] Adds FGF emissions reset when there's a harvest-kill operation and there's none of that feed left in storage.
- [2772](https://github.com/RuminantFarmSystems/MASM/pull/2772) - [minor change] [SimulationEngine] [NoInputChange] [NoOutputChange] Refactors `SimulationEngine`.`_daily_simulation()` to accommodate isolating modules.
- [2791](https://github.com/RuminantFarmSystems/MASM/pull/2791) - [minor change] [Animal] [NoInputChange] [NoOutputChange] Updates ration percentage values in example feed files to sum to exactly 100.
- [2833](https://github.com/RuminantFarmSystems/MASM/pull/2833) - [minor change] [Animal] [NoInputChange] [NoOutputChange] Remove unused animal_requirements.py file.
- [2815](https://github.com/RuminantFarmSystems/MASM/pull/2815) - [minor change] [All Non-Biophysical Modules] [NoInputChange] [NoOutputChange] Updates error messages raised to be clearer and more helpful for diagnosis and fixing.
- [2804](https://github.com/RuminantFarmSystems/MASM/pull/2804) - [minor change] [Tests] [NoInputChange] [NoOutputChange] Clears all mypy errors in test_field.py.
- [2828](https://github.com/RuminantFarmSystems/MASM/pull/2828) - [minor change] [DataValidator] [NoInputChange] [NoOutputChange] Refactors `validate_metadata()` to be less complex.
- [2819](https://github.com/RuminantFarmSystems/MASM/pull/2819) - [minor change] [Tests] [NoInputChange] [NoOutputChange] Clears all mypy errors in test_input_manager.py.
- [2836](https://github.com/RuminantFarmSystems/MASM/pull/2836) - [minor change] [Tests] [NoInputChange] [NoOutputChange] Clears all mypy errors in test_output_manager.py.
- [2826](https://github.com/RuminantFarmSystems/MASM/pull/2826) - [minor change] [Animal] [NoInputChange] [NoOutputChange] Adds functionality to data_padder, removes unecessary use of method in ration reporting.
- [2827](https://github.com/RuminantFarmSystems/MASM/pull/2827) - [minor change] [Metadata] [NoInputChange] [NoOutputChange] Updates ration-related metadata descriptions.
- [2849](https://github.com/RuminantFarmSystems/MASM/pull/2849) - [minor change] [Crop and Soil] [NoInputChange] [NoOutputChange] Update the property definition of dry matter percent.
- [2848](https://github.com/RuminantFarmSystems/MASM/pull/2848) - [minor change] [NoInputChange] [NoOutputChange] Justify `deepcopy()` usage.
- [2843](https://github.com/RuminantFarmSystems/MASM/pull/2843) - [minor change] [NoInputChange] [NoOutputChange] Fix Simple `#noqa`s in codebase.
- [2852](https://github.com/RuminantFarmSystems/MASM/pull/2852) - [minor change] [NoInputChange] [NoOutputChange] Fix AssertionError on `dev`.
- [2866](https://github.com/RuminantFarmSystems/MASM/pull/2866) - [minor change] [NoInputChange] [NoOutputChange] Clears all mypy errors in test_field_manager.py.
- [2863](https://github.com/RuminantFarmSystems/MASM/pull/2863) - [minor change] [NoInputChange] [NoOutputChange] Updates TaskManager to avoid using multiprocessing when running single tasks.
- [2867](https://github.com/RuminantFarmSystems/MASM/pull/2867) - [minor change] [NoInputChange] [NoOutputChange] Updates expand_data_temporally() util function to offer options of full simulation expansion and front-padding data.
- [2854](https://github.com/RuminantFarmSystems/MASM/pull/2854) - [minor change] [Emissions][OutputManager] [NoInputChange] [NoOutputChange] Update `emissions.py` filtering process and remove `use_filter_key_name` option in the OM filter.
- [2720](https://github.com/RuminantFarmSystems/RuFaS/pull/2720) - [minor change] [Emissions] [NoInputChange] [NoOutputChange] Adds FGF emissions reset when there's a harvest-kill operation and there's none of that feed left in storage.
- [2772](https://github.com/RuminantFarmSystems/RuFaS/pull/2772) - [minor change] [SimulationEngine] [NoInputChange] [NoOutputChange] Refactors `SimulationEngine`.`_daily_simulation()` to accommodate isolating modules.
- [2791](https://github.com/RuminantFarmSystems/RuFaS/pull/2791) - [minor change] [Animal] [NoInputChange] [NoOutputChange] Updates ration percentage values in example feed files to sum to exactly 100.
- [2813](https://github.com/RuminantFarmSystems/RuFaS/pull/2813) - [minor change] [Docs] [NoInputChange] [NoOutputChange] Updates branching and versioning policy docs.
- [2833](https://github.com/RuminantFarmSystems/RuFaS/pull/2833) - [minor change] [Animal] [NoInputChange] [NoOutputChange] Remove unused animal_requirements.py file.
- [2815](https://github.com/RuminantFarmSystems/RuFaS/pull/2815) - [minor change] [All Non-Biophysical Modules] [NoInputChange] [NoOutputChange] Updates error messages raised to be clearer and more helpful for diagnosis and fixing.
- [2804](https://github.com/RuminantFarmSystems/RuFaS/pull/2804) - [minor change] [Tests] [NoInputChange] [NoOutputChange] Clears all mypy errors in test_field.py.
- [2828](https://github.com/RuminantFarmSystems/RuFaS/pull/2828) - [minor change] [DataValidator] [NoInputChange] [NoOutputChange] Refactors `validate_metadata()` to be less complex.
- [2819](https://github.com/RuminantFarmSystems/RuFaS/pull/2819) - [minor change] [Tests] [NoInputChange] [NoOutputChange] Clears all mypy errors in test_input_manager.py.
- [2836](https://github.com/RuminantFarmSystems/RuFaS/pull/2836) - [minor change] [Tests] [NoInputChange] [NoOutputChange] Clears all mypy errors in test_output_manager.py.
- [2826](https://github.com/RuminantFarmSystems/RuFaS/pull/2826) - [minor change] [Animal] [NoInputChange] [NoOutputChange] Adds functionality to data_padder, removes unecessary use of method in ration reporting.
- [2827](https://github.com/RuminantFarmSystems/RuFaS/pull/2827) - [minor change] [Metadata] [NoInputChange] [NoOutputChange] Updates ration-related metadata descriptions.
- [2849](https://github.com/RuminantFarmSystems/RuFaS/pull/2849) - [minor change] [Crop and Soil] [NoInputChange] [NoOutputChange] Update the property definition of dry matter percent.
- [2848](https://github.com/RuminantFarmSystems/RuFaS/pull/2848) - [minor change] [NoInputChange] [NoOutputChange] Justify `deepcopy()` usage.
- [2843](https://github.com/RuminantFarmSystems/RuFaS/pull/2843) - [minor change] [NoInputChange] [NoOutputChange] Fix Simple `#noqa`s in codebase.
- [2852](https://github.com/RuminantFarmSystems/RuFaS/pull/2852) - [minor change] [NoInputChange] [NoOutputChange] Fix AssertionError on `dev`.
- [2866](https://github.com/RuminantFarmSystems/RuFaS/pull/2866) - [minor change] [NoInputChange] [NoOutputChange] Clears all mypy errors in test_field_manager.py.
- [2863](https://github.com/RuminantFarmSystems/RuFaS/pull/2863) - [minor change] [NoInputChange] [NoOutputChange] Updates TaskManager to avoid using multiprocessing when running single tasks.
- [2867](https://github.com/RuminantFarmSystems/RuFaS/pull/2867) - [minor change] [NoInputChange] [NoOutputChange] Updates expand_data_temporally() util function to offer options of full simulation expansion and front-padding data.
- [2854](https://github.com/RuminantFarmSystems/RuFaS/pull/2854) - [minor change] [Emissions][OutputManager] [NoInputChange] [NoOutputChange] Update `emissions.py` filtering process and remove `use_filter_key_name` option in the OM filter.
- [2872](https://github.com/RuminantFarmSystems/RuFaS/pull/2872) - [minor change] [NoInputChange] [NoOutputChange] Adds information and links for onboarding videos.
- [2850](https://github.com/RuminantFarmSystems/RuFaS/pull/2850) - [minor change] [NoInputChange] [NoOutputChange] Refactor `Pen.get_manure_stream()`.
- [2902](https://github.com/RuminantFarmSystems/RuFaS/pull/2902) - [minor change] [NoInputChange] [NoOutputChange] Add v1.0.0 release notes.
Expand All @@ -61,7 +62,7 @@ v1.0.0
- [2924](https://github.com/RuminantFarmSystems/RuFaS/pull/2924) - [minor change] [NoInputChange] [NoOutputChange] Updated advance purchase allowance to prevent excessive warnings for example run.
- [2929](https://github.com/RuminantFarmSystems/RuFaS/pull/2929) - [minor change] [GraphGenerator] [NoInputChange] [NoOutputChange] Sanitizes non-numerical data sent to graph generator to allow graphing to occur despite.
- [2925](https://github.com/RuminantFarmSystems/RuFaS/pull/2925) - [minor change] [NoInputChange] [NoOutputChange] Fix the `graph_and_report` option in report_generation.py.
- [2907](https://github.com/RuminantFarmSystems/RuFaS/pull/2907) - [minor change] [NoInputChange] [OutputChange] Fix the FarmGrownFeed Emissions unit issue. The mirror issue of [Fix FarmGrownFeed Emissions Unit on test #2908](https://github.com/RuminantFarmSystems/MASM/pull/2908) to update `dev`.
- [2907](https://github.com/RuminantFarmSystems/RuFaS/pull/2907) - [minor change] [NoInputChange] [OutputChange] Fix the FarmGrownFeed Emissions unit issue. The mirror issue of [Fix FarmGrownFeed Emissions Unit on test #2908](https://github.com/RuminantFarmSystems/RuFaS/pull/2908) to update `dev`.
- [2934](https://github.com/RuminantFarmSystems/RuFaS/pull/2934) - [minor change] [NoInputChange] [NoOutputChange] [Animal][Reproduction] Refactor `Reproduction.execute_cow_ed_protocol()`.
- [2948](https://github.com/RuminantFarmSystems/RuFaS/pull/2948) - [minor change] [Feeds][NoInputChange] [NoOutputChange] Removes feed id maximums in metadata properties.

Expand Down
184 changes: 134 additions & 50 deletions docs/_src/_wiki/Branching-Strategy-in-RuFaS.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
Branching Strategy in RuFaS
===========================

In this wiki, we outline the branching strategy used in RuFaS, detailing
In this page, we outline the branching strategy used in RuFaS, detailing
the purpose of each branch and the process for merging changes.

Branches Overview
Expand All @@ -12,82 +12,166 @@ Branches Overview

- **Purpose**: Active development branch where new features and changes
are implemented.

- **Usage**: All pull requests (PRs) are merged into ``dev``. This is
the main branch for ongoing development.
- **Approval**: Merging to ``dev`` requires 2 approvals.
the primary branch for ongoing development.

- **Approval**: Merging to ``dev`` requires **2 approvals**.

- **Note**: All the changes on ``dev`` are considered for the next release.
If something is **NOT** intended to be included in the next release,
it should be merged into a separate parking branch and not merged into ``dev``
until it is ready for release.

``test``
~~~~~~~~

- **Purpose**: Intermediate branch used for integration and testing of
features before moving to ``main``.
- **Usage**: Changes from ``dev`` are periodically pulled into ``test``
for vigorous testing. This ensures that new features and fixes are
properly tested before being considered stable.
- **Approval**: Merging to ``test`` requires at least 1 approval.
- **Purpose**: Intermediate branch used for **integration, validation,
and stabilization** prior to a release.

- **Usage**: When preparing a release candidate, the current state of
``dev`` is merged into ``test``. The ``test`` branch is then used for
validation and stabilization before releasing a new version.

Once ``dev`` has been merged into ``test`` for a release candidate,
no new development work should be introduced into ``test``. Only bug
fixes discovered during testing should be applied.

- **Approval**: ``test`` is locked and only admins can merge into it.

``main``
~~~~~~~~

- **Purpose**: Primary branch representing the latest stable release
that is ready for production.
- **Usage**: Once changes in ``test`` are confirmed to be stable, the
version number is updated, and updates are pulled into ``main``. The
``main`` branch is locked, and only `Pooya
Hekmati <https://github.com/PooyaHekmati>`__ and `Kristan
Reed <https://github.com/KFosterReed>`__ have the permissions to merge
PRs into it.

- **Usage**: Once changes in ``test`` are confirmed to be stable and the
version number has been updated, updates are pulled into ``main``.

- **Permissions**: The ``main`` branch is locked, and only
repo admins have permission to merge pull requests into it.

``scientific_documentation_updates``
Copy link
Copy Markdown
Contributor

@LisaM-kiwi LisaM-kiwi Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Geneva confirmed that we will most likely be moving to a different branch for updates in the future. Timing for the change isn't set yet, so we recommend moving forward with this "as is" and we can update it when the new branch is set up.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- **Purpose**: Branch used for updates to the **scientific documentation**
that do not require changes to the RuFaS codebase.

- **Usage**: Documentation updates may be committed directly to this
branch and merged into ``main`` without going through the ``test``
branch.
Comment on lines +60 to +62
Copy link
Copy Markdown
Contributor

@elle-andreen elle-andreen Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if this is the right place for this information, but should it be specified that only maintainers should update documentation? It looks like the branch itself is not protected and there is no mention here of protection, am I wrong in thinking anyone could modify the content of the branch accidentally or erroneously?

Copy link
Copy Markdown
Collaborator Author

@PooyaHekmati PooyaHekmati Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, Elle!
I can add the branch protection rules; but am curious about only maintainers being able to update the documentation,

Copy link
Copy Markdown
Contributor

@elle-andreen elle-andreen Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

only maintainers being able to update the documentation,

That was my presumption since the sci doc branch is unprotected at the moment! My original question probably pertains more to the sci doc update process than to branching strategy. It makes sense to me that we would eventually permit or encourage non-maintainers to update sci docs, but I presume we would want to adhere to something similar to the usual process of PRs and reviews to ensure updates are correct and appropriate. But I think that process has not been fleshed out yet, maybe the best thing is to come back and add a little more detail here once the sci doc process is agreed upon and documented.

Copy link
Copy Markdown
Contributor

@LisaM-kiwi LisaM-kiwi Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We're working on the sci docs update guidelines now. I'm comfortable leaving the branch without protections and we can update this section with more information and links to procedures once they are finalized.


- **Synchronization**: After merging into ``main``, the changes must
also be merged into ``dev`` to ensure documentation remains consistent
across development branches.

Merging Process
---------------

Merging to ``dev``
~~~~~~~~~~~~~~~~~~

1. **Develop**: Create feature branches off ``dev`` to work on new
features or fixes.
2. **Submit PR**: Once the feature is ready, create a pull request to
merge it into ``dev``.
3. **Review**: The code is reviewed following the `code review
process <https://github.com/RuminantFarmSystems/MASM/wiki/Code-review>`__
in RuFaS.
4. **Merge**: After approval, the PR is merged into ``dev``.
1. **Develop**

- Create feature branches from ``dev`` to implement new features,
bug fixes, or improvements.

2. **Submit PR**

- Once development is complete, submit a pull request to merge the
feature branch into ``dev``.

3. **Review**

- Code is reviewed following the
`code review process <https://ruminantfarmsystems.github.io/RuFaS/_wiki/Code-review.html>`__
used in RuFaS.

4. **Merge**

- After receiving the required approvals, the PR is merged into
``dev``.

Merging to ``test``
~~~~~~~~~~~~~~~~~~~

1. **Periodic Updates**: Periodically, pull changes from ``dev`` into
``test``.
2. **Testing**: Conduct rigorous testing on the ``test`` branch to
ensure all features and fixes are stable.
3. **Feedback**: Address any issues found during testing by pushing
fixes to ``dev`` and then merging the updates back into ``test``.
1. **Prepare a Release Candidate**

- When the development team decides to prepare a release,
update the version number in ``pyproject.toml`` on the ``dev``
branch and merge ``dev`` into ``test``.

2. **Testing Phase**

- Conduct rigorous testing on the ``test`` branch to verify model
correctness, integration stability, and expected behavior.

3. **Handling Issues During Testing**

If an issue is discovered during testing:

- Create a **fix branch from ``test``**.
- Implement the fix in that branch.
- Submit a PR to merge the fix into ``test``.
- After the fix is merged into ``test``, create a PR to merge the
same fix back into ``dev`` so both branches remain synchronized.

4. **Continue Stabilization**

- Repeat this process until the ``test`` branch is confirmed to be
stable and ready for release.

Merging to ``main``
~~~~~~~~~~~~~~~~~~~

1. **Stability Confirmation**: Once the ``test`` branch is confirmed to
be stable, update the version number in both ``TaskManager`` and the
change log. :doc:`RuFaS Versioning Policy <RuFaS-Versioning-Policy>`
2. **Pull Updates**: Pull the stable updates from ``test`` into
``main``.
3. **Approval**: Only `Pooya
Hekmati <https://github.com/PooyaHekmati>`__ and `Kristan
Reed <https://github.com/KFosterReed>`__ can merge PRs into ``main``
to ensure high-quality, stable releases.
1. **Merge Version Update into Test**

- Merge the updated ``dev`` branch into ``test`` as part of the
release preparation.

2. **Stability Confirmation**

- Confirm that the ``test`` branch has passed validation and
stabilization testing.

3. **PML Approval**

- The **Project Management Lead (PML)** must approve the release and
Copy link
Copy Markdown
Contributor

@LisaM-kiwi LisaM-kiwi Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the contributing guidelines we have Program Management Leadership, so I recommend changing for consistency.

the release notes before the merge to ``main`` is performed.

4. **Merge to Main**

- Pull the stable updates from ``test`` into ``main``.

5. **Tag the Release**

- Create a Git tag corresponding to the version number
(for example ``v1.2.0``).

Best Practices
--------------

- **Consistent Testing**: Ensure thorough testing is done in ``test``
before merging into ``main``.
- **Clear Communication**: Keep all team members informed about the
status of each branch and any important changes.
- **Documentation**: Maintain clear and up-to-date documentation for all
changes and testing procedures.
- **Review and Approval**: Adhere to the :doc:`code review guidelines <Code-review>`
to maintain code quality and stability.

By following this branching strategy, we ensure a clear and structured
workflow that supports continuous integration and delivery, maintaining
the high standards of code quality in RuFaS.
- **Consistent Testing**

Ensure thorough validation is completed in ``test`` before merging
into ``main``.

- **Branch Consistency**

Fixes applied during the testing phase must always be merged back into
``dev`` to prevent branch divergence.

- **Clear Communication**

Keep all team members informed about the status of release candidates
and branch updates.

- **Documentation**

Maintain clear and up-to-date documentation for changes and testing
procedures.

- **Review and Approval**

Adhere to the :doc:`Code Review Guidelines <https://ruminantfarmsystems.github.io/RuFaS/_wiki/Code-review.html>` to maintain
Copy link
Copy Markdown
Contributor

@LisaM-kiwi LisaM-kiwi Apr 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The link on this line isn't showing up properly in the page preview.

code quality and model integrity.
Loading
Loading