From ce5c670c1fe3630f86ba6054563475f147593606 Mon Sep 17 00:00:00 2001 From: Kristan Reed Date: Fri, 6 Mar 2026 15:02:43 -0500 Subject: [PATCH 1/4] Add Maintainer Version Update process description to wiki --- docs/_src/_wiki/Version-Update-Workflow.rst | 128 ++++++++++++++++++++ docs/_src/index.rst | 1 + 2 files changed, 129 insertions(+) create mode 100644 docs/_src/_wiki/Version-Update-Workflow.rst diff --git a/docs/_src/_wiki/Version-Update-Workflow.rst b/docs/_src/_wiki/Version-Update-Workflow.rst new file mode 100644 index 0000000000..e7c1639f12 --- /dev/null +++ b/docs/_src/_wiki/Version-Update-Workflow.rst @@ -0,0 +1,128 @@ +Maintainer Team Workflow/Communication for Version Update +========================================================= + +This page describes the process that RuFaS Maintainers will use to communicate +and execute a version update. + +In addition to the updated model and scientific documentation in the repository +codebase, additional deliverables of this process for **Major** and **Minor** +updates are: + +- A version release note that includes: + + - A high-level summary of the outcomes of the SME Review + - A summary of the changelog + +- A detailed technical report of the SME Review + + +Version Update Process +====================== + +The process for updating the RuFaS version is as follows: + + +Version Release Trigger +----------------------- + +When a version release is triggered according to the principles of semantic +versioning and approved by the PML: + +- Announcements are made at the All Team Meeting (ATM) and in the general + Slack channel to communicate the decision. + + +Major and Minor Updates +----------------------- + +For **Major** and **Minor** updates: + +1. RuFaS Maintainers meet to discuss what work **will and will not** be + included in the release and the proposed timeline. + +2. The PML reviews and finalizes pending work to be included and excluded + from the version update, with additional Maintainer input as needed. + +3. The PML and team leaders create a GitProject for the version release and + add pending issues/PRs that must be completed before the version update + (before ``dev → test``). + +4. SME Maintainers review the evaluation process and criteria from the + previous version release: + + - Are updates to benchmarks required? + - Are new metrics required for new features? + + +Patch Updates +------------- + +For **Patch** updates: + +- A full project is not required. +- Bug fixes required in the patch should be collected as sub-issues under + a **Patch version update parent issue**. + + +Evaluation Preparation +---------------------- + +- Maintainers update evaluation farm inputs and ensure they run on the + ``dev`` branch. + + +Dev Freeze and Test Preparation +------------------------------- + +For **Major and Minor updates**, when all required tasks are merged into +``dev`` (or all but one or two are pending): + +1. Pooya Hekmati or Kristan Reed freezes ``dev``. +2. Maintainers merge ``dev`` into ``test``. +3. The Director of Software Engineering (Pooya Hekmati) generates a release + note summarizing the changelog. + + +Evaluation and SME Review +------------------------- + +When ``test`` has been updated: + +1. Maintainers work together to run Evaluation Farms on ``test``. +2. Outputs are collected and summarized for the SME Review process + (link to upcoming SME Review page). +3. SME Maintainers conduct the SME Review led by the Scientific Director. + +During this stage: + +- Maintainers identify and fix any bugs or model errors surfaced during + the SME Review following the processes outlined in the branch management + guidelines for version updates. + +- The Scientific Director prepares: + + - A high-level statement of model outcomes + - A technical summary of the review process + +These summaries are shared with SME Maintainers for input. + + +Release Approval and Publication +-------------------------------- + +After SME Maintainers have had an opportunity to review and provide +feedback on the evaluation report and technical summaries: + +1. RuFaS Directors vote on the release: + + - Director of Software Engineering + - Director of Strategic Partnerships and Governance + - Scientific Director + +2. The high-level summary of the SME review is combined with the release + note. + +3. The technical summary of the SME review is combined with release notes + and added to the RuFaS GitHub Pages documentation. + +4. The Director of Software Engineering generates the official release. \ No newline at end of file diff --git a/docs/_src/index.rst b/docs/_src/index.rst index 360002636c..39f2b857ae 100644 --- a/docs/_src/index.rst +++ b/docs/_src/index.rst @@ -67,6 +67,7 @@ Team Culture _wiki/RuFaS-Versioning-Policy _wiki/SCRUM-at-RuFaS + _wiki/Version-Update-Workflows Contributing to RuFaS From 518c279f95ac1f22cf8fda444fd47fecdf676b46 Mon Sep 17 00:00:00 2001 From: Kristan Reed Date: Sun, 12 Apr 2026 15:26:21 -0400 Subject: [PATCH 2/4] update version update workflow based on feedback --- docs/_src/_wiki/Version-Update-Workflow.rst | 123 ++++---------------- 1 file changed, 25 insertions(+), 98 deletions(-) diff --git a/docs/_src/_wiki/Version-Update-Workflow.rst b/docs/_src/_wiki/Version-Update-Workflow.rst index e7c1639f12..1f2e839253 100644 --- a/docs/_src/_wiki/Version-Update-Workflow.rst +++ b/docs/_src/_wiki/Version-Update-Workflow.rst @@ -1,5 +1,5 @@ -Maintainer Team Workflow/Communication for Version Update -========================================================= +Maintainer Team Workflow and Communication during a Version Update +=================================================================== This page describes the process that RuFaS Maintainers will use to communicate and execute a version update. @@ -8,121 +8,48 @@ In addition to the updated model and scientific documentation in the repository codebase, additional deliverables of this process for **Major** and **Minor** updates are: +- A detailed technical report of the scientific review by SME Maintainers - A version release note that includes: - - A high-level summary of the outcomes of the SME Review - A summary of the changelog -- A detailed technical report of the SME Review +Before Merging ``dev`` to ``test`` +------------------------------ -Version Update Process -====================== +**Major** and **Minor** updates: +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The process for updating the RuFaS version is as follows: - - -Version Release Trigger ------------------------ - -When a version release is triggered according to the principles of semantic -versioning and approved by the PML: - -- Announcements are made at the All Team Meeting (ATM) and in the general - Slack channel to communicate the decision. - - -Major and Minor Updates ------------------------ - -For **Major** and **Minor** updates: 1. RuFaS Maintainers meet to discuss what work **will and will not** be included in the release and the proposed timeline. -2. The PML reviews and finalizes pending work to be included and excluded +2. The PML reviews and approves pending work to be included and excluded from the version update, with additional Maintainer input as needed. 3. The PML and team leaders create a GitProject for the version release and add pending issues/PRs that must be completed before the version update - (before ``dev → test``). - -4. SME Maintainers review the evaluation process and criteria from the - previous version release: - - - Are updates to benchmarks required? - - Are new metrics required for new features? - - -Patch Updates -------------- - -For **Patch** updates: - -- A full project is not required. -- Bug fixes required in the patch should be collected as sub-issues under - a **Patch version update parent issue**. - - -Evaluation Preparation ----------------------- - -- Maintainers update evaluation farm inputs and ensure they run on the - ``dev`` branch. + (before ``dev → test``). If a Maintainer identifies additional work that would benefit + the version release after the project is created, issues/PRs should be added to + the version release project or discussed with the PML at the members discretion. +4. SME Maintainers review the scientific evaluation process and criteria from the + previous version release and update as necessary. -Dev Freeze and Test Preparation -------------------------------- -For **Major and Minor updates**, when all required tasks are merged into -``dev`` (or all but one or two are pending): +**Patch** Updates +^^^^^^^^^^^^^^^^^^ -1. Pooya Hekmati or Kristan Reed freezes ``dev``. -2. Maintainers merge ``dev`` into ``test``. -3. The Director of Software Engineering (Pooya Hekmati) generates a release - note summarizing the changelog. +Patch updates do not require a full project. Bug fixes required in the patch should be collected +as sub-issues under a **Patch version update parent issue**. -Evaluation and SME Review +After ``test`` is updated ------------------------- - -When ``test`` has been updated: - -1. Maintainers work together to run Evaluation Farms on ``test``. -2. Outputs are collected and summarized for the SME Review process - (link to upcoming SME Review page). -3. SME Maintainers conduct the SME Review led by the Scientific Director. - -During this stage: - -- Maintainers identify and fix any bugs or model errors surfaced during - the SME Review following the processes outlined in the branch management - guidelines for version updates. - -- The Scientific Director prepares: - - - A high-level statement of model outcomes - - A technical summary of the review process - -These summaries are shared with SME Maintainers for input. - - -Release Approval and Publication --------------------------------- - -After SME Maintainers have had an opportunity to review and provide -feedback on the evaluation report and technical summaries: - -1. RuFaS Directors vote on the release: - - - Director of Software Engineering - - Director of Strategic Partnerships and Governance - - Scientific Director - -2. The high-level summary of the SME review is combined with the release - note. - -3. The technical summary of the SME review is combined with release notes - and added to the RuFaS GitHub Pages documentation. - -4. The Director of Software Engineering generates the official release. \ No newline at end of file +- During the testing phase, SME Maintainers will evaluate integrated model performance. +(link to Scientific Evaluation Process). +- When the model performance has been verified by at least one SME Maintainer per Module, +the Scientific Director will prepare a Scientific Report summarizing the model performance and changes in scientific methodology. +- The Director of Software Engineering will lead preparation of a set of Release Notes to summarize model updates. +- When the testing phase is complete, both the Scientific Report and Release notes are added to the project documentation on GitHub +and shared with the PML for approval. From 4d5a4aba9177c99b1a1fbbeb5cba4f086722ab89 Mon Sep 17 00:00:00 2001 From: Kristan Reed Date: Sun, 12 Apr 2026 15:31:31 -0400 Subject: [PATCH 3/4] update changelog --- changelog.md | 1 + 1 file changed, 1 insertion(+) diff --git a/changelog.md b/changelog.md index 10ab98d822..dc2b0dd39c 100644 --- a/changelog.md +++ b/changelog.md @@ -63,6 +63,7 @@ v1.0.0 - [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`. - [2934](https://github.com/RuminantFarmSystems/RuFaS/pull/2934) - [minor change] [NoInputChange] [NoOutputChange] [Animal][Reproduction] Refactor `Reproduction.execute_cow_ed_protocol()`. +- [2840](https://github.com/RuminantFarmSystems/RuFaS/pull/2840) - [minor change] [Docs] [NoInputChange] [NoOutputChange] Adds page documenting workflow to acheive version update. ### v1.0.0 From 1d1f3496e3b7b5ddf542fced58c6a3e05e409cfd Mon Sep 17 00:00:00 2001 From: Kristan <41019131+KFosterReed@users.noreply.github.com> Date: Sun, 12 Apr 2026 15:35:36 -0400 Subject: [PATCH 4/4] Clarify patch update process in documentation Updated wording for clarity and consistency in the version update workflow documentation. --- docs/_src/_wiki/Version-Update-Workflow.rst | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/_src/_wiki/Version-Update-Workflow.rst b/docs/_src/_wiki/Version-Update-Workflow.rst index 1f2e839253..c4be27afdb 100644 --- a/docs/_src/_wiki/Version-Update-Workflow.rst +++ b/docs/_src/_wiki/Version-Update-Workflow.rst @@ -41,15 +41,12 @@ Before Merging ``dev`` to ``test`` ^^^^^^^^^^^^^^^^^^ Patch updates do not require a full project. Bug fixes required in the patch should be collected -as sub-issues under a **Patch version update parent issue**. +as sub-issues under a Patch parent/tracker issue. After ``test`` is updated ------------------------- -- During the testing phase, SME Maintainers will evaluate integrated model performance. -(link to Scientific Evaluation Process). -- When the model performance has been verified by at least one SME Maintainer per Module, -the Scientific Director will prepare a Scientific Report summarizing the model performance and changes in scientific methodology. +- During the testing phase, SME Maintainers will evaluate integrated model performance. (link to Scientific Evaluation Process). +- When the model performance has been verified by at least one SME Maintainer per Module, the Scientific Director will prepare a Scientific Report summarizing the model performance and changes in scientific methodology. - The Director of Software Engineering will lead preparation of a set of Release Notes to summarize model updates. -- When the testing phase is complete, both the Scientific Report and Release notes are added to the project documentation on GitHub -and shared with the PML for approval. +- When the testing phase is complete, both the Scientific Report and Release notes are added to the project documentation on GitHub and shared with the PML for approval.