Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 0ce1e7a

Browse files
ParkreinerParkreiner
authored
chore: add CONTRIBUTING.md file (coder#13)
## Changes made - Added `CONTRIBUTING.md` file (mostly copied over from modules repo, with some parts reworded, and some sections added) ## Notes - This definitely isn't the final version of the file (it should definitely change we have more Bash stuff added), but it felt like it's in a good enough spot for an initial release
1 parent 9404ad9 commit 0ce1e7a

File tree

1 file changed

+200
-0
lines changed

1 file changed

+200
-0
lines changed

‎CONTRIBUTING.md

+200
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# Contributing
2+
3+
## Getting started
4+
5+
This repo uses two main runtimes to verify the correctness of a module/template before it is published:
6+
7+
- [Bun](https://bun.sh/) – Used to run tests for each module/template to validate overall functionality and correctness of Terraform output
8+
- [Go](https://go.dev/) – Used to validate all README files in the directory
9+
10+
### Installing Bun
11+
12+
To install Bun, you can run this command on Linux/MacOS:
13+
14+
```shell
15+
curl -fsSL https://bun.sh/install | bash
16+
```
17+
18+
Or this command on Windows:
19+
20+
```shell
21+
powershell -c "irm bun.sh/install.ps1 | iex"
22+
```
23+
24+
Follow the instructions to ensure that Bun is available globally. Once Bun is installed, install all necessary dependencies from the root of the repo:
25+
26+
Via NPM:
27+
28+
```shell
29+
npm i
30+
```
31+
32+
Via PNPM:
33+
34+
```shell
35+
pnpm i
36+
```
37+
38+
This repo does not support Yarn.
39+
40+
### Installing Go (optional)
41+
42+
This step can be skipped if you are not working on any of the README validation logic. The validation will still run as part of CI.
43+
44+
[Navigate to the official Go Installation page](https://go.dev/doc/install), and install the correct version for your operating system.
45+
46+
Once Go has been installed, verify the installation via:
47+
48+
```shell
49+
go version
50+
```
51+
52+
### Adding a new module/template (coming soon)
53+
54+
Once Bun (and possibly Go) have been installed, clone this repository. From there, you can run this script to make it easier to start contributing a new module or template:
55+
56+
```shell
57+
./new.sh NAME_OF_NEW_MODULE
58+
```
59+
60+
You can also create the correct module/template files manually.
61+
62+
## Testing a Module
63+
64+
> [!IMPORTANT]
65+
> It is the responsibility of the module author to implement tests for every new module they wish to contribute. It falls to the author to test the module locally before submitting a PR.
66+
67+
All general-purpose test helpers for validating Terraform can be found in the top-level `/testing` directory. The helpers run `terraform apply` on modules that use variables, testing the script output against containers.
68+
69+
> [!NOTE]
70+
> The testing suite must be able to run docker containers with the `--network=host` flag. This typically requires running the tests on Linux as this flag does not apply to Docker Desktop for MacOS and Windows. MacOS users can work around this by using something like [colima](https://github.com/abiosoft/colima) or [Orbstack](https://orbstack.dev/) instead of Docker Desktop.
71+
72+
You can reference the existing `*.test.ts` files to get an idea for how to set up tests.
73+
74+
You can run all tests by running this command:
75+
76+
```shell
77+
bun test
78+
```
79+
80+
Note that tests can take some time to run, so you probably don't want to be running this as part of your development loop.
81+
82+
To run specific tests, you can use the `-t` flag, which accepts a filepath regex:
83+
84+
```shell
85+
bun test -t '<regex_pattern>'
86+
```
87+
88+
To ensure that the module runs predictably in local development, you can update the Terraform source as follows:
89+
90+
```tf
91+
module "example" {
92+
# You may need to remove the 'version' field, it is incompatible with some sources.
93+
source = "git::https://github.com/<USERNAME>/<REPO>.git//<MODULE-NAME>?ref=<BRANCH-NAME>"
94+
}
95+
```
96+
97+
## Adding/modifying README files
98+
99+
This repo uses Go to do a quick validation of each README. If you are working with the README files at all, it is strongly recommended that you install Go, so that the files can be validated locally.
100+
101+
### Validating all README files
102+
103+
To validate all README files throughout the entire repo, you can run the following:
104+
105+
```shell
106+
go build ./cmd/readmevalidation && ./readmevalidation
107+
```
108+
109+
The resulting binary is already part of the `.gitignore` file, but you can quickly remove it with:
110+
111+
```shell
112+
rm ./readmevalidation
113+
```
114+
115+
### README validation criteria
116+
117+
The following criteria exists for one of two reasons: (1) content accessibility, or (2) having content be designed in a way that's easy for the Registry site build step to use:
118+
119+
#### General README requirements
120+
121+
- There must be a frontmatter section.
122+
- There must be exactly one h1 header, and it must be at the very top
123+
- 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.
124+
- When increasing the level of a header, the header's level must be incremented by one each time.
125+
- Additional image/video assets can be placed in one of two places:
126+
- In the same user namespace directory where that user's main content lives
127+
- In the top-level `.icons` directory
128+
- Any `.hcl` code snippets must be labeled as `.tf` snippets instead
129+
130+
```txt
131+
\`\`\`tf
132+
Content
133+
\`\`\`
134+
```
135+
136+
#### Contributor profiles
137+
138+
- The README body is allowed to be empty, but if it isn't, it must follow all the rules above.
139+
- The frontmatter supports the following fields:
140+
- `display_name` (required string) – The name to use when displaying your user profile in the Coder Registry site
141+
- `bio` (optional string) – A short description of who you are
142+
- `github` (required string) – Your GitHub handle
143+
- `avatar_url` (optional string) – A relative/absolute URL pointing to your avatar
144+
- `linkedin` (optional string) – A URL pointing to your LinkedIn page
145+
- `support_email` (optional string) – An email for users to reach you at if they need help with a published module/template
146+
- `employer_github` (optional string) – The name of another user namespace whom you'd like to have associated with your account. The namespace must also exist in the repo, or else the README validation will fail.
147+
- `status` (optional string union) – If defined, must be one of "community", "partner", or "official". "Community" is treated as the default value if not specified, and should be used for the majority of external contributions. "Official" should be used for Coder and Coder satellite companies. "Partner" is for companies who have a formal business agreement with Coder.
148+
149+
#### Modules and templates
150+
151+
- The frontmatter supports the following fields:
152+
- `description` (required string) A short description of what the module/template does.
153+
- `icon` (required string) – A URL pointing to the icon to use for the module/template when viewing it on the Registry website.
154+
- `display_name` (optional string) – A name to display instead of the name intuited from the module's/template's directory name
155+
- `verified` (optional boolean) – A boolean indicated that the Coder team has officially tested and vouched for the functionality/reliability of a given module or template. This field should only be changed by Coder employees.
156+
- `tags` (optional string array) – A list of tags to associate with the module/template. Users will be able to search for these tags from the Registry website.
157+
158+
## Releases
159+
160+
The release process is automated with these steps:
161+
162+
### 1. Create and merge a new PR
163+
164+
- Create a PR with your module changes
165+
- Get your PR reviewed, approved, and merged into the `main` branch
166+
167+
### 2. Prepare Release (Maintainer Task)
168+
169+
After merging to `main`, a maintainer will:
170+
171+
- View all modules and their current versions:
172+
173+
```shell
174+
./release.sh --list
175+
```
176+
177+
- Determine the next version number based on changes:
178+
179+
- **Patch version** (1.2.3 → 1.2.4): Bug fixes
180+
- **Minor version** (1.2.3 → 1.3.0): New features, adding inputs, deprecating inputs
181+
- **Major version** (1.2.3 → 2.0.0): Breaking changes (removing inputs, changing input types)
182+
183+
- Create and push an annotated tag:
184+
185+
```shell
186+
# Fetch latest changes
187+
git fetch origin
188+
189+
# Create and push tag
190+
./release.sh module-name 1.2.3 --push
191+
```
192+
193+
The tag format will be: `release/module-name/v1.2.3`
194+
195+
### 3. Publishing to Coder Registry
196+
197+
Our automated processes will handle publishing new data to [registry.coder.com](https://registry.coder.com).
198+
199+
> [!NOTE]
200+
> Some data in registry.coder.com is fetched on demand from the [coder/modules](https://github.com/coder/modules) repo's `main` branch. This data should update almost immediately after a release, while other changes will take some time to propagate.

0 commit comments

Comments
 (0)