Update versioning and branching documentation

[PooyaHekmati]

Context

Issue(s) closed by this pull request: closes #2797

What

Enhance the clarity and detail of the versioning and branching strategy documentation for RuFaS.

Why

This documentation aims to support consistent practices and clear communication among team members.

How

The updates include improved descriptions of branch purposes, usage, and merging processes to ensure a better understanding of the workflow.

Test plan

N/A

Input Changes

N/A

Output Changes

• N/A

Filter

[github-actions]

Current Coverage: 99%

Mypy errors on version-hygene branch: 1684
Mypy errors on dev branch: 1684
No difference in error counts

[github-actions]

🚨 Please update the changelog. This PR cannot be merged until changelog.md is updated.

[github-actions]

Current Coverage: 99%

Mypy errors on version-hygene branch: 1684
Mypy errors on dev branch: 1684
No difference in error counts

[github-actions]

Current Coverage: 99%

Mypy errors on version-hygene branch: 1684
Mypy errors on dev branch: 1684
No difference in error counts

[KFosterReed]

Thank you for leading this effort Pooya! A couple of questions:

• Do we need to consider how a bug fix or patch update/release be handled in the case that dev and/or test is already working towards a minor (or major) release?
• Should we specify who decides whether a release should increment major, minor or patch? Is it the same for all 3 types of version updates? This decision is referenced in the "Merging to test" section o fthe Branching Strategy page and in the first step of the "Version Number Update Process" of the RuFaS Versioning Policy page. My thoughts are that we don't want/need to be too prescriptive but some clarity on who is making these decisions is needed.
• For Major updates (and Maybe Minor updates?) do we need to consider parallel development work that we might need to manage and exclude from version updates? I am thinking about the example of the genetics feature (among others) that we intentionally held back from the major version update. Does that process of freezing dev need to be included in the branch management or is that soley in the sphere of maintainer communication?
• In the "Version Number Update Process" do we need to refernece and then link to the SME review process? Also, should this process be the same or different for Major, Minor, and patch updates?

I think that is it for now!

[KFosterReed]

Other questions that came up on Issue #2796 :

• If a dev freeze period is included in the branch management description: who freezes? For how long or what is required to unfreeze?
• Who merges dev --> test? (Currently it says it just needs 1 review which would imply that any maintainer can update test with one review which doesn't seem like enough protections to me?)
• Should the Changelog summary/releasenote generation be added to the versioning policy description of the process?
• Clarify who owns the steps in the "Update Version Number Process" in the Versioning Policy page.

[PooyaHekmati]

Thanks for your review, @KFosterReed !

• Do we need to consider how a bug fix or patch update/release be handled in the case that dev and/or test is already working towards a minor (or major) release?

I don't think so. This is not a critical system where not fixing bug in few days causes millions of dollars of damage. If we need to make a fix once dev has been pulled to dev, we have ways to handle it. I think it can wait for the actual release.

• Should we specify who decides whether a release should increment major, minor or patch? Is it the same for all 3 types of version updates? This decision is referenced in the "Merging to test" section o fthe Branching Strategy page and in the first step of the "Version Number Update Process" of the RuFaS Versioning Policy page. My thoughts are that we don't want/need to be too prescriptive but some clarity on who is making these decisions is needed.

PML does this.

• For Major updates (and Maybe Minor updates?) do we need to consider parallel development work that we might need to manage and exclude from version updates? I am thinking about the example of the genetics feature (among others) that we intentionally held back from the major version update. Does that process of freezing dev need to be included in the branch management or is that soley in the sphere of maintainer communication?

When something is merged into dev, it means it is ready to be included in the next release. If something needs to be withheld from the next release, then it needs to remain on a separate parking branch until it is ready to be released.

• In the "Version Number Update Process" do we need to refernece and then link to the SME review process? Also, should this process be the same or different for Major, Minor, and patch updates?

Yes, once we have that page ready.

• If a dev freeze period is included in the branch management description: who freezes? For how long or what is required to unfreeze?

We shouldn't need to freeze dev in normal operations.

• Who merges dev --> test? (Currently it says it just needs 1 review which would imply that any maintainer can update test with one review which doesn't seem like enough protections to me?)

Thanks, fixed

• Should the Changelog summary/releasenote generation be added to the versioning policy description of the process?

I think it is better to keep it out for now.

• Clarify who owns the steps in the "Update Version Number Process" in the Versioning Policy page.

[github-actions]

Current Coverage: 99%

Mypy errors on version-hygene branch: 1509
Mypy errors on dev branch: 1509
No difference in error counts

[elle-andreen]

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?

[PooyaHekmati]

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

[elle-andreen]

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.

[LisaM-kiwi]

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.

[KFosterReed]

When something is merged into dev, it means it is ready to be included in the next release. If something needs to be withheld from the next release, then it needs to remain on a separate parking branch until it is ready to be released.

If a dev freeze period is included in the branch management description: who freezes? For how long or what is required to unfreeze?
We shouldn't need to freeze dev in normal operations.

I think we know that RuFaS is not a normal operation... improving our process for what new features are planned for the next release will help a lot but with this recent effort to update the version, we needed to freeze dev and given that our team is spread across institutions, working asynchronously and often working on different tasks, even with improved communication, I think having guidance on when and how we would freeze dev when making a major or minor update makes sense.

[KFosterReed]

I think this is clear and concise. I like the additional call out to PML and admins for their responsibilty of certain tasks. I will add a sentence referencing the SME review process in the "Testing Phase" after merging to test.

Thanks for leading this effort Pooya!

[github-actions]

Current Coverage: 99%

Mypy errors on version-hygene branch: 1191
Mypy errors on dev branch: 1191
No difference in error counts

[github-actions]

Current Coverage: 99%

Mypy errors on version-hygene branch: 1191
Mypy errors on dev branch: 1191
No difference in error counts

[LisaM-kiwi]

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

[LisaM-kiwi]

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.

[LisaM-kiwi]

Link isn't appearing properly in the preview, it works but doesn't look right.

[LisaM-kiwi]

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

[LisaM-kiwi]

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