Skip to content

Commit 783b2e3

Browse files
8bitAlex8bitAlex
committed
Refactor YAML documentation for consistency; add quotes around keys and values
1 parent b68b291 commit 783b2e3

6 files changed

Lines changed: 152 additions & 131 deletions

File tree

‎docs/environments.md‎

Lines changed: 39 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -11,67 +11,70 @@ Environments let you define named configurations — sets of variables and tasks
1111
Environments are defined at the **top level of the profile**, as a list. Each environment has a `name`, optional `variables`, and optional `tasks`.
1212

1313
```yaml title="profile.yaml"
14-
name: platform
14+
name: "platform"
1515

1616
environments:
17-
- name: local
17+
- name: "local"
1818
variables:
19-
- name: LOG_LEVEL
20-
value: debug
19+
- name: "LOG_LEVEL"
20+
value: "debug"
2121
tasks:
2222
- type: Shell
23-
cmd: docker-compose up -d db
24-
- name: staging
23+
cmd: "docker-compose up -d db"
24+
- name: "staging"
2525
variables:
26-
- name: LOG_LEVEL
27-
value: info
26+
- name: "LOG_LEVEL"
27+
value: "info"
2828
tasks:
2929
- type: Print
3030
message: "Switched to staging"
31-
- name: production
31+
- name: "production"
3232
variables:
33-
- name: LOG_LEVEL
34-
value: warn
33+
- name: "LOG_LEVEL"
34+
value: "warn"
3535
tasks:
3636
- type: Confirm
3737
message: "Switch to production?"
3838

3939
repositories:
40-
- name: api
41-
url: git@github.com:my-org/api.git
42-
path: ~/dev/api
40+
- name: "api"
41+
url: "git@github.com:my-org/api.git"
42+
path: "~/dev/api"
4343
```
4444
4545
Individual repositories can also define their own environments in their `raid.yaml`. These are merged with the profile-level environments when applied.
4646

4747
```yaml title="~/dev/api/raid.yaml"
48+
name: "api"
49+
branch: "main"
50+
4851
environments:
49-
- name: local
52+
- name: "local"
5053
variables:
51-
- name: DATABASE_URL
52-
value: postgres://localhost:5432/api_dev
53-
- name: API_PORT
54+
- name: "DATABASE_URL"
55+
value: "postgres://localhost:5432/api_dev"
56+
- name: "API_PORT"
5457
value: "3000"
5558
tasks:
5659
- type: Shell
57-
cmd: docker-compose up -d db
58-
- name: staging
60+
cmd: "docker-compose up -d db"
61+
- name: "staging"
5962
variables:
60-
- name: DATABASE_URL
61-
value: postgres://staging-db.internal:5432/api
62-
- name: API_PORT
63+
- name: "DATABASE_URL"
64+
value: "postgres://staging-db.internal:5432/api"
65+
- name: "API_PORT"
6366
value: "443"
64-
- name: production
67+
- name: "production"
6568
variables:
66-
- name: DATABASE_URL
67-
value: postgres://prod-db.internal:5432/api
68-
- name: API_PORT
69+
- name: "DATABASE_URL"
70+
value: "postgres://prod-db.internal:5432/api"
71+
- name: "API_PORT"
6972
value: "443"
7073
tasks:
7174
- type: Confirm
7275
message: "Point API at production database?"
7376
- type: Shell
74-
cmd: ./scripts/rotate-api-key.sh
77+
cmd: "./scripts/rotate-api-key.sh"
7578
```
7679

7780
| Field | Description |
@@ -105,18 +108,21 @@ raid env list
105108
**Use `Prompt` and `Template` for developer-specific values.** If values differ per developer (e.g. local ports), prompt for them at apply-time.
106109

107110
```yaml title="~/dev/api/raid.yaml"
111+
name: "api"
112+
branch: "main"
113+
108114
environments:
109-
- name: local
115+
- name: "local"
110116
tasks:
111117
- type: Prompt
112-
var: DB_PORT
118+
var: "DB_PORT"
113119
message: "Local database port"
114120
default: "5432"
115121
- type: Prompt
116-
var: API_PORT
122+
var: "API_PORT"
117123
message: "Local API port"
118124
default: "3000"
119125
- type: Template
120-
src: ./envs/local.env.tmpl
121-
dest: ~/dev/api/.env
126+
src: "./envs/local.env.tmpl"
127+
dest: "~/dev/api/.env"
122128
```

