@davidbyoung/software-factory 0.1.9 → 0.1.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/board.mjs +1 -3
- package/dist/cli.mjs +9 -0
- package/dist/code-host/github.d.mts +1 -1
- package/dist/code-host/github.mjs +29 -2
- package/dist/code-host/types.d.mts +16 -1
- package/dist/code-host/types.mjs +8 -0
- package/dist/columns-suggest.d.mts +25 -5
- package/dist/columns-suggest.mjs +117 -21
- package/dist/commands.d.mts +3 -2
- package/dist/commands.mjs +16 -2
- package/dist/config.d.mts +16 -3
- package/dist/config.mjs +102 -22
- package/dist/doctor.mjs +1 -2
- package/dist/explain.mjs +7 -1
- package/dist/init.d.mts +8 -0
- package/dist/init.mjs +83 -22
- package/dist/lib/gh.d.mts +6 -0
- package/dist/lib/gh.mjs +11 -1
- package/dist/lib/listed.d.mts +3 -2
- package/dist/lib/listed.mjs +5 -4
- package/dist/poller.d.mts +1 -1
- package/dist/poller.mjs +9 -6
- package/dist/pr.mjs +9 -1
- package/dist/ticket.d.mts +3 -0
- package/dist/ticket.mjs +27 -1
- package/docs/builds.md +26 -13
- package/docs/cli.md +30 -27
- package/docs/configuration.md +187 -35
- package/docs/existing-repo.md +47 -26
- package/docs/github/by-hand.md +13 -1
- package/docs/github/setup.md +9 -2
- package/docs/presets.md +15 -3
- package/docs/updating.md +129 -2
- package/docs/workflow.md +1 -1
- package/package.json +1 -1
- package/settings.schema.json +14 -9
- package/skills/factory-build/SKILL.md +39 -7
- package/skills/factory-deps/SKILL.md +6 -4
package/dist/ticket.mjs
CHANGED
|
@@ -67,6 +67,7 @@ import { boardConfigOf, checkFields } from "./board.mjs";
|
|
|
67
67
|
import { refuseBareTags, refuseOverride } from "./guard-ticket-text.mjs";
|
|
68
68
|
import { openTickets } from "./tickets/index.mjs";
|
|
69
69
|
import { GROUPS, need, supports, } from "./tickets/types.mjs";
|
|
70
|
+
import { NotSignedInError } from "./code-host/types.mjs";
|
|
70
71
|
export async function readComments(c, issue) {
|
|
71
72
|
return (await c.tickets.read(issue)).comments;
|
|
72
73
|
}
|
|
@@ -292,11 +293,28 @@ const READS_AND_WRITES = new Set([
|
|
|
292
293
|
"open",
|
|
293
294
|
"label",
|
|
294
295
|
"link",
|
|
296
|
+
"branch",
|
|
295
297
|
"blockers",
|
|
296
298
|
"block",
|
|
297
299
|
"unblock",
|
|
298
300
|
"supports",
|
|
299
301
|
]);
|
|
302
|
+
/** The branch a build of `ticket` pushes, from `code-host.branch-name`. */
|
|
303
|
+
async function branchOf(ticket, d) {
|
|
304
|
+
let user = "";
|
|
305
|
+
if (d.branchName.includes("{user}"))
|
|
306
|
+
try {
|
|
307
|
+
user = await d.signedInAs(d.repository, d.codeHost);
|
|
308
|
+
}
|
|
309
|
+
catch (e) {
|
|
310
|
+
if (!(e instanceof NotSignedInError))
|
|
311
|
+
throw e;
|
|
312
|
+
throw new Error("code-host.branch-name uses {user}, and gh is not signed in: run gh auth login", { cause: e });
|
|
313
|
+
}
|
|
314
|
+
return d.branchName
|
|
315
|
+
.replaceAll("{ticket}", String(ticket))
|
|
316
|
+
.replaceAll("{user}", user);
|
|
317
|
+
}
|
|
300
318
|
/** The commands that read or write a ticket for a skill. Null when
|
|
301
319
|
* `command` is not one of them. */
|
|
302
320
|
async function ticketCommand(command, args, d) {
|
|
@@ -413,6 +431,11 @@ async function ticketCommand(command, args, d) {
|
|
|
413
431
|
case "link":
|
|
414
432
|
d.out(t.linkText(numbered()));
|
|
415
433
|
return 0;
|
|
434
|
+
case "branch": {
|
|
435
|
+
const ticket = await t.read(numbered());
|
|
436
|
+
d.out(await branchOf(ticket.number, d));
|
|
437
|
+
return 0;
|
|
438
|
+
}
|
|
416
439
|
case "blockers": {
|
|
417
440
|
const list = await need(t, "blockers").list(numbered());
|
|
418
441
|
for (const b of list)
|
|
@@ -437,7 +460,7 @@ async function ticketCommand(command, args, d) {
|
|
|
437
460
|
return null;
|
|
438
461
|
}
|
|
439
462
|
}
|
|
440
|
-
const USAGE = "Usage: npx --no-install factory ticket claim|still-live|stop|end|refining|waiting|refined|ready|cost|view|list|edit|comment|open|label|link|blockers|block|unblock|supports|follow-up ...";
|
|
463
|
+
const USAGE = "Usage: npx --no-install factory ticket claim|still-live|stop|end|refining|waiting|refined|ready|cost|view|list|edit|comment|open|label|link|branch|blockers|block|unblock|supports|follow-up ...";
|
|
441
464
|
export async function main(argv, deps) {
|
|
442
465
|
const [command, first, ...rest] = argv;
|
|
443
466
|
const issue = Number(first);
|
|
@@ -450,6 +473,8 @@ export async function main(argv, deps) {
|
|
|
450
473
|
...deps,
|
|
451
474
|
config: boardConfigOf(settings),
|
|
452
475
|
codeHost: settings.codeHost.type,
|
|
476
|
+
// Null only when init reads the settings to ask for it.
|
|
477
|
+
branchName: settings.codeHost.branchName,
|
|
453
478
|
repository,
|
|
454
479
|
board,
|
|
455
480
|
...opened,
|
|
@@ -561,6 +586,7 @@ export async function run(argv) {
|
|
|
561
586
|
return main(argv, {
|
|
562
587
|
open: (settings, target) => openTickets(settings, target),
|
|
563
588
|
openPulls: (repository, codeHost) => openCodeHost(repository, codeHost).open(),
|
|
589
|
+
signedInAs: (repository, codeHost) => openCodeHost(repository, codeHost).signedInAs(),
|
|
564
590
|
runner: (repository, name) => openRunner(repository, name),
|
|
565
591
|
settings: () => loadSettings(),
|
|
566
592
|
env: process.env,
|
package/docs/builds.md
CHANGED
|
@@ -116,28 +116,40 @@ does no further check.
|
|
|
116
116
|
### What it reads from its environment
|
|
117
117
|
|
|
118
118
|
On a server you host, the poller runs with no copy of your repository, so
|
|
119
|
-
it takes everything from environment variables. All
|
|
120
|
-
|
|
119
|
+
it takes everything from environment variables. All five are required.
|
|
120
|
+
Without `FACTORY_REPOSITORY` it doesn't start. Without any of the others,
|
|
121
|
+
it logs `not polling:` naming each that is missing, and starts no build
|
|
122
|
+
until they are set. On a schedule it has a
|
|
121
123
|
checkout, and needs only the token.
|
|
122
124
|
|
|
123
125
|
| Variable | What it is |
|
|
124
126
|
| ---------------------- | ------------------------------------------------------------------- |
|
|
125
127
|
| `FACTORY_REPOSITORY` | The repository, as `owner/name` |
|
|
126
128
|
| `FACTORY_BOARD_OWNER` | The account the board belongs to |
|
|
127
|
-
| `FACTORY_BOARD_NUMBER` |
|
|
129
|
+
| `FACTORY_BOARD_NUMBER` | The board's number, the last part of its address |
|
|
128
130
|
| `FACTORY_BOARD_TOKEN` | An access token that can read the board, comment, and start a build |
|
|
131
|
+
| `FACTORY_READY_COLUMN` | The column that approves a build |
|
|
129
132
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
[`
|
|
134
|
-
|
|
135
|
-
when it applies.
|
|
133
|
+
The repository, the board's number, and the ready column repeat what your
|
|
134
|
+
settings file says, because the poller cannot read it. The ready column
|
|
135
|
+
is the one [`tickets.columns.ready`](configuration.md#ticketscolumns)
|
|
136
|
+
names. [`factory board check`](cli.md) prints it on the ready row, for
|
|
137
|
+
you to copy:
|
|
136
138
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
139
|
+
```text
|
|
140
|
+
? ready Ready: the poller needs FACTORY_READY_COLUMN set to "Ready"
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
A poller only runs with a ready column: with `ready: none`, builds start
|
|
144
|
+
only when you ask, and there is no poller to host.
|
|
145
|
+
|
|
146
|
+
A poller set up before `FACTORY_READY_COLUMN` was required logs
|
|
147
|
+
`not polling: FACTORY_READY_COLUMN not set` after an update, and polls
|
|
148
|
+
nothing until you set it.
|
|
149
|
+
|
|
150
|
+
The factory takes the board's owner to be the repository's owner
|
|
151
|
+
everywhere else, a person or an organization, so a board owned by another
|
|
152
|
+
account is not supported yet.
|
|
141
153
|
|
|
142
154
|
### Its limits
|
|
143
155
|
|
|
@@ -171,6 +183,7 @@ docker run \
|
|
|
171
183
|
-e FACTORY_BOARD_OWNER=your-name \
|
|
172
184
|
-e FACTORY_BOARD_NUMBER=1 \
|
|
173
185
|
-e FACTORY_BOARD_TOKEN \
|
|
186
|
+
-e FACTORY_READY_COLUMN=Ready \
|
|
174
187
|
ghcr.io/davidbyoung/software-factory-poller:0.2.0
|
|
175
188
|
```
|
|
176
189
|
|
package/docs/cli.md
CHANGED
|
@@ -51,7 +51,7 @@ nothing to fix.
|
|
|
51
51
|
`doctor` prints its checks under headings: `Settings and files`, then
|
|
52
52
|
each tool's name, such as `GitHub` or `Claude Code`, then the parts you
|
|
53
53
|
left off. Each check starts with a mark: ✓ works, ✗ needs fixing, ?
|
|
54
|
-
|
|
54
|
+
worth a look, and - off on purpose. `doctor` exits 1 when a
|
|
55
55
|
check fails. GitHub never lets a secret be read back, so `doctor` checks
|
|
56
56
|
only that each secret your parts read is set.
|
|
57
57
|
|
|
@@ -137,32 +137,33 @@ prints what the ticket system returned as one JSON value. `edit`,
|
|
|
137
137
|
`comment`, and `open` refuse a body with a bare tag-like `<word>` the
|
|
138
138
|
ticket system would swallow, name it, and post nothing.
|
|
139
139
|
|
|
140
|
-
| Command | What it does
|
|
141
|
-
| ---------------------------------------------------------- |
|
|
142
|
-
| `factory ticket view N` | Prints ticket N: its title, state, labels, body, and comments with their IDs and authors
|
|
143
|
-
| `factory ticket view N --field NAME` | Prints one of `title`, `state`, `labels` (one per line), or `body`, and nothing else
|
|
144
|
-
| `factory ticket list` | Lists the open tickets: number, title, and labels, separated by tabs
|
|
145
|
-
| `factory ticket list --label LABEL` | Only those with the label. `--title "TITLE"` keeps those whose title is exactly that
|
|
146
|
-
| `factory ticket edit N [--title TITLE] [--body-file FILE]` | Replaces N's title, its body, or both. `--attach FILE` adds an image to a body
|
|
147
|
-
| `factory ticket comment N --body-file FILE` | Comments on N and prints the comment's ID. `--attach FILE` adds an image
|
|
148
|
-
| `factory ticket open --title TITLE --body-file FILE` | Opens a ticket and prints its number. `--label LABEL` adds a label
|
|
149
|
-
| `factory ticket label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off
|
|
150
|
-
| `factory ticket label N --was-removed LABEL` | Prints `yes` if the label was ever removed from N, otherwise `no`
|
|
151
|
-
| `factory ticket link N` | Prints the text that makes a merged pull request close N, such as "Closes #12"
|
|
152
|
-
| `factory ticket
|
|
153
|
-
| `factory ticket
|
|
154
|
-
| `factory ticket
|
|
155
|
-
| `factory ticket
|
|
156
|
-
| `factory ticket
|
|
157
|
-
| `factory ticket
|
|
158
|
-
| `factory ticket
|
|
159
|
-
| `factory ticket
|
|
160
|
-
| `factory ticket
|
|
161
|
-
| `factory ticket
|
|
162
|
-
| `factory ticket
|
|
163
|
-
| `factory ticket
|
|
164
|
-
| `factory ticket
|
|
165
|
-
| `factory
|
|
140
|
+
| Command | What it does |
|
|
141
|
+
| ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
142
|
+
| `factory ticket view N` | Prints ticket N: its title, state, labels, body, and comments with their IDs and authors |
|
|
143
|
+
| `factory ticket view N --field NAME` | Prints one of `title`, `state`, `labels` (one per line), or `body`, and nothing else |
|
|
144
|
+
| `factory ticket list` | Lists the open tickets: number, title, and labels, separated by tabs |
|
|
145
|
+
| `factory ticket list --label LABEL` | Only those with the label. `--title "TITLE"` keeps those whose title is exactly that |
|
|
146
|
+
| `factory ticket edit N [--title TITLE] [--body-file FILE]` | Replaces N's title, its body, or both. `--attach FILE` adds an image to a body |
|
|
147
|
+
| `factory ticket comment N --body-file FILE` | Comments on N and prints the comment's ID. `--attach FILE` adds an image |
|
|
148
|
+
| `factory ticket open --title TITLE --body-file FILE` | Opens a ticket and prints its number. `--label LABEL` adds a label |
|
|
149
|
+
| `factory ticket label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off |
|
|
150
|
+
| `factory ticket label N --was-removed LABEL` | Prints `yes` if the label was ever removed from N, otherwise `no` |
|
|
151
|
+
| `factory ticket link N` | Prints the text that makes a merged pull request close N, such as "Closes #12" |
|
|
152
|
+
| `factory ticket branch N` | Prints the branch a build of N pushes, from [`code-host.branch-name`](configuration.md#code-host), such as `12` or `feature/octocat/12`. Exits 1 when N does not exist, or the pattern has `{user}` and `gh` is not signed in |
|
|
153
|
+
| `factory ticket blockers N` | One line per ticket N waits on: its number and whether it is open |
|
|
154
|
+
| `factory ticket block N --by M` | Records that N waits on M |
|
|
155
|
+
| `factory ticket unblock N --by M` | Removes that record |
|
|
156
|
+
| `factory ticket supports GROUP` | Prints `yes` or `no` for `board`, `blockers`, `label-history`, or `attachments` |
|
|
157
|
+
| `factory ticket claim N` | Claims ticket N for this session. Prints `claimed`, `held by`, or `blocked by` |
|
|
158
|
+
| `factory ticket still-live N` | Says whether this session still holds N |
|
|
159
|
+
| `factory ticket stop N "reason"` | Releases N and says why |
|
|
160
|
+
| `factory ticket end N` | A run's last step: releases this session's claim if no open pull request links N. Prints `released`, `kept`, or `not live` |
|
|
161
|
+
| `factory ticket refining N` | Marks N as being refined |
|
|
162
|
+
| `factory ticket waiting N` | Marks N as waiting on your reply to a round of questions |
|
|
163
|
+
| `factory ticket refined N` | Marks N as refined, unless its body lacks what a build reads. `--check` makes that check alone and posts nothing |
|
|
164
|
+
| `factory ticket ready N` | Moves N to Ready. Only when you ask a session to |
|
|
165
|
+
| `factory ticket cost N` | Notes what this session spent on N since it started |
|
|
166
|
+
| `factory follow-up FILE "what is wrong"` | Adds a line about that file to the follow-ups ticket, opening the ticket if none is open |
|
|
166
167
|
|
|
167
168
|
`factory ticket refined N` posts nothing and exits 1 when N's body lacks a
|
|
168
169
|
section a build reads, printing one line for each, such as
|
|
@@ -182,6 +183,7 @@ ticket system.
|
|
|
182
183
|
| `factory pr reply N COMMENT --body-file FILE` | Replies on a thread |
|
|
183
184
|
| `factory pr resolve N COMMENT` | Resolves a thread |
|
|
184
185
|
| `factory pr closes N` | The tickets N closes |
|
|
186
|
+
| `factory pr for-branch BRANCH` | The newest pull request from BRANCH, open or not: `#N open`, `#N merged`, or `#N closed`, or `none` when there has been none |
|
|
185
187
|
| `factory pr wait-checks N` | Waits for every CI run on the pushed commit. Prints `success`, `failure:` with the failed checks, or `no checks` |
|
|
186
188
|
| `factory pr ready N` | Marks a draft ready for review. When `commit.gpgsign` is `true`, refuses while the code host shows a commit as not verified |
|
|
187
189
|
| `factory pr comments N` | N's conversation comments: ID, author, time, and first line. `--author LOGIN`, `--contains TEXT`, and `--json`, which prints each comment's `id`, `user.login`, `body`, and `created_at` |
|
|
@@ -223,6 +225,7 @@ You can run them too.
|
|
|
223
225
|
| `factory test-one FILE [NAME]` | Runs [`commands.test-one`](configuration.md#commandstest-one), one test file alone or the one test NAME in it, and exits with its status |
|
|
224
226
|
| `factory end-to-end FILE [--times K]` | Runs [`commands.end-to-end`](configuration.md#commandsend-to-end), one end-to-end spec alone, and exits with its status. With `--times K`, K times in a row, stopping at the first run that fails. Ends with `✓ The test passed.` or `✗ The test failed.` |
|
|
225
227
|
| `factory specs check` | Runs [`specs.check`](configuration.md#specscheck), the check of your written specs, and exits with its status, ending with `✓ The specs check passed.` or `✗ The specs check failed.`. Prints `specs are off` when `specs` is `none` |
|
|
228
|
+
| `factory specs change-name N` | Prints the name of the OpenSpec change a build of N writes, always `issue-N` whatever [`code-host.branch-name`](configuration.md#code-host) says. Exits 1 with `specs are off: there is no spec change to name` when [`specs`](configuration.md#specs) is `none` |
|
|
226
229
|
| `factory default-branch` | Prints the name of your repository's default branch, which nothing in the factory assumes is `main` |
|
|
227
230
|
|
|
228
231
|
`factory default-branch` asks, in turn, the event of the workflow run it
|
package/docs/configuration.md
CHANGED
|
@@ -34,9 +34,10 @@ The [glossary](glossary.md) has the rest.
|
|
|
34
34
|
|
|
35
35
|
## How the file works
|
|
36
36
|
|
|
37
|
-
- **
|
|
38
|
-
file has [`version`](#version)
|
|
39
|
-
|
|
37
|
+
- **Three settings are required, and a fourth before any build.** Every
|
|
38
|
+
file has [`version`](#version), [`repository`](#repository), and
|
|
39
|
+
[`code-host.branch-name`](#code-host), which `factory init` writes for
|
|
40
|
+
you, and a session can't build a ticket until you set
|
|
40
41
|
[`commands.gate`](#commandsgate). Every other setting has a default, and
|
|
41
42
|
you write it only when you want something else.
|
|
42
43
|
- **It holds only what a script needs.** Anything that needs judgment,
|
|
@@ -85,6 +86,9 @@ The [glossary](glossary.md) has the rest.
|
|
|
85
86
|
```yaml
|
|
86
87
|
version: 2
|
|
87
88
|
repository: your-name/your-repo
|
|
89
|
+
code-host:
|
|
90
|
+
type: github
|
|
91
|
+
branch-name: "{ticket}"
|
|
88
92
|
```
|
|
89
93
|
|
|
90
94
|
With only this, the factory refines a ticket when you run `/factory-refine N` in a session,
|
|
@@ -177,6 +181,13 @@ Where your tickets live, and which board shows them.
|
|
|
177
181
|
tickets:
|
|
178
182
|
type: github
|
|
179
183
|
board: 1
|
|
184
|
+
columns:
|
|
185
|
+
backlog: Backlog
|
|
186
|
+
refining: In refinement
|
|
187
|
+
ready: Ready
|
|
188
|
+
building: In progress
|
|
189
|
+
review: In review
|
|
190
|
+
done: Done
|
|
180
191
|
```
|
|
181
192
|
|
|
182
193
|
- **`type`** is the ticket system. Only `github` is built, and it is the
|
|
@@ -184,6 +195,8 @@ tickets:
|
|
|
184
195
|
- **`board`** is your GitHub Project's number: the last part of its
|
|
185
196
|
address, such as `1` in `github.com/users/your-name/projects/1`. The
|
|
186
197
|
default, `none`, means no board.
|
|
198
|
+
- **`columns`** says which of the board's columns shows each state, and a
|
|
199
|
+
board needs it: see [`tickets.columns`](#ticketscolumns).
|
|
187
200
|
|
|
188
201
|
Without a board, `factory status` still shows every ticket's state, which
|
|
189
202
|
the factory keeps in comments on the ticket. Builds then start only when
|
|
@@ -199,12 +212,14 @@ with it.
|
|
|
199
212
|
#### `tickets.columns`
|
|
200
213
|
|
|
201
214
|
The board has one column for each of the six
|
|
202
|
-
[states](workflow.md#the-six-states) a ticket goes through.
|
|
203
|
-
board's columns
|
|
204
|
-
|
|
205
|
-
state. `factory init` suggests this block when you choose a board without the
|
|
206
|
-
factory's columns: see
|
|
215
|
+
[states](workflow.md#the-six-states) a ticket goes through. This block
|
|
216
|
+
says which of your board's columns shows each state, and it names all
|
|
217
|
+
six. `factory init` writes it for you, from the board you choose: see
|
|
207
218
|
[You already have a board](existing-repo.md#you-already-have-a-board).
|
|
219
|
+
There is no default: your board's column names may not be the
|
|
220
|
+
factory's, and a guess would put tickets in the wrong column without
|
|
221
|
+
telling you.
|
|
222
|
+
|
|
208
223
|
A new GitHub Project starts with only Todo, In Progress, and Done,
|
|
209
224
|
so its settings would be:
|
|
210
225
|
|
|
@@ -213,73 +228,86 @@ tickets:
|
|
|
213
228
|
board: 7
|
|
214
229
|
columns:
|
|
215
230
|
backlog: Todo
|
|
216
|
-
building: In Progress
|
|
217
|
-
done: Done
|
|
218
231
|
refining: none
|
|
219
232
|
ready: none
|
|
233
|
+
building: In Progress
|
|
220
234
|
review: none
|
|
235
|
+
done: Done
|
|
221
236
|
builds:
|
|
222
237
|
trigger: manual
|
|
223
238
|
```
|
|
224
239
|
|
|
225
|
-
|
|
240
|
+
When init creates your board, or adds columns to one, it gives them the
|
|
241
|
+
factory's own names:
|
|
226
242
|
|
|
227
|
-
|
|
|
228
|
-
| ---------- |
|
|
229
|
-
| `backlog` | Backlog
|
|
230
|
-
| `refining` | In refinement
|
|
231
|
-
| `ready` | Ready
|
|
232
|
-
| `building` | In progress
|
|
233
|
-
| `review` | In review
|
|
234
|
-
| `done` | Done
|
|
243
|
+
| Key | Name of the column init creates |
|
|
244
|
+
| ---------- | ------------------------------- |
|
|
245
|
+
| `backlog` | Backlog |
|
|
246
|
+
| `refining` | In refinement |
|
|
247
|
+
| `ready` | Ready |
|
|
248
|
+
| `building` | In progress |
|
|
249
|
+
| `review` | In review |
|
|
250
|
+
| `done` | Done |
|
|
235
251
|
|
|
236
252
|
- **Capitals don't matter,** so "In progress" finds your "In Progress".
|
|
237
253
|
- **`none` means your board has no column for that state.** A ticket in
|
|
238
254
|
that state stays in the column of the state before it. With
|
|
239
255
|
`review: none`, a ticket whose pull request is in review stays in In
|
|
240
|
-
|
|
256
|
+
Progress. Every state can be `none` except `backlog`.
|
|
241
257
|
- **A state can take a list of columns,** when more than one of yours
|
|
242
|
-
means it.
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
258
|
+
means it. Init never writes a list, so add one to the block yourself.
|
|
259
|
+
A ticket in any of the columns is in that state. When the factory
|
|
260
|
+
moves a ticket into the state, it uses the first, and a ticket already
|
|
261
|
+
in any of them stays where it is:
|
|
246
262
|
|
|
247
263
|
```yaml
|
|
248
264
|
tickets:
|
|
249
265
|
board: 7
|
|
250
266
|
columns:
|
|
251
267
|
backlog: Todo
|
|
268
|
+
refining: none
|
|
269
|
+
ready: none
|
|
270
|
+
building: In Progress
|
|
252
271
|
# When a pull request opens, its ticket moves to Code review.
|
|
253
272
|
# One you moved to QA stays there.
|
|
254
273
|
review: [Code review, QA]
|
|
274
|
+
done: Done
|
|
255
275
|
```
|
|
256
276
|
|
|
257
277
|
`ready` takes one column, since only a ticket you approved goes there.
|
|
258
278
|
|
|
259
|
-
- **A ticket never
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
279
|
+
- **A ticket never stays in the ready column unless you approved it.**
|
|
280
|
+
With `building: none`, a ticket being built would stay in ready's
|
|
281
|
+
column, so it stays in refining's column instead. On a board with the
|
|
282
|
+
factory's columns and `building: none`, it shows in In refinement.
|
|
263
283
|
- **With `ready: none`, nothing on the board approves a build,** so you
|
|
264
284
|
need `builds.trigger: manual`, and you start each build by asking a
|
|
265
285
|
session.
|
|
266
286
|
- **A ticket in a column no state uses is left alone.** The board sync
|
|
267
287
|
doesn't move it or fill in its fields, and nothing builds it.
|
|
268
|
-
- **If you host your own poller
|
|
269
|
-
|
|
288
|
+
- **If you host your own poller,** it needs `FACTORY_READY_COLUMN` set
|
|
289
|
+
to the column `ready` names: see
|
|
270
290
|
[Builds](builds.md#what-it-reads-from-its-environment).
|
|
271
291
|
|
|
272
292
|
`factory config check` stops, naming the key, when `columns` has:
|
|
273
293
|
|
|
294
|
+
- no `board` beside it, or a `board` with no `columns`;
|
|
295
|
+
- a state left out, naming each one;
|
|
274
296
|
- a state it doesn't know;
|
|
275
297
|
- `backlog: none`;
|
|
276
298
|
- one column for two states;
|
|
277
299
|
- an empty list, or a list for `ready`;
|
|
278
|
-
- no `board` beside it;
|
|
279
300
|
- `ready: none` while [`builds.trigger`](#builds) isn't `manual`,
|
|
280
301
|
since then a build starts only from the ready column.
|
|
281
302
|
|
|
282
|
-
|
|
303
|
+
Such as:
|
|
304
|
+
|
|
305
|
+
```text
|
|
306
|
+
.claude/factory.yaml: tickets.columns: building and done have no column: give each a column, a list of columns, or none, or run factory init to choose them
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
`factory config check` doesn't read your board. `factory board check`
|
|
310
|
+
does, and says which of the columns you named the board lacks.
|
|
283
311
|
|
|
284
312
|
#### `tickets.fields`
|
|
285
313
|
|
|
@@ -373,13 +401,104 @@ you confirm them.
|
|
|
373
401
|
|
|
374
402
|
### `code-host`
|
|
375
403
|
|
|
376
|
-
Where your repository and its pull requests live
|
|
377
|
-
|
|
404
|
+
Where your repository and its pull requests live, and what every
|
|
405
|
+
[build](#words-this-page-uses) names the branch it pushes, in a session
|
|
406
|
+
on your machine and in the cloud alike.
|
|
378
407
|
|
|
379
408
|
```yaml
|
|
380
|
-
code-host:
|
|
409
|
+
code-host:
|
|
410
|
+
type: github
|
|
411
|
+
branch-name: "feature/{user}/{ticket}"
|
|
412
|
+
```
|
|
413
|
+
|
|
414
|
+
- **`type`** is the code host. GitHub is the only one so far, and it is
|
|
415
|
+
the default.
|
|
416
|
+
- **`branch-name`** is the pattern for the branch's name. It has no
|
|
417
|
+
default: [`factory init`](github/setup.md) asks for it and offers
|
|
418
|
+
`{ticket}`, so ticket 12 is built on a branch named `12`. A
|
|
419
|
+
[preset](#presets) can set it for every repository that follows it.
|
|
420
|
+
|
|
421
|
+
Without `branch-name`, `factory config check` stops:
|
|
422
|
+
|
|
423
|
+
```text
|
|
424
|
+
.claude/factory.yaml: code-host.branch-name: is required. Run factory init to set it, or add it, such as branch-name: "{ticket}"
|
|
425
|
+
```
|
|
426
|
+
|
|
427
|
+
A pattern uses these placeholders. It must have `{ticket}`; `{user}` is
|
|
428
|
+
for a convention that names who did the work, and a pattern can leave
|
|
429
|
+
it out:
|
|
430
|
+
|
|
431
|
+
| Placeholder | What it becomes | For ticket 12 |
|
|
432
|
+
| ----------- | ------------------------------------ | ------------- |
|
|
433
|
+
| `{ticket}` | The ticket's number, without `#` | `12` |
|
|
434
|
+
| `{user}` | The GitHub account the build runs as | `octocat` |
|
|
435
|
+
|
|
436
|
+
In a session, `{user}` is the account the GitHub CLI, `gh`, is signed in
|
|
437
|
+
as, exactly as GitHub spells it, so the same ticket built by two people
|
|
438
|
+
gets two branches. In GitHub Actions, it is the owner of
|
|
439
|
+
the [token the build runs with](github/reference.md#workflows), not
|
|
440
|
+
whoever approved the ticket, so with a shared bot account every branch
|
|
441
|
+
built in Actions carries the bot's name.
|
|
442
|
+
|
|
443
|
+
Keep the quotes, as in the examples. YAML reads an unquoted
|
|
444
|
+
`branch-name: {ticket}` as a map rather than as text, and
|
|
445
|
+
`factory config check` stops and says to quote it.
|
|
446
|
+
|
|
447
|
+
`{ticket}` gives each ticket its own branch, and the same branch every
|
|
448
|
+
time. So a ticket built a second time, such as the
|
|
449
|
+
[follow-ups ticket](workflow.md#follow-ups), a reopened ticket, or one whose first
|
|
450
|
+
build stopped, finds its earlier branch still on GitHub, unless GitHub
|
|
451
|
+
deleted it when its pull request merged. What the build does depends on
|
|
452
|
+
that branch's newest pull request:
|
|
453
|
+
|
|
454
|
+
- **Merged, with nothing pushed to the branch since:** the build deletes
|
|
455
|
+
the old branch and starts fresh, since its work is already merged.
|
|
456
|
+
- **Open:** the build stops before it starts and names the pull request.
|
|
457
|
+
Work that one instead, with `/factory-address-review N` for pull
|
|
458
|
+
request N.
|
|
459
|
+
- **Anything else:** closed without merging, no pull request at all, or
|
|
460
|
+
merged with commits pushed since. The build stops before it starts, so
|
|
461
|
+
no work is lost:
|
|
462
|
+
|
|
463
|
+
```text
|
|
464
|
+
Branch 12 is already on origin, with work no pull request merged. Open a pull request from it to keep that work, or delete it with: git push origin --delete 12
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
A build that stopped partway pushes its branch so its work is kept. To
|
|
468
|
+
keep it, open a pull request from the branch on GitHub. Otherwise
|
|
469
|
+
delete the branch, and build the ticket again with `/factory-build 12`.
|
|
470
|
+
|
|
471
|
+
Once you change the pattern, run `factory config check`, then
|
|
472
|
+
`factory sync` (every setting needs it, as
|
|
473
|
+
[How the file works](#how-the-file-works) says), then see what the
|
|
474
|
+
pattern gives one ticket:
|
|
475
|
+
|
|
476
|
+
```console
|
|
477
|
+
$ factory config check
|
|
478
|
+
✓ The settings are valid.
|
|
479
|
+
$ factory ticket branch 12
|
|
480
|
+
feature/octocat/12
|
|
381
481
|
```
|
|
382
482
|
|
|
483
|
+
`factory config check` stops on a placeholder it doesn't know, a pattern
|
|
484
|
+
without `{ticket}`, and a pattern git can't use as a branch name. Git
|
|
485
|
+
refuses a name that:
|
|
486
|
+
|
|
487
|
+
- has a space, a control character, `..`, `//`, or `@{`
|
|
488
|
+
- has any of `~`, `^`, `:`, `?`, `*`, `[`, or `\`
|
|
489
|
+
- starts with `-` or `/`, or ends with `/`, `.`, or `.lock`
|
|
490
|
+
- has a part between slashes that starts with `.` or ends with `.lock`
|
|
491
|
+
|
|
492
|
+
Anything else is fine, `#` and `_` included. The check names the first
|
|
493
|
+
fault it finds:
|
|
494
|
+
|
|
495
|
+
```text
|
|
496
|
+
.claude/factory.yaml: code-host.branch-name: feature//{ticket} can't be a git branch name: it has //
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
Commit `.claude/factory.yaml` and `.claude/factory.lock`. The next build
|
|
500
|
+
uses the new pattern; branches already pushed keep their names.
|
|
501
|
+
|
|
383
502
|
### `builds`
|
|
384
503
|
|
|
385
504
|
What starts a build when you approve a ticket, and where the build runs.
|
|
@@ -1101,6 +1220,17 @@ repository: harbor-goods/storefront
|
|
|
1101
1220
|
|
|
1102
1221
|
tickets:
|
|
1103
1222
|
board: 1
|
|
1223
|
+
columns:
|
|
1224
|
+
backlog: Backlog
|
|
1225
|
+
refining: In refinement
|
|
1226
|
+
ready: Ready
|
|
1227
|
+
building: In progress
|
|
1228
|
+
review: In review
|
|
1229
|
+
done: Done
|
|
1230
|
+
|
|
1231
|
+
code-host:
|
|
1232
|
+
type: github
|
|
1233
|
+
branch-name: "{ticket}"
|
|
1104
1234
|
|
|
1105
1235
|
builds:
|
|
1106
1236
|
trigger: own-server
|
|
@@ -1170,6 +1300,17 @@ repository: riverbend-studio/site
|
|
|
1170
1300
|
|
|
1171
1301
|
tickets:
|
|
1172
1302
|
board: 4
|
|
1303
|
+
columns:
|
|
1304
|
+
backlog: Backlog
|
|
1305
|
+
refining: In refinement
|
|
1306
|
+
ready: Ready
|
|
1307
|
+
building: In progress
|
|
1308
|
+
review: In review
|
|
1309
|
+
done: Done
|
|
1310
|
+
|
|
1311
|
+
code-host:
|
|
1312
|
+
type: github
|
|
1313
|
+
branch-name: "{ticket}"
|
|
1173
1314
|
|
|
1174
1315
|
commands:
|
|
1175
1316
|
before-commit:
|
|
@@ -1193,6 +1334,17 @@ repository: northwind-php/ledger
|
|
|
1193
1334
|
|
|
1194
1335
|
tickets:
|
|
1195
1336
|
board: 2
|
|
1337
|
+
columns:
|
|
1338
|
+
backlog: Backlog
|
|
1339
|
+
refining: In refinement
|
|
1340
|
+
ready: Ready
|
|
1341
|
+
building: In progress
|
|
1342
|
+
review: In review
|
|
1343
|
+
done: Done
|
|
1344
|
+
|
|
1345
|
+
code-host:
|
|
1346
|
+
type: github
|
|
1347
|
+
branch-name: "{ticket}"
|
|
1196
1348
|
|
|
1197
1349
|
commands:
|
|
1198
1350
|
build-setup:
|