From 3f30a8e14046d8e5d47fcad977dbc374d750e6fc Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Wed, 15 Oct 2025 12:34:26 -0500 Subject: [PATCH 1/3] Add component deprecation and archival process documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This commit adds comprehensive documentation for the process of deprecating and archiving Cloud Posse components. The documentation includes a step-by-step guide covering: - Announcing deprecations via pull requests - Adding warning admonitions to READMEs - Updating README.yaml with deprecated field - Creating and pinning GitHub issues - Grace period for community migration - Repository archival process Also includes a blog post announcing the new documentation to the community. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- blog/2025-10-15-deprecation-process.mdx | 45 +++++++++++++ docs/community/contribute/our-github.mdx | 80 ++++++++++++++++++++++++ 2 files changed, 125 insertions(+) create mode 100644 blog/2025-10-15-deprecation-process.mdx diff --git a/blog/2025-10-15-deprecation-process.mdx b/blog/2025-10-15-deprecation-process.mdx new file mode 100644 index 000000000..ee637c677 --- /dev/null +++ b/blog/2025-10-15-deprecation-process.mdx @@ -0,0 +1,45 @@ +--- +title: Introducing Our Component Deprecation Process +slug: deprecation-process +authors: [osterman] +tags: [community, maintenance, github] +date: 2025-10-15 +--- + +import Intro from '@site/src/components/Intro'; + + +We've documented our formal process for deprecating and archiving components to ensure transparency and give our community adequate notice when repositories are being sunset. + + +Hello SweetOps! + +As part of our commitment to maintaining [300+ open source projects](https://github.com/cloudposse/), we occasionally need to deprecate repositories that are no longer actively maintained or have been superseded by better alternatives. + +## New Documentation + +We've added comprehensive documentation outlining our [Deprecation and Archival Process](/community/contribute/our-github#deprecation-and-archival-process) to ensure this transition is as smooth as possible for everyone in our community. + +The process includes: + +- **Transparent Communication**: We announce deprecations via pull requests with clear timelines +- **Prominent Warnings**: Deprecation notices are added to READMEs using GitHub's warning admonitions +- **Pinned Issues**: Each deprecation gets a dedicated GitHub issue with migration guidance +- **Grace Period**: Typically 90+ days to allow for migration and questions +- **Archival**: Repositories are archived (not deleted) and remain publicly accessible + +## Why This Matters + +This structured approach ensures that: +- You have advance notice before any repository is archived +- Migration paths and alternatives are clearly documented +- Historical access to code is preserved +- The community can provide feedback during the deprecation period + +## Our Commitment + +As stated in our [GitHub documentation](/community/contribute/our-github), we commit to always provide free and public access to our Open Source repositories. Even when archived, repositories remain accessible for historical reference and continued use. + +:::tip Questions? +If you have questions about deprecated components or need migration assistance, reach out in the [SweetOps Slack](https://cloudposse.com/slack) or [GitHub Discussions](https://github.com/orgs/cloudposse/discussions). +::: diff --git a/docs/community/contribute/our-github.mdx b/docs/community/contribute/our-github.mdx index 927073695..63322f19d 100644 --- a/docs/community/contribute/our-github.mdx +++ b/docs/community/contribute/our-github.mdx @@ -42,6 +42,86 @@ In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow. Cloud Posse actively maintains all projects on [our GitHub](https://github.com/cloudposse/). +## Deprecation and Archival Process + +From time to time, we may need to deprecate and archive repositories that are no longer actively maintained. We follow a structured process to ensure transparency and give the community adequate notice. + +### Step 1: Announce Deprecation via Pull Request + +Create a pull request to communicate the planned deprecation. This PR should: +- Clearly state the reason for deprecation +- Specify the planned deprecation date +- Provide migration guidance or alternative solutions (if applicable) +- Tag relevant stakeholders for visibility + +### Step 2: Add Deprecation Notice to README + +Add a deprecation warning at the top of the `README.md` using a GitHub-style warning admonition: + +```markdown +> [!WARNING] +> **Deprecated**: This repository is deprecated and will be archived on [DATE]. +> Please see [Issue #XXX](link-to-pinned-issue) for more information. +``` + +### Step 3: Update README.yaml + +If the project uses `README.yaml` for generating documentation, add the `deprecated` field: + +```yaml +deprecated: + notice: |- + This module is deprecated and will be archived on [DATE]. + Please see the [pinned issue](link-to-pinned-issue) for details and migration guidance. + + Consider using [alternative-module](link) as a replacement. +``` + +After updating `README.yaml`, regenerate the `README.md`: + +```bash +atmos docs generate readme +``` + +### Step 4: Create and Pin a GitHub Issue + +Create a comprehensive GitHub issue that includes: +- Detailed explanation of the deprecation +- Timeline and key dates +- Migration path or alternatives +- Answers to common questions +- Contact information for support + +Pin this issue to the repository so it appears at the top of the Issues tab. + +### Step 5: Link the Issue in the Deprecation Notice + +Update the deprecation notice in the README to link to the pinned issue created in Step 4. + +### Step 6: Wait Until Deprecation Date + +Allow sufficient time (typically 90+ days) for the community to: +- Migrate away from the deprecated component +- Ask questions and get support +- Complete any in-flight work + +### Step 7: Archive the Repository + +Once the deprecation date has passed: + +1. Update the `.github/settings.yml` file in the repository: + +```yaml +repository: + archived: true +``` + +2. Commit and merge this change + +3. The repository will be automatically archived by GitHub settings automation + +Once archived, the repository becomes read-only but remains publicly accessible for historical reference. + ## GitHub Projects There's a lot going on in our GitHub. With over [200+ Open Source repositories](https://github.com/cloudposse/), keeping track of all the [Open Issues](https://github.com/search?q=org%3Acloudposse+type%3Aissues+is%3Aopen), Feature Requests, and Pull Requests is a fulltime job. From 057789d9e7cd0ccdfa5a1880a005e7fc9a7a9f39 Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Wed, 15 Oct 2025 12:36:43 -0500 Subject: [PATCH 2/3] Clarify process applies to modules and components MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added explicit mention of cloudposse-terraform-components organization - Clarified that the process applies to modules, components, and other tooling - Updated both documentation and blog post for consistency 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- blog/2025-10-15-deprecation-process.mdx | 2 +- docs/community/contribute/our-github.mdx | 5 +++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/blog/2025-10-15-deprecation-process.mdx b/blog/2025-10-15-deprecation-process.mdx index ee637c677..8d504677d 100644 --- a/blog/2025-10-15-deprecation-process.mdx +++ b/blog/2025-10-15-deprecation-process.mdx @@ -14,7 +14,7 @@ We've documented our formal process for deprecating and archiving components to Hello SweetOps! -As part of our commitment to maintaining [300+ open source projects](https://github.com/cloudposse/), we occasionally need to deprecate repositories that are no longer actively maintained or have been superseded by better alternatives. +As part of our commitment to maintaining [300+ open source projects](https://github.com/cloudposse/) across Terraform modules, [components](https://github.com/cloudposse-terraform-components), and other tooling, we occasionally need to deprecate repositories that are no longer actively maintained or have been superseded by better alternatives. ## New Documentation diff --git a/docs/community/contribute/our-github.mdx b/docs/community/contribute/our-github.mdx index 63322f19d..767285b23 100644 --- a/docs/community/contribute/our-github.mdx +++ b/docs/community/contribute/our-github.mdx @@ -46,6 +46,11 @@ Cloud Posse actively maintains all projects on [our GitHub](https://github.com/c From time to time, we may need to deprecate and archive repositories that are no longer actively maintained. We follow a structured process to ensure transparency and give the community adequate notice. +This process applies to all Cloud Posse repositories, including: +- Terraform modules in the [cloudposse](https://github.com/cloudposse/) organization +- Terraform components in the [cloudposse-terraform-components](https://github.com/cloudposse-terraform-components) organization +- GitHub Actions and other tooling + ### Step 1: Announce Deprecation via Pull Request Create a pull request to communicate the planned deprecation. This PR should: From 4b66facf59c5124ffdf62e07408c20f5f1ecc02f Mon Sep 17 00:00:00 2001 From: Erik Osterman Date: Thu, 16 Oct 2025 14:52:13 -0500 Subject: [PATCH 3/3] Changes auto-committed by Conductor --- blog/2025-10-15-deprecation-process.mdx | 16 ++++---- docs/community/contribute/our-github.mdx | 47 ++++++++++++++++-------- 2 files changed, 40 insertions(+), 23 deletions(-) diff --git a/blog/2025-10-15-deprecation-process.mdx b/blog/2025-10-15-deprecation-process.mdx index 8d504677d..3b8f7702a 100644 --- a/blog/2025-10-15-deprecation-process.mdx +++ b/blog/2025-10-15-deprecation-process.mdx @@ -16,17 +16,19 @@ Hello SweetOps! As part of our commitment to maintaining [300+ open source projects](https://github.com/cloudposse/) across Terraform modules, [components](https://github.com/cloudposse-terraform-components), and other tooling, we occasionally need to deprecate repositories that are no longer actively maintained or have been superseded by better alternatives. -## New Documentation +## What to Expect We've added comprehensive documentation outlining our [Deprecation and Archival Process](/community/contribute/our-github#deprecation-and-archival-process) to ensure this transition is as smooth as possible for everyone in our community. -The process includes: +When we deprecate a repository, here's what you can expect: -- **Transparent Communication**: We announce deprecations via pull requests with clear timelines -- **Prominent Warnings**: Deprecation notices are added to READMEs using GitHub's warning admonitions -- **Pinned Issues**: Each deprecation gets a dedicated GitHub issue with migration guidance -- **Grace Period**: Typically 90+ days to allow for migration and questions -- **Archival**: Repositories are archived (not deleted) and remain publicly accessible +1. **GitHub Issue Created**: A pinned issue with detailed explanation, timeline, and migration guidance +2. **README Warnings Added**: Prominent deprecation notices at the top of documentation +3. **Blog Post Published**: Announcement in our changelog/blog about the deprecation +4. **Pull Request Submitted**: All changes announced via PR for community visibility +5. **Grace Period**: Typically 90+ days for the community to migrate and ask questions +6. **Repository Archived**: After the grace period, repos are archived (not deleted) and remain publicly accessible +7. **Blog Post Updated**: Announcement updated to reflect the archival completion ## Why This Matters diff --git a/docs/community/contribute/our-github.mdx b/docs/community/contribute/our-github.mdx index 767285b23..cf5456f2b 100644 --- a/docs/community/contribute/our-github.mdx +++ b/docs/community/contribute/our-github.mdx @@ -51,13 +51,16 @@ This process applies to all Cloud Posse repositories, including: - Terraform components in the [cloudposse-terraform-components](https://github.com/cloudposse-terraform-components) organization - GitHub Actions and other tooling -### Step 1: Announce Deprecation via Pull Request +### Step 1: Create and Pin a GitHub Issue -Create a pull request to communicate the planned deprecation. This PR should: -- Clearly state the reason for deprecation -- Specify the planned deprecation date -- Provide migration guidance or alternative solutions (if applicable) -- Tag relevant stakeholders for visibility +Create a comprehensive GitHub issue that includes: +- Detailed explanation of the deprecation +- Timeline and key dates +- Migration path or alternatives +- Answers to common questions +- Contact information for support + +Pin this issue to the repository so it appears at the top of the Issues tab. ### Step 2: Add Deprecation Notice to README @@ -88,20 +91,25 @@ After updating `README.yaml`, regenerate the `README.md`: atmos docs generate readme ``` -### Step 4: Create and Pin a GitHub Issue +### Step 4: Publish Blog Post Announcement -Create a comprehensive GitHub issue that includes: -- Detailed explanation of the deprecation -- Timeline and key dates -- Migration path or alternatives -- Answers to common questions -- Contact information for support +Create a blog post announcing the deprecation. This post should: +- Link to the pinned GitHub issue +- Explain the reason for deprecation +- Provide the timeline and deprecation date +- Offer migration guidance or alternatives +- Direct readers where to ask questions -Pin this issue to the repository so it appears at the top of the Issues tab. +This ensures the broader community is aware of the deprecation, even if they're not actively monitoring the repository. -### Step 5: Link the Issue in the Deprecation Notice +### Step 5: Submit Pull Request -Update the deprecation notice in the README to link to the pinned issue created in Step 4. +Create a pull request with the changes from Steps 2-3. This PR provides visibility to those monitoring repository activity. The PR should: +- Clearly state the reason for deprecation +- Specify the planned deprecation date +- Provide migration guidance or alternative solutions (if applicable) +- Reference the GitHub issue created in Step 1 +- Tag relevant stakeholders for visibility ### Step 6: Wait Until Deprecation Date @@ -127,6 +135,13 @@ repository: Once archived, the repository becomes read-only but remains publicly accessible for historical reference. +### Step 8: Update Blog Post + +Update the blog post from Step 4 to reflect that the repository has been archived: +- Add a note that the deprecation period has ended +- Confirm the repository is now archived +- Remind readers that the code remains publicly accessible for historical reference + ## GitHub Projects There's a lot going on in our GitHub. With over [200+ Open Source repositories](https://github.com/cloudposse/), keeping track of all the [Open Issues](https://github.com/search?q=org%3Acloudposse+type%3Aissues+is%3Aopen), Feature Requests, and Pull Requests is a fulltime job.