‎docs/examples/custom-commands.md‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ commands:
2121
path: "./scripts/deploy.sh staging"
2222
- type: Print
2323
message: "Deployed."
24-
color: green
24+
color: "green"
2525
```
2626
2727
```bash
@@ -74,12 +74,12 @@ install:
7474
- type: Shell
7575
cmd: "brew install postgresql"
7676
condition:
77-
platform: darwin
77+
platform: "darwin"
7878
cmd: "! which psql"
7979
- type: Shell
8080
cmd: "sudo apt-get install -y postgresql"
8181
condition:
82-
platform: linux
82+
platform: "linux"
8383
cmd: "! which psql"
8484
- type: Shell
8585
cmd: "createdb api_dev"
@@ -116,7 +116,7 @@ commands:
116116
concurrent: true
117117
- type: Print
118118
message: "All tests passed"
119-
color: green
119+
color: "green"
120120
```
121121

122122
```bash
@@ -149,7 +149,7 @@ commands:
149149
usage: "Pull all repos and reinstall dependencies"
150150
tasks:
151151
- type: Group
152-
ref: pull-all
152+
ref: "pull-all"
153153
- type: Shell
154154
cmd: "npm install"
155155
path: "~/dev/frontend"
@@ -158,7 +158,7 @@ commands:
158158
usage: "Pull latest and deploy"
159159
tasks:
160160
- type: Group
161-
ref: pull-all
161+
ref: "pull-all"
162162
- type: Shell
163163
cmd: "./scripts/deploy.sh"
164164
```
@@ -170,12 +170,15 @@ commands:
170170
Commands can also live in individual repository `raid.yaml` files, scoped to that service. They are automatically available when the profile is loaded.
171171

172172
```yaml title="~/dev/api/raid.yaml"
173+
name: api
174+
branch: main
175+
173176
commands:
174177
- name: "migrate"
175178
usage: "Run pending database migrations"
176179
tasks:
177180
- type: Set
178-
var: ENV
181+
var: "ENV"
179182
value: "local"
180183
- type: Confirm
181184
message: "Run migrations against $ENV?"

‎docs/examples/environments.md‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,10 @@ Profile-level environments define shared variables and tasks that apply across a
1818
name: "platform"
1919

2020
repositories:
21-
- name: api
21+
- name: "api"
2222
url: "git@github.com:my-org/api.git"
2323
path: "~/dev/api"
24-
- name: frontend
24+
- name: "frontend"
2525
url: "git@github.com:my-org/frontend.git"
2626
path: "~/dev/frontend"
2727

@@ -45,6 +45,9 @@ environments:
4545
Each repo defines its own environment variables and additional tasks in its `raid.yaml`:
4646

4747
```yaml title="~/dev/api/raid.yaml"
48+
name: "api"
49+
branch: "main"
50+
4851
environments:
4952
- name: "local"
5053
variables:
@@ -58,7 +61,7 @@ environments:
5861
value: "debug"
5962
tasks:
6063
- type: Shell
61-
cmd: docker-compose up -d db
64+
cmd: "docker-compose up -d db"
6265
- name: "staging"
6366
variables:
6467
- name: "DATABASE_URL"
@@ -87,6 +90,9 @@ environments:
8790
```
8891

8992
```yaml title="~/dev/frontend/raid.yaml"
93+
name: "frontend"
94+
branch: "main"
95+
9096
environments:
9197
- name: "local"
9298
variables:
@@ -131,6 +137,9 @@ For production, the `Confirm` tasks in the profile and each repo's `raid.yaml` w
131137
If local values differ between developers (ports, paths, credentials), use `Prompt` and `Template` tasks instead of hardcoded `variables` to generate values at apply-time:
132138

133139
```yaml title="~/dev/api/raid.yaml"
140+
name: "api"
141+
branch: "main"
142+
134143
environments:
135144
- name: "local"
136145
tasks:

‎docs/examples/new-developer.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ install:
4747
- type: Shell
4848
cmd: "brew bundle"
4949
condition:
50-
platform: darwin
50+
platform: "darwin"
5151
- type: Shell
5252
cmd: "raid env local"
5353
- type: Print

0 commit comments

Comments
 (0)