Skip to content

Commit fa9966e

Browse files
committed
docs(wiki): document choosing on the fleet, and fix the ORM members
The catalog page still listed the ORM group as `sequelize`, `prisma`. The bare `prisma` addon is gone as of 5.0.0 and the members are `pg-prisma`, `sequelize` — so the one table a reader consults before passing --packages named an id that now errors, and omitted the one it should reach for. Neither page mentioned that the four one-of-many choices now follow the fleet, which is the whole point of the release: an unexplained (recommended) marker that moves between runs reads as a bug. The VCS/CI table's bold value needed saying differently too — it is the fallback when there is no fleet to learn from, not a fixed default, and it is overridden non-interactively as well. The prompt transcript is copied from an actual run against a two-service Sequelize fleet, choice order included.
1 parent e11fa63 commit fa9966e

2 files changed

Lines changed: 55 additions & 3 deletions

File tree

‎wiki/Creating-Services.md‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,15 +15,28 @@ If omitted, `name` defaults to the current directory's name and `path` to `.`
1515

1616
Service creation is organized around four independent, pluggable axes, so you
1717
can mix the tools you actually use. Each resolves via the standard precedence
18-
(flag → `.imqrc.json` → global config → prompt → default).
18+
(flag → `.imqrc.json` → global config → fleet → prompt → default).
1919

20-
| Axis | Flag | Choices (default **bold**) |
20+
| Axis | Flag | Choices (fallback **bold**) |
2121
|---|---|---|
2222
| VCS host | `--vcs` | **github**, gitlab, bitbucket |
2323
| CI provider | `--ci` | **github-actions**, circleci, travis |
2424
| Container registry | `--registry` | **dockerhub**, google, aws-ecr, azure-acr |
2525
| Addon packages | `--packages` | (none) — see [Package Catalog](Package-Catalog) |
2626

27+
The bold value is the fallback, not a fixed default. With nothing configured,
28+
`imq service create` reads the git remotes and CI config of the services that
29+
already sit alongside the new one and proposes what they use — a service
30+
joining services hosted on GitLab is going on GitLab. The bold value applies
31+
when there is no fleet to learn from, or when the fleet does not agree with
32+
itself. [Package Catalog](Package-Catalog#following-the-fleet) describes the
33+
analysis and its cache.
34+
35+
A VCS host and a CI provider get picked either way — unlike an addon, choosing
36+
none is not an option — so this applies to non-interactive runs too. If you
37+
script `imq service create` inside a fleet and want a specific host or
38+
provider regardless of its neighbours, pass `--vcs` / `--ci` explicitly.
39+
2740
CI choices are filtered to those compatible with the selected VCS host. See
2841
[Providers](Providers) for the details and tokens each one needs.
2942

‎wiki/Package-Catalog.md‎

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,11 +27,13 @@ imq service packages --json # machine-readable
2727

2828
Packages belong to groups. **Exclusive** groups accept at most one member;
2929
selecting two members of the same exclusive group is rejected with an error.
30+
At most one, not exactly one — selecting none is a normal answer, and for a
31+
service that talks to no database it is the right one.
3032

3133
| Group | Exclusive? | Members |
3234
|---|---|---|
3335
| **Tracing / APM** | yes | `opentelemetry`, `dd-trace` |
34-
| **ORM / database** | yes | `sequelize`, `prisma` |
36+
| **ORM / database** | yes | `pg-prisma`, `sequelize` |
3537
| **Service features** | no | `pg-cache`, `pg-pubsub`, `tag-cache`, `job`, `net`, `http-protect`, `graphql-dependency`, `type-graphql-dependency` |
3638

3739
## What each addon does when selected
@@ -55,6 +57,43 @@ and you will get a multi-select for the feature group and single-selects for
5557
the exclusive groups. Non-interactive runs use your config/flags and never
5658
prompt.
5759

60+
Each exclusive list marks one member **(recommended)**, and `(none)` is always
61+
the first choice. The recommendation is `pg-prisma` for the ORM and
62+
`opentelemetry` for tracing — unless the fleet says otherwise.
63+
64+
### Following the fleet
65+
66+
`imq service create` looks at the directory the new service is being created
67+
into, and treats every sibling directory whose `package.json` depends on
68+
`@imqueue/rpc` as part of your fleet. If those services already agree on an
69+
ORM or a tracing backend, that member becomes both the preselected and the
70+
recommended one, with a line above the list saying why:
71+
72+
```
73+
? Select ORM / database:
74+
Only if the service uses a database — none is normal.
75+
Preselected sequelize to match 2 services in this fleet. Moving the fleet to
76+
pg-prisma is worth considering — as its own piece of work, not as part of this.
77+
(none)
78+
Prisma ORM + @imqueue/pg-prisma toolkit
79+
❯ Sequelize ORM + @imqueue/sequelize toolkit (recommended)
80+
```
81+
82+
A new service in an established fleet belongs on the fleet's stack: matching
83+
what is already there beats taking the default.
84+
85+
A fleet that disagrees with itself gets no proposal: with a strict majority the
86+
majority wins, and on a tie nothing is preselected and only the fallback is
87+
marked. The same analysis drives the VCS host and CI provider prompts — see
88+
[Creating Services](Creating-Services).
89+
90+
Scanning is cheap but not free, so the result is cached in
91+
`~/.imq/var/fleet.json`, keyed by directory (`IMQ_CLI_HOME` relocates it with
92+
the rest of the CLI's files). The cache is invalidated when the set of sibling
93+
directories changes. Choosing against the analysis is taken as intent: your
94+
choice is recorded as an override for that directory and proposed next time,
95+
until a later scan agrees with it on its own.
96+
5897
## Extending the catalog
5998

6099
Because the catalog is data, you can publish new addons by editing

0 commit comments

Comments
 (0)