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.

[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.

[vinaysrao1]

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.

Once this is merged, I will open a new PR with the API docs and agents.md doc.

[juanmrad]

left a couple more comments on things I think we miss from my perspective 😄

[juanmrad]

I think these two are effectively the same. at least from the description and handled by Dependabot for the most part. We could merge them no?

[annebdh]

We certainly could merge them, and then handling is often the same (re Dependabot, scanners, etc, but not always if someone just sets up a OVS feed). The security person in me likes highlighting that they're different in urgency, but I'm not strongly opinionated here.

[juanmrad]

We should have a section for contribution guidelines. Having explicit contribution guidelines (issue templates, PR templates, Code of Conduct reference, first-time contributor onboarding) is important.

[annebdh]

Updated based on discussions above! Still a handful of "TBD" sections on P2 and P3 items, but this seems like a fine initial starting place!