diff --git a/software-development-practices.md b/software-development-practices.md index 173c7ad..55cf295 100644 --- a/software-development-practices.md +++ b/software-development-practices.md @@ -12,16 +12,26 @@ _**Document status:** Working draft. Suggested categories, checks, and priority | Item | Description/Notes | Priority | | ------- | --------- | -------- | | Versioning| ROOST projects are using semantic versioning | P1 | -| Branching | Are there different branches for stable and development? | P0 | +| Branching | To start, ROOST projects should use `main` as the branch for development, and use the GitHub Release feature (via semver-tagged commits) to denote releases. This will need to be revisited as projects mature and have to handle backporting patches, but the ethos is "minimum viable complexity." | P0 | ## Release cadence | Item | Description/Notes | Priority | | ------- | --------- | -------- | | Initial Process | * Identify big features on 12 month timeline. These are _substantial_ changes (think blog headline).
* Estimate delivery time in quarters of big features and group features with similar timelines together. Bundle breaking changes when possible.
* Add minor features/changes to timeline. Bundle together for as consistent cadence as possible.
* Patch versions can be cut at any time as needed for bug fixes. | P0 | +## Project conventions +| Item | Description/Notes | Priority | +| ----- | ---------------- | --------- | +| README.md | All projects/repos must have a README file in markdown format. At minimum, the README must have a description of what the project does, information for how to start using it (can link to longer getting started documentation), and links to the CONTRIBUTING.md and Code of Conduct. | P0 | +| AGENTS.md | Add a markdown file to guide AI coding assistants following the open [AGENTS.md format](https://github.com/agentsmd/agents.md) | P1 | +| API format | Projects should follow the [TBD] API description format | P1 | +| CHANGELOG.md | Projects must have a CHANGELOG.md file, following the [Keep A Changelog format](https://keepachangelog.com/en/1.1.0/) | P0 | +| Contributor guidance | All projects must have a CONTRIBUTING.md file at minimum. By default this is inherited from ROOST's .github, but can be updated at the per-project level. Additional documentation for first time contributors describing project conventions and code quality expectations is recommended. | P0 | +| CODE_OF_CONDUCT.md | All projects must have a CODE_OF_CONDUCT.md with the ROOST Code of Conduct. This is automatically inherited from ROOST's .github and should not be changed. | P0 | ## Testing practices | Item | Description/Notes | Priority | | ------- | --------- | -------- | | Tests for all commits | 1) Unit tests
2) Lint checks
3) Integration tests
4) Build checks | P0 | | Release tests | End-to-end testing for Major and Minor releases | P0 | +| CI checks | Determine the relevant CI checks for the project and enforce that all CI checks pass | P0 | ## Dependency handling | Item | Description/Notes | Priority | | ------- | --------- | -------- | @@ -32,7 +42,7 @@ _**Document status:** Working draft. Suggested categories, checks, and priority ## Security in CI/CD | Item | Description/Notes | Priority | | ------- | --------- | -------- | -| Fuzzing | At what milestones? | P2 | +| Fuzzing | Determine what surfaces or characteristics of surfaces should be fuzzed and at what cadence (including planning for triage and remediation at that cadence) | P2 | | Code analysis | CodeQL, secret and token scanning, etc | P1 | | Binary artifact detection | Flagging checked in binaries | P2 | | Commit-time vuln detection | Flags for packages with known CVEs | P2 | @@ -47,7 +57,7 @@ _**Document status:** Working draft. Suggested categories, checks, and priority | ------- | --------- | -------- | | Issue labeling | How can this be automated or less burdensome? | P2 | | PR labeling| How can this be automated or less burdensome, and identify priority? | P2 | -| Code review guidance | What should reviewers pay attention to? | P1 | +| Code review guidance | Project documentation should include a section on how to help with code review, and highlight any particular areas code reviewers should pay attention to | P1 | ## Support | Item | Description/Notes | Priority | | ------- | --------- | -------- |