You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
title: Introducing Our Component Deprecation Process
3
+
slug: deprecation-process
4
+
authors: [osterman]
5
+
tags: [community, maintenance, github]
6
+
date: 2025-10-15
7
+
---
8
+
9
+
importIntrofrom'@site/src/components/Intro';
10
+
11
+
<Intro>
12
+
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.
13
+
</Intro>
14
+
15
+
Hello SweetOps!
16
+
17
+
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.
18
+
19
+
## What to Expect
20
+
21
+
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.
22
+
23
+
When we deprecate a repository, here's what you can expect:
24
+
25
+
1.**GitHub Issue Created**: A pinned issue with detailed explanation, timeline, and migration guidance
26
+
2.**README Warnings Added**: Prominent deprecation notices at the top of documentation
27
+
3.**Blog Post Published**: Announcement in our changelog/blog about the deprecation
28
+
4.**Pull Request Submitted**: All changes announced via PR for community visibility
29
+
5.**Grace Period**: Typically 90+ days for the community to migrate and ask questions
30
+
6.**Repository Archived**: After the grace period, repos are archived (not deleted) and remain publicly accessible
31
+
7.**Blog Post Updated**: Announcement updated to reflect the archival completion
32
+
33
+
## Why This Matters
34
+
35
+
This structured approach ensures that:
36
+
- You have advance notice before any repository is archived
37
+
- Migration paths and alternatives are clearly documented
38
+
- Historical access to code is preserved
39
+
- The community can provide feedback during the deprecation period
40
+
41
+
## Our Commitment
42
+
43
+
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.
44
+
45
+
:::tip Questions?
46
+
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).
Copy file name to clipboardExpand all lines: docs/community/contribute/our-github.mdx
+100Lines changed: 100 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -42,6 +42,106 @@ In general, PRs are welcome. We follow the typical "fork-and-pull" Git workflow.
42
42
43
43
Cloud Posse actively maintains all projects on [our GitHub](https://github.com/cloudposse/).
44
44
45
+
## Deprecation and Archival Process
46
+
47
+
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.
48
+
49
+
This process applies to all Cloud Posse repositories, including:
50
+
- Terraform modules in the [cloudposse](https://github.com/cloudposse/) organization
51
+
- Terraform components in the [cloudposse-terraform-components](https://github.com/cloudposse-terraform-components) organization
52
+
- GitHub Actions and other tooling
53
+
54
+
### Step 1: Create and Pin a GitHub Issue
55
+
56
+
Create a comprehensive GitHub issue that includes:
57
+
- Detailed explanation of the deprecation
58
+
- Timeline and key dates
59
+
- Migration path or alternatives
60
+
- Answers to common questions
61
+
- Contact information for support
62
+
63
+
Pin this issue to the repository so it appears at the top of the Issues tab.
64
+
65
+
### Step 2: Add Deprecation Notice to README
66
+
67
+
Add a deprecation warning at the top of the `README.md` using a GitHub-style warning admonition:
68
+
69
+
```markdown
70
+
> [!WARNING]
71
+
> **Deprecated**: This repository is deprecated and will be archived on [DATE].
72
+
> Please see [Issue #XXX](link-to-pinned-issue) for more information.
73
+
```
74
+
75
+
### Step 3: Update README.yaml
76
+
77
+
If the project uses `README.yaml` for generating documentation, add the `deprecated` field:
78
+
79
+
```yaml
80
+
deprecated:
81
+
notice: |-
82
+
This module is deprecated and will be archived on [DATE].
83
+
Please see the [pinned issue](link-to-pinned-issue) for details and migration guidance.
84
+
85
+
Consider using [alternative-module](link) as a replacement.
86
+
```
87
+
88
+
After updating `README.yaml`, regenerate the `README.md`:
89
+
90
+
```bash
91
+
atmos docs generate readme
92
+
```
93
+
94
+
### Step 4: Publish Blog Post Announcement
95
+
96
+
Create a blog post announcing the deprecation. This post should:
97
+
- Link to the pinned GitHub issue
98
+
- Explain the reason for deprecation
99
+
- Provide the timeline and deprecation date
100
+
- Offer migration guidance or alternatives
101
+
- Direct readers where to ask questions
102
+
103
+
This ensures the broader community is aware of the deprecation, even if they're not actively monitoring the repository.
104
+
105
+
### Step 5: Submit Pull Request
106
+
107
+
Create a pull request with the changes from Steps 2-3. This PR provides visibility to those monitoring repository activity. The PR should:
108
+
- Clearly state the reason for deprecation
109
+
- Specify the planned deprecation date
110
+
- Provide migration guidance or alternative solutions (if applicable)
111
+
- Reference the GitHub issue created in Step 1
112
+
- Tag relevant stakeholders for visibility
113
+
114
+
### Step 6: Wait Until Deprecation Date
115
+
116
+
Allow sufficient time (typically 90+ days) for the community to:
117
+
- Migrate away from the deprecated component
118
+
- Ask questions and get support
119
+
- Complete any in-flight work
120
+
121
+
### Step 7: Archive the Repository
122
+
123
+
Once the deprecation date has passed:
124
+
125
+
1. Update the `.github/settings.yml` file in the repository:
126
+
127
+
```yaml
128
+
repository:
129
+
archived: true
130
+
```
131
+
132
+
2. Commit and merge this change
133
+
134
+
3. The repository will be automatically archived by GitHub settings automation
135
+
136
+
Once archived, the repository becomes read-only but remains publicly accessible for historical reference.
137
+
138
+
### Step 8: Update Blog Post
139
+
140
+
Update the blog post from Step 4 to reflect that the repository has been archived:
141
+
- Add a note that the deprecation period has ended
142
+
- Confirm the repository is now archived
143
+
- Remind readers that the code remains publicly accessible for historical reference
144
+
45
145
## GitHub Projects
46
146
47
147
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.
0 commit comments