pg 2

Signed-off-by: Amndeep Singh Mann <[email protected]>
mitre · Dec 9, 2024 · 534686a · 534686a
1 parent 3043ac6
commit 534686a
Showing 1 changed file with 50 additions and 35 deletions.
diff --git a/src/courses/profile-dev-test/02.md b/src/courses/profile-dev-test/02.md
@@ -1,7 +1,7 @@
 ---
 order: 2
 next: 03.md
-title: Understanding Repository Organization
+title: 2. Understanding Repository Organization
 author: Aaron Lippold
 ---
 
@@ -15,25 +15,60 @@ By the end of this section, you will:
 
 ## Repository Structure Overview
 
-The repository uses a structured branching and tagging strategy to manage STIG profile versions and updates. This organization ensures reliable tracking of changes and stable releases for production use.
+The InSpec profile repository should have a structured branching and tagging strategy to manage STIG profile versions and updates. This organizational strategy ensures reliable tracking of changes and stable releases for production use.
 
 ## Branch Strategy
 
-### Main Branch
+Security developers and engineers should be putting actively developed changes and updates into feature branches.  Once those feature branches have been completed and peer reviewed, they should be merged into the version branch for the respective guidance release.  Once all required features, changes, bugfixes, etc. have been merged in, a release should be created - this means that the version branch should be merged into your main branch and a tag should be created.  The main branch of the repository ought to be the latest, working version of the codebase.  
+
+::: tip Branches are not releases
+Sometimes code ends up merged directly to the main branch - this is fine - the main branch is not a formal release.
+:::
+
+<table>
+  <thead>
+    <tr>
+      <th></th>
+      <th scope="col">Main Branch</th>
+      <th scope="col">Version Branch (`v{x}r{xx}`)</th> 
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <th scope="row">Purpose</th>
+      <td>Active development and testing</td>
+      <td>Work-in-progress tracking a major STIG benchmark release</td>
+    </tr>
+    <tr>
+      <th scope="row">Contains</th>
+      <td>Latest code and patches</td>
+      <td><p>Code that is becoming aligned to an official guidance release</p><p>DISA usually releases updates to STIGs on a quarterly basis.  See the [DISA STIG Document Library](https://public.cyber.mil/stigs/downloads/).</p></td>
+    </tr>
+    <tr>
+      <th scope="row">Example branch name</th>
+      <td>`main` or `master`</td>
+      <td>`v1r12` for Version 1, Release 12</td>
+    </tr>
+  </tbody>
+</table>
+
+## Version Control and Tagging Strategy
+
+### Tags
+
+#### Current Tag
+
+We do not recommend using a `current` or `latest` tag - if someone needs the latest and greatest, they can pull directly from the main branch of the repository.
+
+#### Major Tags
+
+Major tags point to the latest patch releases of the benchmark. For example, `v1`, `v1.3`, and `v1.3.0` all should point at the same commit representing the first release of the Red Hat Enterprise Linux 8 STIG V1R3 Benchmark. The `v1.12.xx` tag(s) would represent the V1R12 Benchmark releases as we find bugs, fixes, or general improvements to the testing profile.
+
+#### Patch Releases
 
-- Purpose: Active development and testing
-- Contains: Latest code and patches
-- Best for: Development and testing workflows
-- Note: For production, use stable releases instead
-
-### Version Branches (`v{x}r{xx}`)
-
-- Purpose: Track major STIG benchmark releases
-- Example: `v1r12` for Version 1, Release 12
-- Aligns with: Official DISA STIG releases
-- Reference: [DISA STIG Document Library](https://public.cyber.mil/stigs/downloads/)
+The latest patch release always points to the major release for the profile.
 
-## Version Control Strategy
+For example, after releasing `v1.12.0`, we will point `v1.12` to that patch release: `v1.12.0`. When an issue is found, we will fix, tag, and release `v1.12.1`. We will then 'move' the `v1.12` tag so that it points to tag `v1.12.1`. This way, your pipelines can choose if they want to pin on a specific release of the InSpec profile or always run using the latest code on the main branch.
 
 ### Semantic Versioning (SemVer)
 
@@ -42,23 +77,3 @@ Format: `MAJOR.RELEASE.PATCH`
 - MAJOR: Matches STIG version
 - RELEASE: Matches STIG release
 - PATCH: Profile updates between STIG releases
-
-Example timeline:
-
-## Tags
-
-### Current Tag
-
-We don't use a specific `current` or `latest` tag. The `current`/`latest` tag for the profile and repository will always be the latest major tag of the benchmark. For example, if `v1.12.3` is the latest Benchmark release from the STIG author, then the tag `v1.12` will point to the `v1.12.3` release of the code.
-
-To use the current `main`, point directly to the GitHub repo.
-
-### Major Tags
-
-Major tags point to the latest patch release of the benchmark. For example, `v1.3` and `v1.3.0` represent the first release of the Red Hat Enterprise Linux 8 STIG V1R3 Benchmark. The `v1.12.xx` tag(s) would represent the V1R12 Benchmark releases as we find bugs, fixes, or general improvements to the testing profile. This tag will point to its `v{x}r{xx}` counterpart.
-
-## Patch Releases
-
-The latest patch release always points to the major release for the profile.
-
-For example, after releasing `v1.12.0`, we will point `v1.12` to that patch release: `v1.12.0`. When an issue is found, we will fix, tag, and release `v1.12.1`. We will then 'move' the `v1.12` tag so that it points to tag `v1.12.1`. This way, your pipelines can choose if they want to pin on a specific release of the InSpec profile or always run 'current'.