Skip to content

Commit ad7033c

Browse files
DevelopmentCatsDevelopmentCats
committed
docs(MAINTAINER): add maintainer guide for repository management and processes
1 parent 11baccd commit ad7033c

File tree

1 file changed

+292
-0
lines changed

1 file changed

+292
-0
lines changed

‎MAINTAINER.md‎

Lines changed: 292 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,292 @@
1+
# Maintainer Guide
2+
3+
This guide is for maintainers of the Coder Registry repository. It covers processes and tools that are specific to maintaining the repository, validating contributions, and managing releases.
4+
5+
## Prerequisites
6+
7+
### Required Tools
8+
9+
- **Go** - For README validation
10+
- **Bun** - For running tests
11+
- **Git** - For repository management
12+
13+
### Installing Go
14+
15+
[Navigate to the official Go Installation page](https://go.dev/doc/install), and install the correct version for your operating system.
16+
17+
Once Go has been installed, verify the installation via:
18+
19+
```shell
20+
go version
21+
```
22+
23+
## README Validation
24+
25+
The repository uses Go to validate all README files to ensure they meet the requirements for the Registry website.
26+
27+
### Running README Validation
28+
29+
To validate all README files throughout the entire repo:
30+
31+
```shell
32+
go build ./cmd/readmevalidation && ./readmevalidation
33+
```
34+
35+
The resulting binary is already part of the `.gitignore` file, but you can remove it with:
36+
37+
```shell
38+
rm ./readmevalidation
39+
```
40+
41+
### README Validation Criteria
42+
43+
The validation exists for two reasons:
44+
45+
1. Content accessibility
46+
2. Having content designed in a way that's easy for the Registry site build step to use
47+
48+
#### General README Requirements
49+
50+
- There must be a frontmatter section
51+
- There must be exactly one h1 header, and it must be at the very top, directly below the frontmatter
52+
- The README body (if it exists) must start with an h1 header. No other content (including GitHub-Flavored Markdown alerts) is allowed to be placed above it
53+
- When increasing the level of a header, the header's level must be incremented by one each time
54+
- Any `.hcl` code snippets must be labeled as `.tf` snippets instead
55+
56+
```txt
57+
\`\`\`tf
58+
Content
59+
\`\`\`
60+
```
61+
62+
#### Namespace (Contributor Profile) Criteria
63+
64+
In addition to the general criteria, all namespace README files must have:
65+
66+
- Frontmatter metadata with support for the following fields:
67+
- `display_name` (required string) – The name to use when displaying the user profile in the Coder Registry site
68+
- `bio` (optional string) – A short description of who they are
69+
- `github` (optional string) – Their GitHub handle
70+
- `avatar_url` (optional string) – A relative/absolute URL pointing to their avatar for the Registry site
71+
- `linkedin` (optional string) – A URL pointing to their LinkedIn page
72+
- `support_email` (optional string) – An email for users to reach them at if they need help with a published module
73+
- `status` (string union) – If defined, this must be one of `"community"`, `"partner"`, or `"official"`. `"community"` should be used for the majority of external contributions. `"partner"` is for companies who have a formal business partnership with Coder. `"official"` should be used only by Coder employees
74+
75+
- The README body (the content that goes directly below the frontmatter) is allowed to be empty, but if it isn't, it must follow all the rules above
76+
77+
#### Module Criteria
78+
79+
In addition to the general criteria, all module README files must have:
80+
81+
- Frontmatter that describes metadata for the module:
82+
- `display_name` (required string) – This is the name displayed on the Coder Registry website
83+
- `description` (required string) – A short description of the module, which is displayed on the Registry website
84+
- `icon` (required string) – A relative/absolute URL pointing to the icon to display for the module in the Coder Registry website
85+
- `verified` (optional boolean) – Indicates whether the module has been officially verified by Coder. Please do not set this without approval from a Coder employee
86+
- `tags` (required string array) – A list of metadata tags to describe the module. Used in the Registry site for search and navigation functionality
87+
- `maintainer_github` (deprecated string) – The name of the creator of the module. This field exists for backwards compatibility with previous versions of the Registry, but going forward, the value will be inferred from the namespace directory
88+
- `partner_github` (deprecated string) - The name of any additional creators for a module. This field exists for backwards compatibility with previous versions of the Registry, but should not ever be used going forward
89+
90+
- The following content directly under the h1 header (without another header between them):
91+
- A description of what the module does
92+
- A Terraform snippet for letting other users import the functionality
93+
94+
```tf
95+
module "cursor" {
96+
count = data.coder_workspace.me.start_count
97+
source = "registry.coder.com/coder/cursor/coder"
98+
version = "1.0.19"
99+
agent_id = coder_agent.example.id
100+
}
101+
```
102+
103+
## Release Process
104+
105+
The release process involves the following steps:
106+
107+
### 1. Review and Merge PRs
108+
109+
- Review contributor PRs for code quality, tests, and documentation
110+
- Ensure all automated tests pass
111+
- Verify README validation passes
112+
- Merge approved PRs into the `main` branch
113+
114+
### 2. Prepare Release
115+
116+
After merging to `main`, prepare the release:
117+
118+
- Check out the merge commit:
119+
120+
```shell
121+
git checkout MERGE_COMMIT_ID
122+
```
123+
124+
- Create annotated tags for each module that was changed:
125+
126+
```shell
127+
git tag -a "release/$namespace/$module/v$version" -m "Release $namespace/$module v$version"
128+
```
129+
130+
- Push the tags to origin:
131+
132+
```shell
133+
git push origin release/$namespace/$module/v$version
134+
```
135+
136+
For example, to release version 1.0.14 of the coder/aider module:
137+
138+
```shell
139+
git tag -a "release/coder/aider/v1.0.14" -m "Release coder/aider v1.0.14"
140+
git push origin release/coder/aider/v1.0.14
141+
```
142+
143+
### Version Numbers
144+
145+
Version numbers should follow semantic versioning:
146+
147+
- **Patch version** (1.2.3 → 1.2.4): Bug fixes
148+
- **Minor version** (1.2.3 → 1.3.0): New features, adding inputs, deprecating inputs
149+
- **Major version** (1.2.3 → 2.0.0): Breaking changes (removing inputs, changing input types)
150+
151+
### 3. Publishing to Coder Registry
152+
153+
After tags are pushed, the changes will be published to [registry.coder.com](https://registry.coder.com).
154+
155+
> [!NOTE]
156+
> Some data in registry.coder.com is fetched on demand from this repository's `main` branch. This data should update almost immediately after a release, while other changes will take some time to propagate.
157+
158+
## Testing Infrastructure
159+
160+
### Running All Tests
161+
162+
From the repository root:
163+
164+
```shell
165+
bun test
166+
```
167+
168+
### Running Specific Tests
169+
170+
To run tests for specific modules or patterns:
171+
172+
```shell
173+
bun test -t '<regex_pattern>'
174+
```
175+
176+
### Test Requirements
177+
178+
- All modules must have a `main.test.ts` file
179+
- Tests must use the test utilities from `~test` import
180+
- Tests must validate required variables and successful Terraform apply
181+
- The testing suite requires Docker with `--network=host` capabilities
182+
183+
## Repository Structure Management
184+
185+
### Namespaces
186+
187+
- All modules must be placed within a namespace under `/registry/[namespace]/modules/`
188+
- Each namespace should have a README.md file with contributor profile information
189+
- Namespace names must be unique and lowercase
190+
191+
### Images and Assets
192+
193+
Images can be placed in two locations:
194+
195+
1. In the namespace directory: `/registry/[namespace]/images/`
196+
2. For icons used by multiple modules: `/.icons/`
197+
198+
### Module Structure
199+
200+
Each module must contain:
201+
202+
- `main.tf` - Core Terraform functionality
203+
- `main.test.ts` - Test file for validation
204+
- `README.md` - Documentation with required frontmatter
205+
206+
## Validation Checklist for PRs
207+
208+
When reviewing PRs, ensure:
209+
210+
- [ ] Module follows proper directory structure
211+
- [ ] All required files are present (`main.tf`, `main.test.ts`, `README.md`)
212+
- [ ] README has proper frontmatter with all required fields
213+
- [ ] Tests are implemented and pass
214+
- [ ] Code is properly formatted (`bun run fmt`)
215+
- [ ] README validation passes
216+
- [ ] Module follows Terraform best practices
217+
- [ ] No hardcoded values that should be variables
218+
- [ ] Proper variable descriptions and types
219+
220+
## Common Issues and Solutions
221+
222+
### README Validation Failures
223+
224+
- Check frontmatter syntax (YAML format)
225+
- Ensure h1 header is directly below frontmatter
226+
- Verify all required frontmatter fields are present
227+
- Check that code blocks use `tf` instead of `hcl`
228+
229+
### Test Failures
230+
231+
- Ensure Docker is available with `--network=host` support
232+
- Check that all required variables are defined in tests
233+
- Verify Terraform syntax is valid
234+
- Ensure test imports use `~test` alias correctly
235+
236+
### Module Structure Issues
237+
238+
- Use the `./scripts/new_module.sh` script for consistent structure
239+
- Ensure namespace directory exists
240+
- Check that all file paths are correct
241+
242+
## Maintenance Tasks
243+
244+
### Regular Maintenance
245+
246+
- Monitor for security vulnerabilities in dependencies
247+
- Update test infrastructure as needed
248+
- Review and update documentation
249+
- Monitor Registry website for issues
250+
251+
### Dependency Updates
252+
253+
- Keep Bun dependencies up to date
254+
- Monitor Terraform provider updates
255+
- Update test utilities as needed
256+
257+
### Documentation Updates
258+
259+
- Keep README validation criteria current
260+
- Update examples as the platform evolves
261+
- Maintain contributor guidelines
262+
263+
## Emergency Procedures
264+
265+
### Reverting a Release
266+
267+
If a release needs to be reverted:
268+
269+
1. Delete the problematic tag:
270+
```shell
271+
git tag -d release/$namespace/$module/v$version
272+
git push origin :refs/tags/release/$namespace/$module/v$version
273+
```
274+
275+
2. Create a new patch release with the fix
276+
277+
### Handling Security Issues
278+
279+
1. Immediately remove or disable problematic modules
280+
2. Notify affected users through appropriate channels
281+
3. Work with contributors to address security concerns
282+
4. Document the issue and resolution
283+
284+
## Contact and Escalation
285+
286+
For maintainer-specific questions or issues:
287+
288+
- Internal Coder team channels
289+
- Repository issues for public discussion
290+
- Security email for sensitive issues
291+
292+
Remember: As a maintainer, you're responsible for maintaining the quality and security of the Registry. When in doubt, err on the side of caution and seek additional review.

0 commit comments

Comments
 (0)