Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
6905010
docs(adr): propose ADRs 0032 and 0033 for the rename to Wyrm's Hoard …
plainprogrammer Nov 15, 2026
25ef096
docs(specs): PRD for spec 092, rename the application to Wyrm's Hoard…
plainprogrammer Nov 15, 2026
70658bc
docs(specs): PRD 092 after the third review: the guard reads code, no…
plainprogrammer Nov 15, 2026
2bb6ca6
docs(specs): PRD 092 after the fourth review: comments first, documen…
plainprogrammer Nov 15, 2026
860aa04
docs(specs): PRD 092 after the fifth review: the comments-first PR co…
plainprogrammer Nov 15, 2026
e549772
docs(adr): accept ADRs 0032 and 0033 (the maintainer, 2026-11-14, wit…
plainprogrammer Nov 15, 2026
be74f81
docs(specs): spec 092 v0.1.0, rename the application to Wyrm's Hoard …
plainprogrammer Nov 15, 2026
c02485a
docs(specs): spec 092 v0.2.0, spec review round 1 fixed (#434)
plainprogrammer Nov 15, 2026
4420d87
docs(specs): spec 092 v0.3.0, spec review round 2 fixed (#434)
plainprogrammer Nov 15, 2026
45a573d
docs(specs): spec 092 v0.3.1, the maintainer's rulings recorded (#434)
plainprogrammer Nov 15, 2026
bc2fe9e
docs(specs): spec 092 v0.4.0, spec review round 3 fixed (#434)
plainprogrammer Nov 15, 2026
0151eca
docs(specs): spec 092 v0.5.0, the maintainer's rulings on decisions 7…
plainprogrammer Nov 15, 2026
b214eb0
docs(specs): spec 092 v0.6.0, spec review round 4 fixed; the check is…
plainprogrammer Nov 15, 2026
13bc8fa
docs(specs): spec 092 approved (the maintainer, 2026-11-14, v0.6.0) (…
plainprogrammer Nov 15, 2026
8156330
docs(specs): plan for spec 092, approved by the maintainer after two …
plainprogrammer Nov 15, 2026
8c2432e
Merge remote-tracking branch 'origin/main' into 092-rename-to-wyrms-h…
plainprogrammer Nov 15, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions docs/adr/0032-the-rename-is-a-clean-break.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# 0032: The rename to Wyrm's Hoard is a clean break: one spelling per context, no aliases, and the export identifier stays

## Status

Accepted (2026-11-14; the maintainer, with the PRD of spec 092, after five read-only reviews). Written as Proposed. Written with the PRD of spec 092; the maintainer chose each option below in the brainstorm of 2026-11-14 ([#433](https://github.com/plainprogrammer/Collector/issues/433), [#434](https://github.com/plainprogrammer/Collector/issues/434)).

**Date:** 2026-11-14
**Feature:** 092-rename-to-wyrms-hoard

## Context

The application's name changes from Collector to Wyrm's Hoard, and its repository from `plainprogrammer/Collector` to `plainprogrammer/wyrmshoard`. The old name is in four kinds of place (on `main` at `50435ba3`, about 950 tracked files contain it in any case, by `git grep -il collector`):

- **The display name:** page titles (`… · Collector`), the footer, `README.md`, the image's description.
- **Internal code:** `module Collector` and `Collector::…` (about 330 uses), `lib/collector/`, `spec/lib/collector/`, the asset directories `app/assets/{stylesheets,fonts,images}/collector/`.
- **The operator contract:** the `COLLECTOR_*` environment variables and build arguments (19 in code, 7 of them developer-only), the command `bin/rails "collector:user[EMAIL]"` (`lib/tasks/collector.rake`), the Compose volume `collector_storage`, Kamal's `service: collector`, backup files named `collector-backup-<time>.tar.gz`. A renamed setting that an operator doesn't also rename is silently ignored, and a renamed volume starts the application on an empty one.
- **The data contract:** every export file begins with `"format": "collector-export"`, and the four schemas are identified as `urn:collector:export-format:v1` to `v4` (`ExportFormat::Rules::FORMAT`, `app/models/export_format/`).

One released migration, `db/migrate/20261103100002_set_account_currency_from_the_instance.rb`, reads `COLLECTOR_CURRENCY` to set each account's currency. It first shipped in 0.3.0, and a released migration is never edited (`.claude/rules/sqlite-and-migrations.md`).

The same letters also name things that are not the application: `collector_number`, `collector_text` and `collector_line` are a card's printed collector line and what the scanner reads of it, "a collector" is the documentation's and the interface's word for a person who uses the application, and `collector?` is the view helper that asks whether one is signed in.

The display name has an apostrophe and a space, so every machine-facing place needs a derived spelling. The maintainer fixed one: the repository is `wyrmshoard`.

Foundation principle 1 asks that every release upgrade in place, and principle 2 that users own their data. Releases 0.1.0 to 0.3.0 are published. The maintainer stated on 2026-11-14 that no instance other than their own runs the application.

## Options considered

**For existing instances (the operator contract):**

- **A. A clean break (chosen).** One release renames every setting, the volume and the service; no old name is read. Upgrade notes list what to change by hand. Costs: the upgrade from 0.3.0 is not unattended, which principle 1 would otherwise ask for.
- **B. Old names keep working for a release or more, with a deprecation notice.** The upgrade stays unattended, at the cost of an alias layer for every setting, its tests, and a later release that removes it, for an audience of one instance whose operator is the maintainer. Not chosen.
- **C. Old names keep working until 1.0 or indefinitely.** Right if unknown operators existed; the maintainer says none do. Not chosen.

**For the spelling in code and configuration:**

- **A. Two words, by Rails' default inflection (chosen):** `WyrmsHoard`, `wyrms_hoard`, `WYRMS_HOARD_`, `wyrms-hoard`; the repository and the image stay `wyrmshoard`. Costs: two lowercase spellings exist, so a search for one misses the other.
- **B. One token with an inflector acronym:** `wyrmshoard` everywhere lowercase and `WyrmsHoard` as the constant, through `inflect.acronym "WyrmsHoard"`, as `MTG` is. One lowercase spelling, at the cost of an inflection rule a reader must know. Not chosen.
- **C. One token, plain constant:** `Wyrmshoard`. No rule to know, but the constant reads as one word. Not chosen.

**For the export identifier:**

- **A. Keep `collector-export` and the `urn:collector:…` schema ids (chosen).** It reads as "a collector's export", the word the application keeps for its users, so it is not a leftover of the old name. No format version changes and every existing file stays valid.
- **B. Rename it as format version 5,** identical to version 4 but for the identifier, with versions 1 to 4 still read under the old one. A schema, a document section and import tests for a change that carries no data. Not chosen.
- **C. Rename it and stop reading old files.** Breaks principle 2 for every file already downloaded. Not chosen.

## Decision

1. **The rename is a clean break.** From the release that carries it (0.4.0), the running application reads no `COLLECTOR_*` variable (decision 7 is the one exception), has no `collector:user` task, mounts no `collector_storage` volume by default and is no Kamal service named `collector`. No alias, fallback or deprecation notice is written. The release ships upgrade notes that name each renamed setting, the volume and the service, and say how to move the data.
2. **One spelling per context:**

| Context | Spelling |
|---|---|
| Display (titles, prose, the image's description) | Wyrm's Hoard |
| Ruby constants | `WyrmsHoard` |
| File and directory names, Ruby identifiers, the rake namespace, the Compose volume | `wyrms_hoard` |
| Environment variables and build arguments | `WYRMS_HOARD_` |
| Hyphenated names (Kamal's service, backup files, a User-Agent) | `wyrms-hoard` |
| The repository and the image, and nothing else | `wyrmshoard` |

No inflection rule is added.
3. **What names the person or the card's collector line stays:** "a collector" in prose and interface copy, the `collector?` helper, and `collector_number`, `collector_text`, `collector_line` and their kin. The `c-` prefix of the design system's classes stays too; it is a prefix, not the name.
4. **The export identifier stays `collector-export`,** with its `urn:collector:export-format:vN` schema ids and the download's file name `collector-export-<date>.json`, and the format's version stays 4. Only the prose of the format's document and the schemas' titles and descriptions say Wyrm's Hoard.
5. **Data made before the rename is still read.** A backup made by an earlier release restores under the new one (restore judges a file by its contents, never its name's prefix), and every export of versions 1 to 4 imports as before.
6. **Shipped specs and accepted ADRs are not edited** (`.claude/rules/documentation.md`); they keep the old name as the record of their time.
7. **The released currency migration keeps reading `COLLECTOR_CURRENCY`.** It is not edited. An instance on 0.3.0 has already run it, so the rename changes nothing for it. An instance older than 0.3.0 that went straight to 0.4.0 with only the new setting would run it with the default, USD; the upgrade notes therefore say to upgrade to 0.3.0 first.

## Consequences

- **Good:** no alias layer exists to test, document or remove later, and after the release a search for the old name finds only what decisions 3, 4, 6 and 7 leave, the old backup prefix where old data is still read, the upgrade proof's rules for 0.3.0 ([ADR 0033](0033-the-image-moves-to-a-new-package.md)) and `spikes/`.
- **Cost:** the upgrade from 0.3.0 to 0.4.0 needs an operator: rename the settings, copy the volume (Docker has no volume rename) and, under Kamal, move to the new service. An operator who upgrades without the notes gets an instance on an empty volume with default settings; the old volume is untouched, so nothing is lost, but nothing warns them. This is an accepted exception to principle 1, taken because the only instance is the maintainer's.
- **Cost:** the upgrade proof (`bin/upgrade-smoke`, spec 031) must drive this one upgrade across the rename; spec 092 says how, and [ADR 0033](0033-the-image-moves-to-a-new-package.md) covers where it pulls the previous release from.
- **Limit:** two lowercase spellings (`wyrms_hoard`, `wyrmshoard`) and one hyphenated one exist. A guard against the old name is cheap; a wrong new spelling is for review to catch.
- **Limit:** if an unknown operator does exist, decision 1 breaks their upgrade. The upgrade notes are the only mitigation.
- **Follow-up:** the old name remains in shipped specs, accepted ADRs, the export identifier and the old image; a reader who finds it there is reading history or decision 4, not an omission.
44 changes: 44 additions & 0 deletions docs/adr/0033-the-image-moves-to-a-new-package.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
# 0033: The image moves to a new package, `ghcr.io/plainprogrammer/wyrmshoard`, with new releases only; the old package stays frozen

## Status

Accepted (2026-11-14; the maintainer, with the PRD of spec 092, after five read-only reviews). Written as Proposed. Written with the PRD of spec 092; the maintainer chose the option below in the brainstorm of 2026-11-14 ([#433](https://github.com/plainprogrammer/Collector/issues/433), [#434](https://github.com/plainprogrammer/Collector/issues/434)). It supersedes one consequence of [ADR 0008](0008-public-images-from-the-private-repository.md), and nothing else of it: that the package name `ghcr.io/plainprogrammer/collector` is a public contract. From release 0.4.0 the contract is the new name.

**Date:** 2026-11-14
**Feature:** 092-rename-to-wyrms-hoard

## Context

The application is renamed to Wyrm's Hoard and its repository to `plainprogrammer/wyrmshoard` ([ADR 0032](0032-the-rename-is-a-clean-break.md)). Its images are published at `ghcr.io/plainprogrammer/collector`: the releases 0.1.0, 0.2.0, 0.2.1 and 0.3.0 with their channel tags, and `edge` from `main` (ADR 0009).

Facts that bound the choice:

- GitHub redirects a renamed repository's URLs. A container package's name is not the repository's and is not redirected: a package under the new name is a new package, and pulls of the old name keep reading the old one.
- The image name is written in `ci.yml` (`IMAGE`), `compose.yaml`, `config/deploy.yml`, the cleanup script and its workflow (`lib/collector/ghcr_cleanup.rb`, `.github/workflows/ghcr-cleanup.yml`), the upgrade proof (`script/upgrade/harness.rb`, `REPOSITORY`) and the documentation.
- The upgrade proof boots the previous release's published image (spec 031). For release 0.4.0 the previous release is 0.3.0, which exists only under the old name.
- The first push to a new package name creates the package. A package's visibility is its own setting, so the new one has to be checked, and made public if it isn't, before anyone can pull it without credentials (ADR 0008 did this once for the old package). The repository is public now, so the new package may be public from its first push.
- The maintainer's is the only instance (ADR 0032, Context).

## Options considered

- **A. New releases only; the old package stays frozen (chosen).** Nothing is copied. The new package starts with `edge` from the first `main` build that names it, and its first release is 0.4.0. The old package is left as it is and nothing is pushed to it again. Costs: releases up to 0.3.0 can be pulled only by the old name, and the upgrade proof needs to know which package holds a given release.
- **B. Copy the release tags to the new package by digest, then delete the old package.** One package and one name in the proof, at the cost of a copy step that must be verified per tag and architecture, a delete that can't be undone, and images under the new name that call themselves Collector inside. Not chosen.
- **C. Copy the release tags and keep the old package.** As B without the delete; two packages hold the same images. Not chosen.

## Decision

1. **The image is `ghcr.io/plainprogrammer/wyrmshoard`** from the first build of `main` that names the new image. Everything that names the image names the new one.
2. **No existing image is copied, rebuilt or retagged.** The new package's first release is 0.4.0.
3. **The old package, `ghcr.io/plainprogrammer/collector`, is frozen:** nothing pushes to it, nothing deletes from it, and the weekly cleanup works on the new package only. Its `latest` stays 0.3.0 and its `edge` stays the last build before the rename.
4. **The upgrade proof pulls a release of 0.3.0 or earlier from the old package and any later release from the new one.** The rule is written once, beside the proof's repository constant and its `UPGRADE_IMAGE_REPOSITORY` override, with this ADR as its source.
5. **The new package is public before 0.4.0 is tagged.** Checking it is a step of the release: an anonymous pull, and if that fails the maintainer makes the package public in its settings.

## Consequences

- **Good:** the rename needs no registry operation beyond the builds CI already does, and nothing irreversible happens to published images.
- **Good:** the old package keeps answering the pull commands in release 0.3.0's own documentation.
- **Cost:** the upgrade proof carries a rule about two packages for as long as it can be asked to start from 0.3.0 or earlier; it is the one place in the code that still names the old image.
- **Cost:** an operator on the old image who follows `latest` stays on 0.3.0 with no notice. Accepted: the only operator is the maintainer (ADR 0032).
- **Limit:** the old package's untagged versions are no longer cleaned up. Their number can't grow, since nothing pushes there.
- **Follow-up:** deleting the old package later is a separate decision; when it is taken, decision 4 goes with it.
- **Follow-up:** ADR 0008's note to revisit attestations once the repository is public is unchanged by this ADR.
4 changes: 3 additions & 1 deletion docs/adr/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@ Add a line here with each new ADR. All are Accepted unless the line says otherwi
- [0030](0030-a-household-is-a-group-of-accounts.md): A household is a group of accounts; an account stays the unit of ownership and privacy
- [0018](0018-collectible-agnostic-catalog-core.md): A collectible-agnostic catalog core with per-type extensions
- [0019](0019-lot-as-the-unit-of-ownership.md): The lot is the unit of ownership
- [0032](0032-the-rename-is-a-clean-break.md): The rename to Wyrm's Hoard is a clean break: one spelling per context, no aliases, and the export identifier stays

### Card scanner

Expand All @@ -39,10 +40,11 @@ Add a line here with each new ADR. All are Accepted unless the line says otherwi

### Images and publishing

- [0008](0008-public-images-from-the-private-repository.md): Publish public container images from the private repository
- [0008](0008-public-images-from-the-private-repository.md): Publish public container images from the private repository (the package name as a public contract superseded by 0033)
- [0009](0009-image-tags-and-release-channels.md): Image tags and release channels
- [0010](0010-native-multi-architecture-image-builds.md): Native multi-architecture image builds
- [0011](0011-own-ghcr-cleanup-script.md): Own script for GHCR untagged-version cleanup
- [0033](0033-the-image-moves-to-a-new-package.md): The image moves to a new package, `ghcr.io/plainprogrammer/wyrmshoard`, with new releases only; the old package stays frozen
- [0013](0013-active-storage-variants-with-vips.md): Process Active Storage variants with libvips through `ruby-vips`

### Admin
Expand Down
Loading
Loading