From 78651637a8e7ec3efd67f53f5810fdbe16b811e7 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Tue, 5 Nov 2024 14:04:47 -0500 Subject: [PATCH 1/7] [skip ci] Deprecate ADR2, backport "new" #847 ADR --- .../adr/0002-git-release-version-strategy.md | 6 ++++-- documents/adr/0010-semantic-versions-only.md | 19 +++++++++++++++++++ 2 files changed, 23 insertions(+), 2 deletions(-) create mode 100644 documents/adr/0010-semantic-versions-only.md diff --git a/documents/adr/0002-git-release-version-strategy.md b/documents/adr/0002-git-release-version-strategy.md index f7c20cb57..521d389a9 100644 --- a/documents/adr/0002-git-release-version-strategy.md +++ b/documents/adr/0002-git-release-version-strategy.md @@ -1,10 +1,12 @@ # 2. Release and Version Strategy Used for Github Tagging -Date: 2021-06-03 +Date: 2021-10-07 ## Status -Accepted +Deprecated + +(**NOTE:** FedRAMP deprecated this ADR retroactively in favor of [ADR #10](./0010-semantic-versions-only.md). See ADR #10 for further details on the current version methodology as part of the FedRAMP Automation Team's release strategy.) ## Context diff --git a/documents/adr/0010-semantic-versions-only.md b/documents/adr/0010-semantic-versions-only.md new file mode 100644 index 000000000..cff5e26db --- /dev/null +++ b/documents/adr/0010-semantic-versions-only.md @@ -0,0 +1,19 @@ +# 10. Replace Spock Versions with Semantic Versions in Release Strategy + +Date: 2021-10-07 + +## Status + +Accepted + +## Context + +What is the issue that we're seeing that is motivating this decision or change? + +## Decision + +What is the change that we're proposing and/or doing? + +## Consequences + +What becomes easier or more difficult to do because of this change? From 67959d2805463cd2008c6522c5e372e4542da760 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Tue, 5 Nov 2024 16:03:50 -0500 Subject: [PATCH 2/7] [skip ci] Context and decision in #847 ADR --- documents/adr/0010-semantic-versions-only.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/documents/adr/0010-semantic-versions-only.md b/documents/adr/0010-semantic-versions-only.md index cff5e26db..646123831 100644 --- a/documents/adr/0010-semantic-versions-only.md +++ b/documents/adr/0010-semantic-versions-only.md @@ -8,11 +8,16 @@ Accepted ## Context -What is the issue that we're seeing that is motivating this decision or change? +In the past, the FedRAMP Automation Team [the versioning methodology of the Spock Framework](https://spockframework.org/spock/docs/2.0/known_issues.html#_groovy_version_compatibility). Staff documented this versioning methodology in [ADR #2](https://github.com/GSA/fedramp-automation/blob/247f99a0e3a2cfa6b9e78dd7c18836cf008115b2/documents/adr/0002-git-release-version-strategy.md). In 2024, the FedRAMP Automation Team received significant positive feedback from the community to transition from this methodology to [Semantic Versioning](https://semver.org/) as part of its release strategy and updated [the automate.fedramp.gov website](https://automate.fedramp.gov/about/release/) accordingly. They also socialized with the community that this document, not the previous ADR and outdated developer documentation, is the canonical source for the release strategy and other documents. + +This decision record is to document the following possible solutions and implications. ## Decision -What is the change that we're proposing and/or doing? +FedRAMP has decided to move forward completely with the Semantic Versioning transition and completely deprecate the Spock versioning approach. + +1. FedRAMP will use Semantic Versioning, as is the preference of the community. +2. The official, normative release guidance for FedRAMP Automation data, documentation, and tools is the [release guidance on automate.fedramp.gov](https://automate.fedramp.gov/about/release/), not developer documentation in this repository. ## Consequences From e1283d3d86775a34e9da585248a6a1787140d358 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Tue, 5 Nov 2024 17:51:09 -0500 Subject: [PATCH 3/7] [skip ci] Add two options to #847 ADR --- documents/adr/0010-semantic-versions-only.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/documents/adr/0010-semantic-versions-only.md b/documents/adr/0010-semantic-versions-only.md index 646123831..8cbb76bb5 100644 --- a/documents/adr/0010-semantic-versions-only.md +++ b/documents/adr/0010-semantic-versions-only.md @@ -12,6 +12,18 @@ In the past, the FedRAMP Automation Team [the versioning methodology of the Spoc This decision record is to document the following possible solutions and implications. +### Possible Solutions + +Below is a list of possible versioning solutions that will or will not support this strategy. + +#### Do Nothing + +If FedRAMP does nothing, the strategy and processes will stay as-is. The documentation about the release strategy and versioning methodology and the practice of using them in releases will contradict one another. Internal staff and external stakeholders will continue to receive conflicted guidance. The misalignment may cause confusion about future releases. + +#### Continue Spock Versioning and Revert Semantic Versioning Change + +FedRAMP can change the developer documentation, standard operating procedures in the wiki, and the website to continue to use Spock versioning and revert the decision to use Semantic Versioning. This option would take as much effort as the alternative to completely move to SemVer. However, this option will likely alienate community stakeholders receptive to the change. + ## Decision FedRAMP has decided to move forward completely with the Semantic Versioning transition and completely deprecate the Spock versioning approach. From 1f854385d1d75c4040d2e611b33909f13cb761c1 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Tue, 5 Nov 2024 19:50:21 -0500 Subject: [PATCH 4/7] [skip ci] Add option 3, finalize #847 ADR --- documents/adr/0010-semantic-versions-only.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/documents/adr/0010-semantic-versions-only.md b/documents/adr/0010-semantic-versions-only.md index 8cbb76bb5..4d1ba41e7 100644 --- a/documents/adr/0010-semantic-versions-only.md +++ b/documents/adr/0010-semantic-versions-only.md @@ -8,7 +8,7 @@ Accepted ## Context -In the past, the FedRAMP Automation Team [the versioning methodology of the Spock Framework](https://spockframework.org/spock/docs/2.0/known_issues.html#_groovy_version_compatibility). Staff documented this versioning methodology in [ADR #2](https://github.com/GSA/fedramp-automation/blob/247f99a0e3a2cfa6b9e78dd7c18836cf008115b2/documents/adr/0002-git-release-version-strategy.md). In 2024, the FedRAMP Automation Team received significant positive feedback from the community to transition from this methodology to [Semantic Versioning](https://semver.org/) as part of its release strategy and updated [the automate.fedramp.gov website](https://automate.fedramp.gov/about/release/) accordingly. They also socialized with the community that this document, not the previous ADR and outdated developer documentation, is the canonical source for the release strategy and other documents. +In the past, the FedRAMP Automation Team [the versioning methodology of the Spock Framework](https://spockframework.org/spock/docs/2.0/known_issues.html#_groovy_version_compatibility). Staff documented this versioning methodology in [ADR #2](https://github.com/GSA/fedramp-automation/blob/247f99a0e3a2cfa6b9e78dd7c18836cf008115b2/documents/adr/0002-git-release-version-strategy.md). In 2024, the FedRAMP Automation Team received significant positive feedback from the community to transition from this methodology to [Semantic Versioning](https://semver.org/) as part of its release strategy and updated [the automate.fedramp.gov website](https://automate.fedramp.gov/about/release/) accordingly. They also socialized with the community that the update page on the website, not the previous ADR and outdated developer documentation, is the canonical source for the release strategy and other documents. This decision record is to document the following possible solutions and implications. @@ -16,13 +16,21 @@ This decision record is to document the following possible solutions and implica Below is a list of possible versioning solutions that will or will not support this strategy. +1. Do nothing +1. Continue Spock Versioning and revert Semantic Versioning change +1. Continue Semantic Versioning change and completely deprecate Spock versioning + #### Do Nothing -If FedRAMP does nothing, the strategy and processes will stay as-is. The documentation about the release strategy and versioning methodology and the practice of using them in releases will contradict one another. Internal staff and external stakeholders will continue to receive conflicted guidance. The misalignment may cause confusion about future releases. +If FedRAMP does nothing, the strategy and processes will stay as-is. The documentation about the release strategy and versioning methodology and the practice of using them in releases will contradict one another. Internal staff and external stakeholders will continue to receive conflicted guidance and releases. The misalignment may cause confusion about future releases. Despite less effort, it has significant downsides in risk when compared to Options 2 and 3. #### Continue Spock Versioning and Revert Semantic Versioning Change -FedRAMP can change the developer documentation, standard operating procedures in the wiki, and the website to continue to use Spock versioning and revert the decision to use Semantic Versioning. This option would take as much effort as the alternative to completely move to SemVer. However, this option will likely alienate community stakeholders receptive to the change. +FedRAMP can change the developer documentation, standard operating procedures in the wiki, and the website to continue to use Spock versioning and revert the decision to use Semantic Versioning. This option would require similar effort to Option 3. However, this option will likely alienate community stakeholders receptive to the change. + +#### Continue Semantic Versioning Change and Completely Deprecate Spock Versioning + +FedRAMP can change the developer documentation, standard operating procedures in the wiki, and the website to finalize the removal of Spock versioning and fully commit to the decision to use Semantic Versioning. This option would require similar effort to Option 2 but with better community support for a popular transition that is not yet complete. ## Decision From b4d2c69c0c7babb843e4a9c6742a4ade1df34066 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Wed, 6 Nov 2024 08:35:16 -0500 Subject: [PATCH 5/7] Apply very valid feedback during review from @Rene2mt Co-authored-by: Rene Tshiteya --- documents/adr/0010-semantic-versions-only.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/documents/adr/0010-semantic-versions-only.md b/documents/adr/0010-semantic-versions-only.md index 4d1ba41e7..194184ad0 100644 --- a/documents/adr/0010-semantic-versions-only.md +++ b/documents/adr/0010-semantic-versions-only.md @@ -8,7 +8,7 @@ Accepted ## Context -In the past, the FedRAMP Automation Team [the versioning methodology of the Spock Framework](https://spockframework.org/spock/docs/2.0/known_issues.html#_groovy_version_compatibility). Staff documented this versioning methodology in [ADR #2](https://github.com/GSA/fedramp-automation/blob/247f99a0e3a2cfa6b9e78dd7c18836cf008115b2/documents/adr/0002-git-release-version-strategy.md). In 2024, the FedRAMP Automation Team received significant positive feedback from the community to transition from this methodology to [Semantic Versioning](https://semver.org/) as part of its release strategy and updated [the automate.fedramp.gov website](https://automate.fedramp.gov/about/release/) accordingly. They also socialized with the community that the update page on the website, not the previous ADR and outdated developer documentation, is the canonical source for the release strategy and other documents. +In the past, the FedRAMP Automation Team implemented [the versioning methodology of the Spock Framework](https://spockframework.org/spock/docs/2.0/known_issues.html#_groovy_version_compatibility). Staff documented this versioning methodology in [ADR #2](https://github.com/GSA/fedramp-automation/blob/247f99a0e3a2cfa6b9e78dd7c18836cf008115b2/documents/adr/0002-git-release-version-strategy.md). In 2024, the FedRAMP Automation Team received significant positive feedback from the community to transition from this methodology to [Semantic Versioning](https://semver.org/) as part of its release strategy and updated [the automate.fedramp.gov website](https://automate.fedramp.gov/about/release/) accordingly. They also socialized with the community that the update page on the website, not the previous ADR and outdated developer documentation, is the canonical source for the release strategy and other documents. This decision record is to document the following possible solutions and implications. @@ -42,3 +42,4 @@ FedRAMP has decided to move forward completely with the Semantic Versioning tran ## Consequences What becomes easier or more difficult to do because of this change? +It will be easier for developers to automate handling version updates based on SemVer rules. From 01ec0effd80790d93b27c9d0fe5a10905ff110ae Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Tue, 12 Nov 2024 17:34:58 -0500 Subject: [PATCH 6/7] [skip ci] Clarify ADR 10 explanation of past work per @Rene2mt review of #866 Co-authored-by: Rene Tshiteya From 012592f1bac5c0c4dd505d8fba2b4b69bab5a147 Mon Sep 17 00:00:00 2001 From: "A.J. Stein" Date: Tue, 12 Nov 2024 17:35:32 -0500 Subject: [PATCH 7/7] [skip ci] Add missing info to ADR 10 per @Rene2mt's #866 review Co-authored-by: Rene Tshiteya --- documents/adr/0010-semantic-versions-only.md | 1 + 1 file changed, 1 insertion(+) diff --git a/documents/adr/0010-semantic-versions-only.md b/documents/adr/0010-semantic-versions-only.md index 194184ad0..747666db3 100644 --- a/documents/adr/0010-semantic-versions-only.md +++ b/documents/adr/0010-semantic-versions-only.md @@ -43,3 +43,4 @@ FedRAMP has decided to move forward completely with the Semantic Versioning tran What becomes easier or more difficult to do because of this change? It will be easier for developers to automate handling version updates based on SemVer rules. +It will be easier for developers to automate handling version updates based on SemVer rules.