Refactor Documentation Requirements & Titles

baseline/OSPS-DO.yaml

@@ -9,8 +9,8 @@ description: |
 controls:
   - id: OSPS-DO-01
     title: |
-      Provide user guides for all basic functionality in the project
-      documentation
+      The project documentation MUST provide user guides for all basic
+      functionality.
     objective: |
       Ensure that users have a clear and comprehensive understanding of the
       project's current features in order to prevent damage from misuse or
@@ -44,8 +44,8 @@ controls:
     assessment-requirements:
       - id: OSPS-DO-01.01
         text: |
-          The project documentation MUST provide user guides for all basic
-          functionality.
+          When the project has made a release, the project documentation MUST
+          include user guides for all basic functionality.
         applicability:
           - Maturity Level 1
           - Maturity Level 2
@@ -58,7 +58,7 @@ controls:
 
   - id: OSPS-DO-02
     title: |
-      Include a mechanism for reporting defects in the project documentation
+      The project MUST provide a mechanism for reporting defects.
     objective: |
       Enable users and contributors to report defects or issues with the
       released software assets, facilitating communication and collaboration on
@@ -96,8 +96,8 @@ controls:
     assessment-requirements:
       - id: OSPS-DO-02.01
         text: |
-          The project documentation MUST include a mechanism for reporting
-          defects.
+          When the project has made a release, the project documentation MUST
+          include a guide for reporting defects.
         applicability:
           - Maturity Level 1
           - Maturity Level 2
@@ -111,8 +111,10 @@ controls:
 
   - id: OSPS-DO-03
     title: |
-      Include instructions to verify the integrity and authenticity of release
-      assets in the project documentation
+      The project documentation MUST contain instructions to verify the
+      integrity and authenticity of the release assets, including the
+      expected identity of the person or process authoring the software
+      release.
     objective: |
       Enable users to verify the authenticity and integrity of the project's
       released software assets, reducing the risk of using tampered or
@@ -138,26 +140,36 @@ controls:
     assessment-requirements:
       - id: OSPS-DO-03.01
         text: |
-          The project documentation MUST contain instructions to verify the
-          integrity and authenticity of the release assets, including the
-          expected identity of the person or process authoring the software
-          release.
+          When the project has made a release, the project documentation MUST
+          contain instructions to verify the integrity and authenticity of the
+          release assets.
         applicability:
           - Maturity Level 3
         recommendation: |
           Instructions in the project should contain information about the
-          technology used, the commands to run, and the expected output. The
-          expected identity may be in the form of key IDs used to sign, issuer
-          and identity from a sigstore certificate, or other similar forms.
+          technology used, the commands to run, and the expected output.
+          When possible, avoid storing this documentation in the same location
+          as the build and release pipeline to avoid a single breach
+          compromising both the software and the documentation for verifying the
+          integrity of the software.
+      - id: OSPS-DO-03.02
+        text: |
+          When the project has made a release, the project documentation MUST
+          contain instructions to verify the expected identity of the person or
+          process authoring the software release.
+        recommendation: |
+          The expected identity may be in the form of key IDs used to sign,
+          issuer and identity from a sigstore certificate, or other similar
+          forms.
           When possible, avoid storing this documentation in the same location
           as the build and release pipeline to avoid a single breach
           compromising both the software and the documentation for verifying the
           integrity of the software.
 
   - id: OSPS-DO-04
     title: |
-      Include a descriptive statement about the scope and duration of support
-      in the project documentation
+      The project documentation MUST include a descriptive statement about
+      the scope and duration of support.
     objective: |
       Provide users with clear expectations regarding the project's support
       lifecycle. This allows downstream consumers to take relevant actions to
@@ -179,8 +191,9 @@ controls:
     assessment-requirements:
       - id: OSPS-DO-04.01
         text: |
-          The project documentation MUST include a descriptive statement about
-          the scope and duration of support.
+          When the project has made a release, the project documentation MUST
+          include a descriptive statement about the scope and duration of
+          support for each release.
         applicability:
           - Maturity Level 3
         recommendation: |
@@ -190,8 +203,8 @@ controls:
 
   - id: OSPS-DO-05
     title: |
-      Provide a descriptive statement when releases or versions will no longer
-      receive security updates in the project documentation
+      The project documentation MUST provide a descriptive statement when
+      releases or versions will no longer receive security updates.
     objective: |
       Communicating when the project maintainers will no longer fix defects or
       security vulnerabilities is crucial for downstream consumers to find
@@ -213,8 +226,9 @@ controls:
     assessment-requirements:
       - id: OSPS-DO-05.01
         text: |
-          The project documentation MUST provide a descriptive statement when
-          releases or versions will no longer receive security updates.
+          When the project has made a release, the project documentation MUST
+          provide a descriptive statement when releases or versions will no
+          longer receive security updates.
         applicability:
           - Maturity Level 3
         recommendation: |
@@ -224,8 +238,8 @@ controls:
 
   - id: OSPS-DO-06
     title: |
-      Describe how the project selects, obtains, and tracks its dependencies in
-      the project documentation
+      The project documentation MUST include a description of how the
+      project selects, obtains, and tracks its dependencies.
     objective: |
       Provide information about how the project selects, obtains, and tracks
       dependencies, libraries, frameworks, etc. to help downstream consumers
@@ -246,8 +260,9 @@ controls:
     assessment-requirements:
       - id: OSPS-DO-06.01
         text: |
-          The project documentation MUST include a description of how the
-          project selects, obtains, and tracks its dependencies.
+          When the project has made a release, the project documentation MUST
+          include a description of how the project selects, obtains, and tracks
+          its dependencies.
         applicability:
           - Maturity Level 2
           - Maturity Level 3