@davidbyoung/software-factory 0.1.1 → 0.1.3
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/README.md +8 -9
- package/dist/agent/claude-code.d.mts +3 -0
- package/dist/agent/claude-code.mjs +89 -0
- package/dist/agent/index.d.mts +2 -0
- package/dist/agent/index.mjs +5 -0
- package/dist/board.mjs +1 -1
- package/dist/cli.mjs +17 -2
- package/dist/code-host/github-setup.d.mts +5 -0
- package/dist/code-host/github-setup.mjs +133 -0
- package/dist/code-host/github.mjs +4 -0
- package/dist/code-host/index.d.mts +1 -1
- package/dist/code-host/index.mjs +2 -1
- package/dist/code-host/types.d.mts +2 -0
- package/dist/config.d.mts +26 -7
- package/dist/config.mjs +79 -26
- package/dist/doctor.d.mts +6 -14
- package/dist/doctor.mjs +52 -64
- package/dist/explain.d.mts +2 -0
- package/dist/explain.mjs +127 -0
- package/dist/init.d.mts +8 -12
- package/dist/init.mjs +179 -131
- package/dist/lib/has-command.d.mts +5 -0
- package/dist/lib/has-command.mjs +8 -0
- package/dist/lib/listed.d.mts +2 -0
- package/dist/lib/listed.mjs +4 -0
- package/dist/lib/work-status.d.mts +12 -2
- package/dist/lib/work-status.mjs +14 -3
- package/dist/parts.d.mts +18 -15
- package/dist/parts.mjs +15 -43
- package/dist/poller.d.mts +20 -3
- package/dist/poller.mjs +62 -15
- package/dist/remove.d.mts +11 -0
- package/dist/remove.mjs +156 -0
- package/dist/runner/github-actions.d.mts +1 -1
- package/dist/runner/github-actions.mjs +12 -0
- package/dist/runner/index.d.mts +1 -1
- package/dist/runner/index.mjs +2 -1
- package/dist/runner/setup.d.mts +2 -0
- package/dist/runner/setup.mjs +22 -0
- package/dist/runner/types.d.mts +3 -0
- package/dist/runner/types.mjs +0 -2
- package/dist/setup.d.mts +98 -0
- package/dist/setup.mjs +3 -0
- package/dist/status.d.mts +4 -4
- package/dist/status.mjs +8 -7
- package/dist/sync.d.mts +22 -3
- package/dist/sync.mjs +144 -11
- package/dist/tickets/github-setup.d.mts +2 -0
- package/dist/tickets/github-setup.mjs +50 -0
- package/dist/tickets/github.mjs +0 -2
- package/dist/tickets/index.mjs +2 -1
- package/dist/tickets/transport.mjs +1 -3
- package/dist/tickets/types.mjs +0 -2
- package/dist/tool-names.d.mts +11 -0
- package/dist/tool-names.mjs +20 -0
- package/dist/tools.d.mts +56 -0
- package/dist/tools.mjs +76 -0
- package/docs/builds.md +103 -51
- package/docs/cli.md +42 -42
- package/docs/configuration.md +38 -32
- package/docs/design.md +1 -1
- package/docs/developing.md +156 -67
- package/docs/existing-repo.md +20 -9
- package/docs/github/by-hand.md +321 -0
- package/docs/github/reference.md +65 -61
- package/docs/github/setup.md +83 -267
- package/docs/glossary.md +5 -4
- package/docs/limitations.md +12 -10
- package/docs/plugins.md +12 -17
- package/docs/quick-start.md +62 -105
- package/docs/removing.md +36 -16
- package/docs/skills.md +47 -37
- package/docs/updating.md +2 -6
- package/docs/workflow.md +13 -12
- package/package.json +5 -3
- package/poller.Dockerfile +10 -18
- package/rules.md +14 -12
- package/settings.schema.json +24 -0
- package/skills/factory-build/SKILL.md +1 -1
- package/skills/factory-trace/SKILL.md +79 -0
- package/workflows/factory-build.yml +5 -4
- package/workflows/factory-deps-auto-merge.yml +3 -2
- package/workflows/factory-poller.yml +46 -0
package/docs/developing.md
CHANGED
|
@@ -8,8 +8,18 @@ How to work on the factory itself. For using it, start with the
|
|
|
8
8
|
This repository holds the package, its docs, and its tests, and publishes
|
|
9
9
|
the package to npm as `@davidbyoung/software-factory`. It was developed
|
|
10
10
|
inside the private repository it was drawn out of until 0.1.0, and moved
|
|
11
|
-
here with a fresh history. Its tickets are
|
|
12
|
-
repository's
|
|
11
|
+
here with a fresh history. Its tickets are issues here, shown on a board
|
|
12
|
+
it shares with that repository: each repository's sync reads only its own
|
|
13
|
+
cards.
|
|
14
|
+
|
|
15
|
+
**It uses the factory on itself.** `.claude/factory.yaml` here sets the
|
|
16
|
+
board, OpenSpec, and the CI review, and `node bin/factory.js sync` copies
|
|
17
|
+
this repository's own skills, agents, rules, and workflows into `.claude/`
|
|
18
|
+
and `.github/`, with hooks that run `bin/factory.js` at the root. So a
|
|
19
|
+
change to a skill shows in the same pull request twice: the source, and
|
|
20
|
+
the copy this repository's own sessions follow. `CLAUDE.md` says what is
|
|
21
|
+
this repository's own, and `npx --no-install factory` finds the package's
|
|
22
|
+
own command here without installing it.
|
|
13
23
|
|
|
14
24
|
A change reaches a repository that uses the factory as a release: a new
|
|
15
25
|
version on npm, then Dependabot's pull request there, which `factory-deps`
|
|
@@ -20,40 +30,44 @@ completes with the files the version writes ([Updating](updating.md)).
|
|
|
20
30
|
The factory is the npm package `@davidbyoung/software-factory`. Parts not
|
|
21
31
|
marked working below exist only in these docs.
|
|
22
32
|
|
|
23
|
-
| Part
|
|
24
|
-
|
|
|
25
|
-
| Refining, building, and working a pull request's review
|
|
26
|
-
| The board, its sync, and `status`
|
|
27
|
-
| Builds from the board, with a poller you host
|
|
28
|
-
| Builds that run in GitHub Actions, started by a command
|
|
29
|
-
| Starting builds from the board, and the review, conflict, and dependency runs, in GitHub Actions
|
|
30
|
-
| Who merges, and the review's verdict
|
|
31
|
-
| The labels `merge: manual` and `verdict: override`
|
|
32
|
-
| These docs
|
|
33
|
-
| `.claude/factory.yaml`, and the factory's files kept apart from the host's
|
|
34
|
-
| The follow-ups ticket as one checklist
|
|
35
|
-
| The `factory` tool, `sync`, and the package folder
|
|
36
|
-
| A global `factory` command that runs each repository's own copy
|
|
37
|
-
| The automated review as one of the factory's workflows, and `ci-review`
|
|
38
|
-
| Nothing in the package names the repository it was drawn out of, checked in the folder and the packed tarball
|
|
39
|
-
| The `factory-` names and the `FACTORY_` secrets
|
|
40
|
-
| Ticket commands that go through one interface
|
|
41
|
-
| The code host and the runner, each behind one interface
|
|
42
|
-
| A published package
|
|
43
|
-
|
|
|
44
|
-
|
|
|
45
|
-
|
|
|
46
|
-
|
|
|
47
|
-
|
|
|
48
|
-
|
|
|
49
|
-
| `
|
|
50
|
-
|
|
|
51
|
-
|
|
|
52
|
-
|
|
|
53
|
-
| `
|
|
54
|
-
|
|
|
55
|
-
|
|
|
56
|
-
|
|
|
33
|
+
| Part | State |
|
|
34
|
+
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
|
|
35
|
+
| Refining, building, and working a pull request's review | Working |
|
|
36
|
+
| The board, its sync, and `status` | Working |
|
|
37
|
+
| Builds from the board, with a poller you host | Working |
|
|
38
|
+
| Builds that run in GitHub Actions, started by a command | Working |
|
|
39
|
+
| Starting builds from the board, and the review, conflict, and dependency runs, in GitHub Actions | Working |
|
|
40
|
+
| Who merges, and the review's verdict | Working |
|
|
41
|
+
| The labels `merge: manual` and `verdict: override` | Working |
|
|
42
|
+
| These docs | Working |
|
|
43
|
+
| `.claude/factory.yaml`, and the factory's files kept apart from the host's | Working |
|
|
44
|
+
| The follow-ups ticket as one checklist | Working |
|
|
45
|
+
| The `factory` tool, `sync`, and the package folder | Working |
|
|
46
|
+
| A global `factory` command that runs each repository's own copy | Working |
|
|
47
|
+
| The automated review as one of the factory's workflows, and [`ci-review`](configuration.md#ci-review) | Working |
|
|
48
|
+
| Nothing in the package names the repository it was drawn out of, checked in the folder and the packed tarball | Working |
|
|
49
|
+
| The `factory-` names and the `FACTORY_` secrets | Working |
|
|
50
|
+
| Ticket commands that go through one interface | Working |
|
|
51
|
+
| The code host and the runner, each behind one interface | Working |
|
|
52
|
+
| A published package | Working |
|
|
53
|
+
| Updates through Dependabot, which `factory-deps` completes with `factory sync` | Working |
|
|
54
|
+
| `factory board --dry-run` | Working |
|
|
55
|
+
| Your own column names on a board | Working |
|
|
56
|
+
| A UI reviewer for any website | Working |
|
|
57
|
+
| Built-in measurements for any website | Working |
|
|
58
|
+
| A design skill for any website | Working |
|
|
59
|
+
| `init`, which can be re-run, and `doctor` | Working |
|
|
60
|
+
| A second repository set up and removed from the quick start alone | Working |
|
|
61
|
+
| `factory remove` | Working |
|
|
62
|
+
| Starting builds from a scheduled workflow, `factory poller --once`, and a poller built from an installed package | Working |
|
|
63
|
+
| [`rules`](configuration.md#rules) in the settings, `factory config explain`, and the `factory-trace` skill | Working |
|
|
64
|
+
| `approvers` in the settings | Planned, [#14](https://github.com/davidbyoung/software-factory/issues/14) |
|
|
65
|
+
| `factory migrate` | Not planned. The first release that changes the settings' shape adds it |
|
|
66
|
+
| Another ticket system, such as Jira | Not planned. The design leaves room |
|
|
67
|
+
| A ticket system or code host named by a package, for an adapter you write yourself | Not planned. The design leaves room |
|
|
68
|
+
| Another code host or runner | Not planned. The design leaves room |
|
|
69
|
+
| Each tool's setup, checks, and removal declared by the tool | Working |
|
|
70
|
+
| Sharing plug-ins between repositories | Not planned |
|
|
57
71
|
|
|
58
72
|
When a part is built, its pull request updates this table, and corrects any
|
|
59
73
|
page the build had to differ from. [The CLI](cli.md) marks each command
|
|
@@ -117,8 +131,9 @@ guard runs before every command a session runs: `npx` took 289 ms a call,
|
|
|
117
131
|
`node` on the launcher 56 ms.
|
|
118
132
|
|
|
119
133
|
To prove the package works outside its host, CI packs the folder, installs
|
|
120
|
-
the tarball into an empty repository, and runs `
|
|
121
|
-
`config check`, and `plugins`
|
|
134
|
+
the tarball into an empty repository, and runs `factory sync`,
|
|
135
|
+
`factory sync --check`, `factory config check`, and `factory plugins`
|
|
136
|
+
there:
|
|
122
137
|
|
|
123
138
|
```bash
|
|
124
139
|
npm run pack-check
|
|
@@ -152,7 +167,8 @@ one does. That is what keeps the folder movable.
|
|
|
152
167
|
## Adding a ticket system
|
|
153
168
|
|
|
154
169
|
Only GitHub is built. The factory is built so that a second system is an
|
|
155
|
-
addition, not a rewrite. Four rules keep it that way
|
|
170
|
+
addition, not a rewrite. Four rules keep it that way, and its setup is
|
|
171
|
+
[declared like any tool's](#setting-a-tool-up).
|
|
156
172
|
|
|
157
173
|
**1. Nothing talks to the ticket system except through the tool.** A skill
|
|
158
174
|
never runs `gh issue` or calls GitHub's issues or projects API. It runs
|
|
@@ -168,13 +184,12 @@ runs. Every command reaches a ticket, a pull request, or a build through
|
|
|
168
184
|
one of them, and a test fails when a file elsewhere under `src/` calls
|
|
169
185
|
GitHub or holds a `github.com` address.
|
|
170
186
|
|
|
171
|
-
**3. The tool reads `tickets.type` and hands
|
|
172
|
-
adapter.** An adapter is one module in
|
|
173
|
-
`
|
|
174
|
-
|
|
187
|
+
**3. The tool reads [`tickets.type`](configuration.md#tickets) and hands
|
|
188
|
+
the work to that type's adapter.** An adapter is one module in
|
|
189
|
+
`src/tickets/` that implements the `Tickets` type in
|
|
190
|
+
`src/tickets/types.mts`. `github` is the only one; any other value fails
|
|
191
|
+
`factory config check` and every ticket command with
|
|
175
192
|
`tickets.type "X" is not supported. "github" is the only ticket system built.`
|
|
176
|
-
A type that names a package, so a team can write an adapter for a system
|
|
177
|
-
the factory does not ship, is planned, not built.
|
|
178
193
|
|
|
179
194
|
| Operation | In `Tickets` | What it returns or does |
|
|
180
195
|
| ----------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -219,9 +234,8 @@ order is prose in the ticket and nothing enforces it.
|
|
|
219
234
|
and one for an answer in plain text, such as a job's log
|
|
220
235
|
(`src/tickets/transport.mts`). `ghTransport` runs the GitHub CLI, for
|
|
221
236
|
sessions and CI. `fetchTransport` calls the API with a token, for the
|
|
222
|
-
poller, which runs with no `gh
|
|
223
|
-
|
|
224
|
-
fails when it misses one.
|
|
237
|
+
poller, which runs with no `gh`: its image installs only the published
|
|
238
|
+
package.
|
|
225
239
|
|
|
226
240
|
What stays above the interface: working out a ticket's state from its
|
|
227
241
|
marker comments, costs, and the formatting of every view, in
|
|
@@ -243,18 +257,18 @@ a third.
|
|
|
243
257
|
## Adding a code host
|
|
244
258
|
|
|
245
259
|
The code host is where pull requests are. Only GitHub is built. The
|
|
246
|
-
settings name it with `code-host.type
|
|
247
|
-
a command the implementation of that name:
|
|
248
|
-
that implements the `CodeHost` type in
|
|
249
|
-
value fails `factory config check`,
|
|
250
|
-
settings and reaches a pull request, with
|
|
260
|
+
settings name it with [`code-host.type`](configuration.md#code-host), and
|
|
261
|
+
`src/code-host/index.mts` hands a command the implementation of that name:
|
|
262
|
+
one module in `src/code-host/` that implements the `CodeHost` type in
|
|
263
|
+
`src/code-host/types.mts`. Any other value fails `factory config check`,
|
|
264
|
+
and every command that reads the settings and reaches a pull request, with
|
|
251
265
|
`code-host.type "X" is not supported. "github" is the only code host built.`
|
|
252
|
-
A type that names a package is planned, not built.
|
|
253
266
|
|
|
254
267
|
A command that a workflow also runs, such as `factory pr`, does not read
|
|
255
268
|
the settings there, so an unreadable settings file cannot fail the
|
|
256
|
-
workflow's step; it asks for the default. The poller has no
|
|
257
|
-
all and names its implementations itself
|
|
269
|
+
workflow's step; it asks for the default. The poller you host has no
|
|
270
|
+
settings at all and names its implementations itself; a scheduled pass
|
|
271
|
+
reads the settings only for its board and Ready column.
|
|
258
272
|
|
|
259
273
|
| Operation | In `CodeHost` | What it returns or does |
|
|
260
274
|
| ---------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -307,7 +321,7 @@ of which call GitHub is sent belongs.
|
|
|
307
321
|
## Adding a runner
|
|
308
322
|
|
|
309
323
|
The runner is where an unattended build runs. Only GitHub Actions is
|
|
310
|
-
built. The settings name it with `builds.runner
|
|
324
|
+
built. The settings name it with [`builds.runner`](configuration.md#builds), and
|
|
311
325
|
`src/runner/index.mts` hands a command the implementation of that name:
|
|
312
326
|
one module in `src/runner/` that implements the `Runner` type in
|
|
313
327
|
`src/runner/types.mts`. Any other value fails `factory config check`, and
|
|
@@ -342,6 +356,44 @@ variables, and reach pull requests through the code host.
|
|
|
342
356
|
The in-memory runner is `tests/memory-runner.ts`, and GitHub Actions' has
|
|
343
357
|
its own tests against faked replies.
|
|
344
358
|
|
|
359
|
+
## Setting a tool up
|
|
360
|
+
|
|
361
|
+
A tool is a code host, a ticket system, a runner, or a coding agent. Each
|
|
362
|
+
says what it needs, so `factory init` sets it up, `factory doctor` checks
|
|
363
|
+
it, and `factory remove` takes it out, with no edit to those commands.
|
|
364
|
+
`src/tools.mts` registers each one by the name a setting gives it, with
|
|
365
|
+
how to open it and its setup, the `ToolSetup` type in `src/setup.mts`. The
|
|
366
|
+
names the settings accept are in `src/tool-names.mts`, and a test fails
|
|
367
|
+
when the two differ. Every member of a setup is optional.
|
|
368
|
+
|
|
369
|
+
| Member | What it gives | Used by |
|
|
370
|
+
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------- |
|
|
371
|
+
| `found` | Its row under "Found", when it says more than the tool's name, such as that a command is not installed | `init` |
|
|
372
|
+
| `steps` | A value to write under the tool's block of the settings, or a secret: which parts read it, how to get it, and how to check a pasted one | `init` |
|
|
373
|
+
| `checks` | Its own lines in `doctor`: that it is reachable, signed in, or configured, each failure with its fix in the tool's words | `doctor` |
|
|
374
|
+
| `leftovers` | What removing the factory leaves outside the repository, such as its secrets | `remove` |
|
|
375
|
+
| `unconfigure` | Its own files with the factory's part taken out, such as a coding agent's settings without the factory's hooks | `remove` |
|
|
376
|
+
|
|
377
|
+
**A value** is asked for once, after the parts are chosen, and written
|
|
378
|
+
under the tool's block: a ticket system's under `tickets`, which accepts a
|
|
379
|
+
key only when the ticket system in use declares it. **A secret** names the
|
|
380
|
+
parts that read it, or none when the tool always needs it. `init` asks for
|
|
381
|
+
it when one of those is not set, prints the tool's introduction, opens
|
|
382
|
+
its page or runs its command, reads it in a masked prompt, and stores it
|
|
383
|
+
through the runner under each name the tool gives. Its words are the
|
|
384
|
+
tool's: the prompt, the reason it refuses a value, and the line when
|
|
385
|
+
nothing is pasted.
|
|
386
|
+
|
|
387
|
+
With more than one tool of a kind, `init` asks which, except for the code
|
|
388
|
+
host, which it reads from the git remote: each code host says which
|
|
389
|
+
remotes are its own. The coding agent has no setting until there is a
|
|
390
|
+
second.
|
|
391
|
+
|
|
392
|
+
The tests show a tool that the factory does not ship going through all
|
|
393
|
+
three commands: `tests/fake-tools.ts` has a ticket system with a site
|
|
394
|
+
address and a token of its own, and a coding agent whose configuration is
|
|
395
|
+
one file.
|
|
396
|
+
|
|
345
397
|
## Checking a change
|
|
346
398
|
|
|
347
399
|
| Check | What it proves |
|
|
@@ -349,7 +401,8 @@ its own tests against faked replies.
|
|
|
349
401
|
| The tool's unit tests | Each command does what it says. A new test is seen failing before it is trusted |
|
|
350
402
|
| `factory sync --check` | The copies match the source |
|
|
351
403
|
| Pack and install | CI packs the folder, installs it into an empty scratch repository, and runs `sync`, `config check`, and one read-only command there. It works outside its host |
|
|
352
|
-
|
|
|
404
|
+
| `factory-trace` | A change to a rule did not make some kind of change heavier, lighter, or ambiguous |
|
|
405
|
+
| Fork safety | No workflow it runs or ships could run a fork's code with a secret or write access (`tests/fork-safety.test.ts`). This repository is public |
|
|
353
406
|
| One throwaway ticket | After each stage, one small ticket goes through refine, build, and review for real. Nothing else tests the prose |
|
|
354
407
|
|
|
355
408
|
The skills are instructions, and instructions cannot be unit tested. The
|
|
@@ -357,15 +410,32 @@ last row is the only real proof that a change to one still works.
|
|
|
357
410
|
|
|
358
411
|
## Releasing
|
|
359
412
|
|
|
360
|
-
1.
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
413
|
+
1. On the Actions tab, run **Release** on `main` and choose the part of
|
|
414
|
+
the version to raise: patch for fixes alone, minor for something new,
|
|
415
|
+
and major for a change that breaks a repository using the factory. From
|
|
416
|
+
0.1.2, they give 0.1.3, 0.2.0, and 1.0.0.
|
|
417
|
+
2. The run raises the highest `vX.Y.Z` tag by that part, and runs the
|
|
418
|
+
whole CI on `main`'s commit, the same jobs a pull request gets. Only
|
|
419
|
+
once they pass does it publish the version to npm, then the poller's
|
|
420
|
+
image of that version to GitHub's container registry. Last, it tags the
|
|
421
|
+
commit and creates a GitHub Release whose notes list the pull requests
|
|
422
|
+
merged since the previous version. Those notes are the changelog, and
|
|
423
|
+
Dependabot copies them into the update pull requests it opens, so a
|
|
424
|
+
pull request's title is the line a user reads. When a release needs
|
|
425
|
+
something done by hand in a repository that uses the factory, edit its
|
|
426
|
+
GitHub Release as soon as the run ends, and put the steps first.
|
|
427
|
+
3. A run that stops partway has made no tag. Re-running its failed jobs,
|
|
428
|
+
from the run's page, finishes it on the same commit and version, and
|
|
429
|
+
does not publish to npm twice. A new run for a version npm already has
|
|
430
|
+
stops and says so.
|
|
431
|
+
4. After the first release that publishes the image, pull it with no
|
|
432
|
+
sign-in: `docker logout ghcr.io` and
|
|
433
|
+
`docker pull ghcr.io/davidbyoung/software-factory-poller:VERSION`. If it
|
|
434
|
+
is refused, set the package to Public on its GitHub page, once.
|
|
435
|
+
|
|
436
|
+
Nothing is committed for a release. `package.json` on `main` keeps the
|
|
437
|
+
version `0.0.0-development`, and the run writes the real one into its own
|
|
438
|
+
copy before publishing, so the tags and npm hold the released versions.
|
|
369
439
|
|
|
370
440
|
The first version, 0.1.0, was published by hand, since npm sets up a
|
|
371
441
|
trusted publisher only for a package that exists:
|
|
@@ -398,3 +468,22 @@ drawn out of.
|
|
|
398
468
|
to differ.
|
|
399
469
|
- **Examples carry the reason for a rule, without the host's private
|
|
400
470
|
history.**
|
|
471
|
+
|
|
472
|
+
### A page a reader follows
|
|
473
|
+
|
|
474
|
+
`README.md` and every page under `docs/` but this one is read by someone
|
|
475
|
+
who has never seen the factory and wants one thing done. `docs-reader`,
|
|
476
|
+
this repository's own reviewer, reads a changed page as that person.
|
|
477
|
+
|
|
478
|
+
- **A page says who it is for and what they will have at the end,** in its
|
|
479
|
+
first lines.
|
|
480
|
+
- **Lead with the command that does it.** The same steps by hand go on a
|
|
481
|
+
page of their own, linked once.
|
|
482
|
+
- **Say only what the reader must do or decide.** What a command does for
|
|
483
|
+
them is one sentence, and a link to the page that lists it.
|
|
484
|
+
- **A setting links to its entry in `docs/configuration.md` where a page
|
|
485
|
+
first names it.** A test fails on one that does not.
|
|
486
|
+
- **A setting the reader writes is shown as YAML they can paste,** with
|
|
487
|
+
what each line is for.
|
|
488
|
+
- **A step ends with how the reader knows it worked.**
|
|
489
|
+
- **Each fact has one home.** Every other page links to it.
|
package/docs/existing-repo.md
CHANGED
|
@@ -17,8 +17,16 @@ The factory's tool runs on Node and is installed with npm, whatever your
|
|
|
17
17
|
project is written in. In a PHP, Python, or Go repository that means:
|
|
18
18
|
|
|
19
19
|
- **A `package.json` appears**, holding one development dependency and
|
|
20
|
-
nothing else.
|
|
21
|
-
|
|
20
|
+
nothing else. Make it yourself before installing, marked private so it
|
|
21
|
+
can never be published:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
echo '{ "private": true }' > package.json
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Without one, npm installs into the nearest folder above that has a
|
|
28
|
+
`package.json`, if there is one, rather than into your repository.
|
|
29
|
+
|
|
22
30
|
- **`package-lock.json` is committed.** It is what keeps everyone on the
|
|
23
31
|
same version of the factory.
|
|
24
32
|
- **`node_modules/` is ignored.** `factory init` adds it
|
|
@@ -28,8 +36,9 @@ project is written in. In a PHP, Python, or Go repository that means:
|
|
|
28
36
|
- **Your own CI does not change.** The factory's cloud jobs install Node
|
|
29
37
|
for themselves. If you turn on the automated review, how it installs your
|
|
30
38
|
project, such as `composer install`, is yours to edit.
|
|
31
|
-
- **Your commands stay yours.**
|
|
32
|
-
|
|
39
|
+
- **Your commands stay yours.**
|
|
40
|
+
[`before-commit`](configuration.md#before-commit) in the settings takes
|
|
41
|
+
any command: `composer lint`, `make check`, `go vet ./...`.
|
|
33
42
|
|
|
34
43
|
The factory's hooks run its own tool, so they need nothing beyond Node.
|
|
35
44
|
Someone who only writes code by hand, and never runs an agent session in
|
|
@@ -58,9 +67,10 @@ Added to board 3: Backlog, In refinement, Ready, In review, Session, Runs in, Co
|
|
|
58
67
|
or move them all once and retire the column.
|
|
59
68
|
- **The factory's fields are overwritten on every sync.** Do not type into
|
|
60
69
|
Session, Runs in, or Cost. Your own fields are never touched.
|
|
61
|
-
- **Using your own column names** works today:
|
|
62
|
-
|
|
63
|
-
|
|
70
|
+
- **Using your own column names** works today:
|
|
71
|
+
[`tickets.columns`](configuration.md#ticketscolumns) in your settings
|
|
72
|
+
says which of your columns shows each state, and `none` says your board
|
|
73
|
+
has none. [Configuration](configuration.md#ticketscolumns) has the
|
|
64
74
|
mapping for a board with Todo, In Progress, and Done. To see what the
|
|
65
75
|
factory will do with your board, run:
|
|
66
76
|
|
|
@@ -105,7 +115,7 @@ names each file.
|
|
|
105
115
|
teammate's session goes out under that teammate's account. A cloud build
|
|
106
116
|
acts as the one account that owns its token: yours, or an account you
|
|
107
117
|
create for the team's builds
|
|
108
|
-
([
|
|
118
|
+
([Secrets](github/by-hand.md#secrets)).
|
|
109
119
|
- **Say who approves.** By default only the repository's owner can approve
|
|
110
120
|
a ticket for building or give a session instructions in a comment. List
|
|
111
121
|
the others under [`approvers`](configuration.md#approvers), _[Planned](developing.md#what-is-built)_.
|
|
@@ -134,5 +144,6 @@ and how to undo each. The short version:
|
|
|
134
144
|
sessions, not to your own terminal.
|
|
135
145
|
- Its CI workflows: one that checks the factory's files are in step, the
|
|
136
146
|
ones that run a session in the cloud, and one more for each optional part
|
|
137
|
-
you turn on.
|
|
147
|
+
you turn on. With a Dependabot configuration, two more complete
|
|
148
|
+
Dependabot's pull requests, the factory's own updates among them.
|
|
138
149
|
- Comments on tickets it works, and one "Follow-ups" ticket.
|