docs: add adoption guidance docs and example files

README.md

@@ -4,27 +4,64 @@
 
 This specification provides a mechanism for projects to report information about their security in a machine-processable way. It is formatted as a YAML file to make it easy to read and edit by humans.
 
-The data tracked within this specification is intended to fill the gaps between simplified solutions such as `SECURITY.md` and comprehensive automatable solutions such as SBOMs. In that gap lay elements that must be self-reported by projects to allow end-users to make informed security decisions.
+The data tracked within this specification is intended to fill the gaps between simplified solutions such as `SECURITY.md` and comprehensive automated solutions such as SBOMs. In that gap lay elements that must be self-reported by projects to allow end-users to make informed security decisions.
 
-## Usage
+## Usage by project maintainers
 
-Projects should include a `security-insights.yml` file in the root of their repository, or in the appropriate source forge directory such as `.github/` or `.gitlab/`. Users should assume the contents of that file will be updated any time the relevant information changes.
+We hope your project appreciates the value the specification provides and makes the decision to use it. Here's how you can.
 
-To ensure you are adhering to an official version of the specification, please refer to the `specification.md` in the [latest release](https://github.com/ossf/security-insights-spec/releases/latest), which is a versioned compilation of all details.
+### Initial Adoption
+
+Projects adopting the specification in a single project repository should be able to get started and produce a useful `security-insights.yml` in about 30 minutes by consulting the [`template-minimum.yml`](template-minimum.yml).
+
+If your project has multiple repositories, you can apply the specification across all of them quickly by reusing the `project` definition from a single source. Consult [`template-multi-repository-project.yml`](template-multi-repository-project.yml) and [`template-multi-repository-project-reuse.yml`](template-multi-repository-project-reuse.yml) that are relevant to this use case.
+
+Projects should include a `security-insights.yml` file in the root of their repository, or in the appropriate source forge directory such as `.github/` or `.gitlab/`.
+
+To ensure you are adhering to an official version of the specification, please refer to the `schema.cue` and `Security-Insights-{version}.pdf` in the [latest release](https://github.com/ossf/security-insights-spec/releases/latest).
+
+### Plan your project security investments
+
+In reviewing the schema, the examples, and creating a `security-insights.yml` for your project, you probably found many parts of the specification that you would like to be able to add over time. It can be helpful to refer to [`template-full.yml`](template-full.yml) and identify sections for targeted improvement. Consider filing issues in your project's issue tracker for each section so the community understands how you prioritize these investments.
+
+### Ongoing Maintenance
+
+As the project and community around it evolve over time, so too does the project's security posture. As the posture of the project changes, these changes should be reflected in updates to `security-insights.yml`. In the example below, we see the insights data was `last-updated` quite some time ago, but the `last-reviewed` highlights the project's ongoing maintenance efforts to review the data for accuracy.
+
+```yaml
+header:
+  schema-version: 2.0.0
+  last-updated: '2025-01-15'
+  last-reviewed: '2025-04-03' # no changes needed, reviewed as part of last minor version release
+```
+
+Consider using [a scheduled issue](https://docs.github.com/en/actions/use-cases-and-examples/project-management/scheduling-issue-creation) in your project's issue tracker to review the data every 1, 3 or 6 months and make required updates to `security-insights.yml`.
+
+## Usage by project consumers
+
+Consumers of the `security-insights.yml` file(s) provided by projects should assume the contents will be updated any time the relevant information changes.
+
+## Releases
 
 This repository often remains unchanged from the latest release, but may diverge as incremental development takes place in preparation for an upcoming release. Any differences between the latest release and the main branch should only be considered previews of the next release.
 
-As the adoption of Security Insights grows, so does the opportunity to automatically ingest it. For example, the Linux Foundation's [CLOMonitor](https://clomonitor.io/) parses a project's Security Insights file to determine whether projects have reported on select security factors prioritized by the foundation.
+## Tooling Ecosystem
+
+As the adoption of Security Insights grows, so does the opportunity to automatically ingest it. For example, the Linux Foundation's [CLOMonitor](https://clomonitor.io/) parses a project's Security Insights file to determine whether projects have reported on select security factors prioritized by the foundation. The [si-tooling](https://github.com/ossf/si-tooling) repository has community-maintained tools for reading, validating and manipulating the data.
 
 ## Maintenance
 
 The specification maintenance occurs in the following places:
 
 - `specification/`: Contains markdown details for all specification values
 - `schema.cue`: Contains the CUE schema that can be used to validate files against the specification
+
+Examples are also available to provide further context to the specification details above.
+
 - `template-full.yml`: Contains a template that includes all possible fields
-- `template-minimal.yml`: Contains a template that includes only the required fields
+- `template-minimum.yml`: Contains a template that includes only the required fields
+- `template-multi-repository-project.yml`: Contains an extension of `template-minimum.yml` for the primary repository of a multi-repository project
+- `template-multi-repository-project-reuse.yml`: Contains a template for a secondary repository of a multi-repository project
 
-Discussion and feedback should take place in [GitHub Issues](https://github.com/ossf/security-insights-spec/issues). 
+Discussion and feedback should take place in [GitHub Issues](https://github.com/ossf/security-insights-spec/issues). We ask that you follow the [Security Insights Enhancement Proposal](./docs/GOVERNANCE.md#security-insights-enhancement-proposals) process to explore potential changes to the specification.
 
-Because this specification receives light maintenance and infrequent updates, beginning in 2025 we ask that you follow the [Security Insights Enhancement Proposal](./docs/GOVERNANCE.md#security-insights-enhancement-proposals) process to explore potential changes to the specification.

template-full.yml

@@ -1,7 +1,7 @@
 header:
   schema-version: 2.0.0
-  last-updated: '2021-09-01'
-  last-reviewed: '2022-09-01'
+  last-updated: '2025-03-01'
+  last-reviewed: '2025-04-01'
   url: https://example.com/foo/bar
   comment: |
     This file contains all possible information for both project and repository,

template-minimum.yml

@@ -1,7 +1,7 @@
 header:
   schema-version: 2.0.0
-  last-updated: '2021-09-01'
-  last-reviewed: '2022-09-01'
+  last-updated: '2025-03-01'
+  last-reviewed: '2025-04-01'
   url: https://example.com/kubernetes/kubernetes
   comment: |
     This file contains the minimum information for both project and repository.

template-multi-repository-project-reuse.yml

@@ -0,0 +1,28 @@
+# Repository template for a multi-repository project
+# This file would be stored in the https://vcs.example.com/foobar/bar repository
+header:
+  schema-version: 2.0.0
+  last-updated: '2025-03-01'
+  last-reviewed: '2025-04-01'
+  url: https://example.com/kubernetes/kubernetes
+  project-si-source: https://vcs.example.com/foobar/foo/security-insights.yml
+
+repository:
+  url: https://vcs.example.com/foobar/bar
+  status: active
+  accepts-change-request: true
+  accepts-automated-change-request: true
+  core-team:
+    - name:        Alice White
+      affiliation: Foo Bar
+      email:       alicewhite@email.com
+      social:      https://social.example.com/alicewhite
+      primary:     true
+  license:
+    url: https://example.com/LICENSE
+    expression: MIT
+  security:
+    assessments:
+      self:
+        comment: |
+          Self assessment has not yet been completed.

template-multi-repository-project.yml

@@ -0,0 +1,53 @@
+# Project and repository template for a multi-repository project
+# This file would be stored in the https://vcs.example.com/foobar/foo repository
+# and addressable via https://vcs.example.com/foobar/foo/security-insights.yml
+header:
+  schema-version: 2.0.0
+  last-updated: '2025-03-01'
+  last-reviewed: '2025-04-01'
+  url: https://example.com/kubernetes/kubernetes
+  comment: |
+    This file contains the minimum information for both project and repository.
+    It not required to include both a project and repository section if the project
+    section is intended to be inherited by repositories via header.project-si-source
+
+project:
+  name: FooBar
+  administrators:
+    - name: Joe Dohn
+      affiliation: Foo
+      email: joe.bob@example.com
+      social: https://social.example.com/joebob
+      primary: true
+  repositories:
+    - name: Foo
+      url: https://vcs.example.com/foobar/foo
+      comment: |
+        Foo is the core repo for FooBar.
+    - name: Bar
+      url: https://vcs.example.com/foobar/bar
+      comment: |
+        Bar is also part of the FooBar project.
+  vulnerability-reporting:
+    reports-accepted: true
+    bug-bounty-available: true
+
+repository:
+  url: https://vcs.example.com/foobar/foo
+  status: active
+  accepts-change-request: true
+  accepts-automated-change-request: true
+  core-team:
+    - name:        Alice White
+      affiliation: Foo Bar
+      email:       alicewhite@email.com
+      social:      https://social.example.com/alicewhite
+      primary:     true
+  license:
+    url: https://example.com/LICENSE
+    expression: MIT
+  security:
+    assessments:
+      self:
+        comment: |
+          Self assessment has not yet been completed.