Add software development practices for ROOST projects (#45)

[annebdh]

Initial working document for software development practices for ROOST projects, such as dependency handling, versioning, and code review practices.
Issue #45

Contains contributions from @juanmrad and @tpepper.

[annebdh]

Tagging Technical Design Committee members @tgthorley and @haileyok for their thoughts as well

[tgthorley]

This is a great start!! Love an SDLC doc!

I'll add some comments in line, but I think the only thing really missing totally that I'd recommend is some minimum expectations around documentation. Things like:

• What are your README minimum requirements
• What API docs are required and what specification are you using? OpenAPI Specification (OAS)?
• What is your changelog policy?
• ...

If we are using coding agents and/or agent skills I also recommend using copilot-instructions or agents.md in repos as well so that you can enforce things like coding style, naming conventions and other standards that you want to apply across the repo by default.

[tgthorley]

Rather than uses branches for stable versions consider using GitHub Releases for shipping and distributing version of a project and GitHub Packages for hosting and distributing packages/containers.

[cassidyjames]

Yeah, agreed; generally I think we see it like:

• main should be the latest development branch while ensuring some level of automated testing (i.e. CI needs to pass to merge into main)
• feature development is done in other named branches and merged into main
• releases are tagged on main and versioned according to semver

I think the edge case is that if at some point we find a need to patch something in a stable 1.0 version even after we have released a 2.0, we could have a (for example) v1.0.1 branch that has a backport of the patches and then tag and release that… but I don't think we should aim to maintain multiple versions simultaneously as a rule. It starts to get messy real quick.

[juanmrad]

It is very normal practice to cut a branch for a version alongside the tag to do exactly what you mention. The need to be able to patch things after a release. like security patch or minor bugs. For Roost tho I think we can keep things to a minimal.
There is definitively no need to handle multiple branches. My recommendation is:

Define milestones that will be tied to major version releases. Define epics on those milestones to tie to minor version releases. Effectively once X amount of features or meaningful features have been merged we cut a minor release.

Patches for bug fixes and minor corrections.

[haileyok]

Definitely agree with using GH releases. Generally what I've done in the past is tag a commit on main and use that in the GH release. If patches for that release need to get shipped, a branch from that tag can get created (either at initial release time or when the need for a patch arises) and the patched version can also get tagged for a new GH release.

[tpepper]

GitHub Releases should be fine for producing releases from a git tag.

But the intersection of the question of "which tag?", the content of the repo at that tag, and the choice of semver tend to lead to branching. This is especially the case in the context of an org like ROOST. Given that ROOST aims to be a supplier of commonly used infrastructure software components, it is likely that the downstream adoptees will want a stable support stance for its projects and that very likely ends up requiring branching.

As a reminder, semver is defined to mean:
Given a version number MAJOR.MINOR.PATCH, increment the:

1. MAJOR version when you make incompatible API changes
2. MINOR version when you add functionality in a backward compatible manner
3. PATCH version when you make backward compatible bug fixes

For simple ROOST projects, it might well suffice to make a branch only if very much needed and keep dev operations simpler. For Coop it might well be only later a concern. For Osprey, I suspect it comes sooner, but it may also suffice in the near term for dev purposes to more rapidly and flexibly roll forward until a point at which or if consumers request less churn.

Coop's currently at 0.0 and Opsrey at 1.0.1.

[tgthorley]

For fuzzing I'd suggest identifying the surfaces (or characteristics of surfaces that you need to fuzz) and then the cadence against which you aim to run automated processes and triage the results.

[annebdh]

Would you agree the P2 categorization? eg capture all these questions, but punt resolving them til further along?

[vinaysrao1]

I agree with fuzzing being a P2, would love Tom's thoughts.

[annebdh]

I'll add some comments in line, but I think the only thing really missing totally that I'd recommend is some minimum expectations around documentation. Things like:

• What are your README minimum requirements
• What API docs are required and what specification are you using? OpenAPI Specification (OAS)?
• What is your changelog policy?

Great call outs; I'll get those added.

If we are using coding agents and/or agent skills I also recommend using copilot-instructions or agents.md in repos as well so that you can enforce things like coding style, naming conventions and other standards that you want to apply across the repo by default.

+1 on an agents.md file. We haven't yet explored all the GitHub AI-assistance features available to us (I'm still getting my head around what's enabled at the repo level vs individual account), but better to have good practices documented now for anyone using in-IDE assistance.

[annebdh]

Tagging Osprey and Coop codeowners for their visibility and input too: @EXBreder @dom-notion

[haileyok]

Definitely a proponent of establishing a good agents.md/CLAUDE.md for repos. Regardless of maintainers personal preferences on use of those tools, it is inevitable that contributors will use these tools and I think it's a good idea to establish some clear patterns for the agents ahead of time, since that hopefully will increase the quality of PRs submitted that use those tools! (ie making sure the agents understand at least the basic requirements of and how to run tests etc. as well as the overall common patterns in respective codebases)

[vinaysrao1]

Definitely a proponent of establishing a good agents.md/CLAUDE.md for repos. Regardless of maintainers personal preferences on use of those tools, it is inevitable that contributors will use these tools and I think it's a good idea to establish some clear patterns for the agents ahead of time, since that hopefully will increase the quality of PRs submitted that use those tools! (ie making sure the agents understand at least the basic requirements of and how to run tests etc. as well as the overall common patterns in respective codebases)

With claude skills, fairly tight code constraints can be added. For example: running pyright, ruff, threading related checks etc. For most part, this is trivially easy once the skills have been set up as agents will just apply it.