diff --git a/SUMMARY.md b/SUMMARY.md index 648ed67..e915c86 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -8,6 +8,7 @@ - [Software Development Practices](software-development-practices/README.md) - [APIs](software-development-practices/api.md) - [Agents](software-development-practices/agents.md) + - [Security](software-development-practices/security.md) - [Documentation Guidelines](documentation.md) - [Meetings](meetings/README.md) - [Guidelines](meetings/guidelines.md) diff --git a/software-development-practices/README.md b/software-development-practices/README.md index 56233c5..df217f1 100644 --- a/software-development-practices/README.md +++ b/software-development-practices/README.md @@ -1,23 +1,30 @@ -# Software Development Practices for ROOST Projects +# Software Development Practices Good software development lifecycle (SDLC) is an endless journey, but it's hard to make progress if you don't know where you're going. This document is intended to be a checklist for ROOST projects to work through as they mature. _**Document status:** Working draft. Suggested categories, checks, and priority below._ ## Quality vision + | Item | Description/Notes | Priority | | ------- | --------- | -------- | | Intention statement | Sets the ethos for what kind of software we're building and for who. | P0 | + ## Versioning + | Item | Description/Notes | Priority | | ------- | --------- | -------- | | Versioning| ROOST projects are using semantic versioning | P1 | | 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 | @@ -26,44 +33,62 @@ _**Document status:** Working draft. Suggested categories, checks, and priority | 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 | | ------- | --------- | -------- | | Version alerts | Automated alerts and process for updating dependencies | P0| | Vulnerability alerts | Automated alerts and process for updating dependencies | P0| | License scanning | Ensuring compatible licenses for dependencies added via CI | P1 | | Vendoring policy | Do we ever vendor deps? | P2 | -## Security in CI/CD + +## Security + +See the dedicated [Security](security.md) page for more information about our security response process and security releases. + +### CI/CD + | Item | Description/Notes | Priority | | ------- | --------- | -------- | | 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 | -## Release security + +### Releases + | Item | Description/Notes | Priority | | ------- | --------- | -------- | | Signed releases | | P3 | -| Security report intake | See .github/security.md | P0 | -| Incident response process | See OpenSSF process | P1 | +| Security report intake | See [Security](security.md) | P0 | +| Incident response process | See [Security](security.md) | P1 | + ## PR triage and code review + | Item | Description/Notes | 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 | 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 | | ------- | --------- | -------- | | Breaking changes policy | Following semver, breaking changes go in Major versions. This policy is about when it's appropriate to introduce a breaking change and how it should be communicated to users (timeline, expectations, support) | P1 | | Long term support (LTS) policy | How many versions back does the community support? | P3 -- address later | + ## Deprecation + | Item | Description/Notes | Priority | | ------- | --------- | -------- | | Deprecation process | | P3 -- address when needed | diff --git a/software-development-practices/security.md b/software-development-practices/security.md new file mode 100644 index 0000000..5c2deb2 --- /dev/null +++ b/software-development-practices/security.md @@ -0,0 +1,28 @@ +# Security + +> [!NOTE] +> To report a vulnerability or security issue, visit [SECURITY.md](https://github.com/roostorg/.github/blob/main/SECURITY.md) + +This page contains information on how ROOST handles reported security vulnerabilities. We refer to this as our "security response process," and to project releases made during this process as "security releases." + +## Security response process + +ROOST follows the principles of coordinated vulnerability disclosure (CVD). This means we prioritize working with the reporter to create, test, and distribute a fix. You can read more about CVD in open source projects from the [Open Source Security Foundation](https://github.com/ossf/oss-vulnerability-guide). + +### Security reports + +Anyone may submit a security vulnerability report for ROOST open source projects following the submission directions at [SECURITY.md](https://github.com/roostorg/.github/blob/main/SECURITY.md). Reports go to ROOST staff, who triage them based on the potential severity and impact. Staff will validate the report through re-creation, and determine if it is a bug, missing feature, or security vulnerability. + +If a report is confirmed to be a security vulnerability, staff will accept the report and begin developing and testing a patch. Technical Design Committee members or project code owners with relevant expertise may be brought in to validate the vulnerability or patch. A CVE will be created, and once a patch is verified it will be staged for release. Disclosure communications will be prepared in parallel. + +### Security releases + +The severity, impact, and timing of the vulnerability will determine if the security patch is released as part of the next scheduled patch release, or a one-time, security release is tagged. In general, the default is to merge patches as soon as they are available and create security releases. + +Security releases will be announced through GitHub Security Advisories (visible in the "Security" tab on the corresponding project) and announced on the [security-announce@roost.tools mailing list](https://groups.google.com/a/roost.tools/g/security-announce). The announcement will describe the vulnerablity, the affected versions, and what if any action users need to take to apply the patch. + +If you are a vendor offering ROOST tools, you may receive early notification of security patch release dates. To qualify, your offering must be hosted in such a way that users cannot self-patch. Please email for more information. + +## Process evolution and ethos + +As with other ROOST processes, our security response process will continuously evolve as our projects do and as we receive user feedback. Our ethos is to have the "minimum viable governance" for our security release process that is responsive to security reporters and effectively protects our users.