From 2d9933de8d177d01b8ff970d0e9ade6accf42393 Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Fri, 30 Aug 2024 13:27:27 -0400 Subject: [PATCH 01/10] Create 007-signal-unsupportent-content-in-github.md --- ...7-signal-unsupportent-content-in-github.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 documents/adr/007-signal-unsupportent-content-in-github.md diff --git a/documents/adr/007-signal-unsupportent-content-in-github.md b/documents/adr/007-signal-unsupportent-content-in-github.md new file mode 100644 index 000000000..e945baba6 --- /dev/null +++ b/documents/adr/007-signal-unsupportent-content-in-github.md @@ -0,0 +1,49 @@ +# 7. Signal Unsupported Contents in the Repository + +Date: 2024-08-30 + +## Status + +Pending Community Feedback + +## Context + +The FedRAMP OSCAL automation team needs to cleanup the repository periodically, and establish a way to signal to the community areas of the repository that are no longer maintened (e.g., legacy proof-of-concept tools, outdated documentation / guidance, etc.). + +### Possible Solutions + +Signal unsupported code / content in the repository by: +1. marking the content as **DEPRECATED** in a README +2. **OBSOLETE** in a README + - deleting **OBSOLETE** content after some period of time or at specified release +3. marking the content as **ARCHIVED** and moving to an “archived” folder + +## Consequences + +The above will be applied to the current repository as follows: +* **dist/content/rev4** + * Add README \- FR has transitioned to Rev 5\. Rev 4 baselines, resources, and templates are no longer maintained. + * Mark as **DEPRECATED** +* **dist/content/rev5/resources** + * Update README \- letting community know FedRAMP is transitioning from *fedramp\_extensions.xml* & *fedramp\_values.json* + * FedRAMP to consider future work on replacing them with report of constraints auto-generated by CI (from Metaschema constraints) +* **dist/content/rev5/templates** + * Update README clarifying intent of FedRAMP “template” and documenting known validation issues with each template +* **documents** folder + * Update README sending community to [https://automate.fedramp.gov](https://automate.fedramp.gov) for documentation going forward. Add statement about PDF guides no longer being maintained and that existing GH issues submitted about the guides will be address via updates to [https://automate.fedramp.gov](https://automate.fedramp.gov) + * **documents/rev4/README.md** \- mark as **OBSOLETE** + * **documents/rev5/README.md** \- mark as **OBSOLETE** +* presentations folder + * **presentations/data-bites** + * Update with latest Data Bites slides + * Add **presentations/oscal-implementers** + * Update with latest OSCAL Implementers slides +* **src/examples/README.md** \- **ARCHIVED** + * Move all current contents to archived subfolder (e.g., **src/examples/archived** ) +* **src/utils/extensions-preview.xsl** \- **ARCHIVED** + * Move all current contents to archive subfolder (e.g., **src/examples/archived** ) +* **validations** folder \- **ARCHIVED** + * Move all current contents to archive subfolder (e.g., **src/validations/archived** ) + * Update the README to let community know this is now archived and no longer maintained +* **validations/constraints** \- Plan on adding new validation constraints and associated documentation that is currently in the *feature/external-extensions* branch. + * Once merged from that feature branch and a release is created, it will be available in the master branch for the community. From 22945008970b4e12aae3f52f0a416b46680290f3 Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Fri, 30 Aug 2024 16:17:29 -0400 Subject: [PATCH 02/10] Update ADR 007 --- .../adr/007-signal-unsupportent-content-in-github.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/documents/adr/007-signal-unsupportent-content-in-github.md b/documents/adr/007-signal-unsupportent-content-in-github.md index e945baba6..55ed0b1d8 100644 --- a/documents/adr/007-signal-unsupportent-content-in-github.md +++ b/documents/adr/007-signal-unsupportent-content-in-github.md @@ -22,17 +22,17 @@ Signal unsupported code / content in the repository by: The above will be applied to the current repository as follows: * **dist/content/rev4** - * Add README \- FR has transitioned to Rev 5\. Rev 4 baselines, resources, and templates are no longer maintained. + * Add README \- FR has transitioned to Rev 5\. Rev 4 baselines, resources, and templates are no longer maintained but will be kept frozen for historical purposes. * Mark as **DEPRECATED** * **dist/content/rev5/resources** - * Update README \- letting community know FedRAMP is transitioning from *fedramp\_extensions.xml* & *fedramp\_values.json* - * FedRAMP to consider future work on replacing them with report of constraints auto-generated by CI (from Metaschema constraints) + * Archive README \- letting community know FedRAMP is transitioning from *fedramp\_extensions.xml* & *fedramp\_values.json* + * FedRAMP to consider future work on replacing them with report of constraints auto-generated by CI or OSCAL-CLI (from Metaschema constraints) * **dist/content/rev5/templates** - * Update README clarifying intent of FedRAMP “template” and documenting known validation issues with each template + * Update README clarifying intent of FedRAMP “template” and documenting known validation issues with each template. Where possilbe, FedRAMP will attempt to fix template validation issues to reduce the amount of errors they produce. * **documents** folder * Update README sending community to [https://automate.fedramp.gov](https://automate.fedramp.gov) for documentation going forward. Add statement about PDF guides no longer being maintained and that existing GH issues submitted about the guides will be address via updates to [https://automate.fedramp.gov](https://automate.fedramp.gov) - * **documents/rev4/README.md** \- mark as **OBSOLETE** - * **documents/rev5/README.md** \- mark as **OBSOLETE** + * **documents/rev4/README.md** \- mark as **OBSOLETE** and remove PDF guides + * **documents/rev5/README.md** \- mark as **OBSOLETE** and remove PDF guides * presentations folder * **presentations/data-bites** * Update with latest Data Bites slides From 9c4322a7643fc3e8560bf8df4dd39b2857e015e9 Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Tue, 3 Sep 2024 13:38:41 -0400 Subject: [PATCH 03/10] Update documents/adr/007-signal-unsupportent-content-in-github.md Co-authored-by: A.J. Stein --- documents/adr/007-signal-unsupportent-content-in-github.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/adr/007-signal-unsupportent-content-in-github.md b/documents/adr/007-signal-unsupportent-content-in-github.md index 55ed0b1d8..0b8a2fbaa 100644 --- a/documents/adr/007-signal-unsupportent-content-in-github.md +++ b/documents/adr/007-signal-unsupportent-content-in-github.md @@ -15,7 +15,7 @@ The FedRAMP OSCAL automation team needs to cleanup the repository periodically, Signal unsupported code / content in the repository by: 1. marking the content as **DEPRECATED** in a README 2. **OBSOLETE** in a README - - deleting **OBSOLETE** content after some period of time or at specified release + - deleting **OBSOLETE** content from future releases and leaving archival copies in an archive branch for posterity 3. marking the content as **ARCHIVED** and moving to an “archived” folder ## Consequences From 19c0084f109e864984821a7af371fea8d89420a1 Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Tue, 3 Sep 2024 13:38:54 -0400 Subject: [PATCH 04/10] Update documents/adr/007-signal-unsupportent-content-in-github.md Co-authored-by: A.J. Stein --- documents/adr/007-signal-unsupportent-content-in-github.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/adr/007-signal-unsupportent-content-in-github.md b/documents/adr/007-signal-unsupportent-content-in-github.md index 0b8a2fbaa..c33a62339 100644 --- a/documents/adr/007-signal-unsupportent-content-in-github.md +++ b/documents/adr/007-signal-unsupportent-content-in-github.md @@ -39,7 +39,7 @@ The above will be applied to the current repository as follows: * Add **presentations/oscal-implementers** * Update with latest OSCAL Implementers slides * **src/examples/README.md** \- **ARCHIVED** - * Move all current contents to archived subfolder (e.g., **src/examples/archived** ) + * Delete all current contents * **src/utils/extensions-preview.xsl** \- **ARCHIVED** * Move all current contents to archive subfolder (e.g., **src/examples/archived** ) * **validations** folder \- **ARCHIVED** From e8d1748e6fd74e9a89aeb5884deab10e570b6e2f Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Tue, 3 Sep 2024 13:39:02 -0400 Subject: [PATCH 05/10] Update documents/adr/007-signal-unsupportent-content-in-github.md Co-authored-by: A.J. Stein --- documents/adr/007-signal-unsupportent-content-in-github.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/adr/007-signal-unsupportent-content-in-github.md b/documents/adr/007-signal-unsupportent-content-in-github.md index c33a62339..5c9d6b748 100644 --- a/documents/adr/007-signal-unsupportent-content-in-github.md +++ b/documents/adr/007-signal-unsupportent-content-in-github.md @@ -41,7 +41,7 @@ The above will be applied to the current repository as follows: * **src/examples/README.md** \- **ARCHIVED** * Delete all current contents * **src/utils/extensions-preview.xsl** \- **ARCHIVED** - * Move all current contents to archive subfolder (e.g., **src/examples/archived** ) + * Delete all current contents * **validations** folder \- **ARCHIVED** * Move all current contents to archive subfolder (e.g., **src/validations/archived** ) * Update the README to let community know this is now archived and no longer maintained From d00bf3b481c594a144812c72e4d1dc5e8d80d6eb Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Tue, 3 Sep 2024 13:39:10 -0400 Subject: [PATCH 06/10] Update documents/adr/007-signal-unsupportent-content-in-github.md Co-authored-by: A.J. Stein --- documents/adr/007-signal-unsupportent-content-in-github.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/adr/007-signal-unsupportent-content-in-github.md b/documents/adr/007-signal-unsupportent-content-in-github.md index 5c9d6b748..fc49a4c45 100644 --- a/documents/adr/007-signal-unsupportent-content-in-github.md +++ b/documents/adr/007-signal-unsupportent-content-in-github.md @@ -43,7 +43,7 @@ The above will be applied to the current repository as follows: * **src/utils/extensions-preview.xsl** \- **ARCHIVED** * Delete all current contents * **validations** folder \- **ARCHIVED** - * Move all current contents to archive subfolder (e.g., **src/validations/archived** ) + * Delete all current contents * Update the README to let community know this is now archived and no longer maintained * **validations/constraints** \- Plan on adding new validation constraints and associated documentation that is currently in the *feature/external-extensions* branch. * Once merged from that feature branch and a release is created, it will be available in the master branch for the community. From d545517249eb1ed8fd83ab108bfb9ef4ebdbb206 Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Tue, 3 Sep 2024 14:12:01 -0400 Subject: [PATCH 07/10] Address prior review feedback --- documents/adr/007-signal-unsupportent-content-in-github.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documents/adr/007-signal-unsupportent-content-in-github.md b/documents/adr/007-signal-unsupportent-content-in-github.md index fc49a4c45..1b6a907c1 100644 --- a/documents/adr/007-signal-unsupportent-content-in-github.md +++ b/documents/adr/007-signal-unsupportent-content-in-github.md @@ -35,8 +35,8 @@ The above will be applied to the current repository as follows: * **documents/rev5/README.md** \- mark as **OBSOLETE** and remove PDF guides * presentations folder * **presentations/data-bites** - * Update with latest Data Bites slides - * Add **presentations/oscal-implementers** + * Move to automte.fedramp.gov and update with latest Data Bites slides + * Add **presentations/oscal-implementers** folder in the automate.fedramp.gov repository * Update with latest OSCAL Implementers slides * **src/examples/README.md** \- **ARCHIVED** * Delete all current contents From f707ca0e31a26affcb0637ac6bd83fae351e8d79 Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Wed, 4 Sep 2024 11:47:38 -0400 Subject: [PATCH 08/10] Apply suggestions from code review Co-authored-by: A.J. Stein --- ...7-signal-unsupportent-content-in-github.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/documents/adr/007-signal-unsupportent-content-in-github.md b/documents/adr/007-signal-unsupportent-content-in-github.md index 1b6a907c1..4c1fc56db 100644 --- a/documents/adr/007-signal-unsupportent-content-in-github.md +++ b/documents/adr/007-signal-unsupportent-content-in-github.md @@ -8,19 +8,24 @@ Pending Community Feedback ## Context -The FedRAMP OSCAL automation team needs to cleanup the repository periodically, and establish a way to signal to the community areas of the repository that are no longer maintened (e.g., legacy proof-of-concept tools, outdated documentation / guidance, etc.). +The FedRAMP Automation Team must maintain organization of its repositories, including deprecation and migration information for data, tools, and documentation as part of its release strategy. ### Possible Solutions -Signal unsupported code / content in the repository by: -1. marking the content as **DEPRECATED** in a README -2. **OBSOLETE** in a README - - deleting **OBSOLETE** content from future releases and leaving archival copies in an archive branch for posterity -3. marking the content as **ARCHIVED** and moving to an “archived” folder +Several possible solutions for identifying deprecated and migrated data, tools, and documentation are below. + +1. Do nothing, leave all data, tools, and documentation as-is +1. Marking the content as **DEPRECATED** in the relevant READMEs +1. Leverage [the current release strategy and semantic versioning](https://github.com/GSA/automate.fedramp.gov/blob/f085168bc485cf764a37c148d3a3109507d4695a/content/about/release.md): + - identify deprecation of relevant data, tools, and documentation in README with an **OBSOLETE** label in the relevant READMEs; + - make a minor release with deprecation information in those READMEs; + - make a major release with deprecated content deleted and new data, tools, and documentation released +1. Mark deprecated content by labelling relevant READMEs as **ARCHIVED** and move all relevant content to “archive” folder ## Consequences -The above will be applied to the current repository as follows: +For the purposes of this ADR, there is an inventory for this repository of different tools, data, documentation, and their future deprecation below. + * **dist/content/rev4** * Add README \- FR has transitioned to Rev 5\. Rev 4 baselines, resources, and templates are no longer maintained but will be kept frozen for historical purposes. * Mark as **DEPRECATED** From 0a162eb4c55533bc5a0a0a1142d82a9a9d80c240 Mon Sep 17 00:00:00 2001 From: Rene Tshiteya Date: Wed, 11 Sep 2024 16:04:09 -0400 Subject: [PATCH 09/10] Update documents/adr/007-signal-unsupportent-content-in-github.md Co-authored-by: A.J. Stein --- documents/adr/007-signal-unsupportent-content-in-github.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documents/adr/007-signal-unsupportent-content-in-github.md b/documents/adr/007-signal-unsupportent-content-in-github.md index 4c1fc56db..5b30019d6 100644 --- a/documents/adr/007-signal-unsupportent-content-in-github.md +++ b/documents/adr/007-signal-unsupportent-content-in-github.md @@ -40,7 +40,7 @@ For the purposes of this ADR, there is an inventory for this repository of diffe * **documents/rev5/README.md** \- mark as **OBSOLETE** and remove PDF guides * presentations folder * **presentations/data-bites** - * Move to automte.fedramp.gov and update with latest Data Bites slides + * Move to [https://automate.fedramp.gov](https://automate.fedramp.gov) and update with latest Data Bites slides * Add **presentations/oscal-implementers** folder in the automate.fedramp.gov repository * Update with latest OSCAL Implementers slides * **src/examples/README.md** \- **ARCHIVED** From 63e4d17f3c0cbdf857b12aa2e0556a0256b2cc49 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Tue, 17 Sep 2024 00:51:53 -0400 Subject: [PATCH 10/10] [skip ci] Finalize and update ADR 7 with status, datetime stamp, and explicit decision summary --- documents/adr/007-signal-unsupportent-content-in-github.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/documents/adr/007-signal-unsupportent-content-in-github.md b/documents/adr/007-signal-unsupportent-content-in-github.md index 5b30019d6..2bc1cabc6 100644 --- a/documents/adr/007-signal-unsupportent-content-in-github.md +++ b/documents/adr/007-signal-unsupportent-content-in-github.md @@ -1,10 +1,10 @@ # 7. Signal Unsupported Contents in the Repository -Date: 2024-08-30 +Date: 2024-09-17 ## Status -Pending Community Feedback +Accepted ## Context @@ -21,6 +21,9 @@ Several possible solutions for identifying deprecated and migrated data, tools, - make a minor release with deprecation information in those READMEs; - make a major release with deprecated content deleted and new data, tools, and documentation released 1. Mark deprecated content by labelling relevant READMEs as **ARCHIVED** and move all relevant content to “archive” folder + ## Decision + + The FedRAMP Automation Team will implement Solution 3: identify tools, data, and content for migration, deprecation, remove content accordingly by saving them in an archival minor release and deleting them in a major version release. ## Consequences