Renumbering a document
- Comparing
- v1 to v2
- Current
- Read the document
Abstract
A command that changes a numbered document's identifier and follows every reference to it, refusing wherever a frozen document would be left pointing at a file that no longer exists.
Motivation
archdoc new takes the next free number at the moment it runs. Two contributors branching from the same commit both receive the same one, and after both merge two documents carry it. Lint reports the collision. Repairing it means editing the filename, the front matter id and the H1, and doing two of the three trades one lint error for another. The same three-place edit is needed to fix a slug typed wrong at creation.
Proposal
Concepts
| Concept | Meaning |
|---|---|
| Selector | An identifier or a document path naming the document to renumber |
| Target | The identifier to take, or the next free number when none is given |
| Reference | Any place the old identifier appears: a front matter list, a wiki link, a link destination |
Components
| Component | Responsibility |
|---|---|
repo.Renumber |
Finds every reference, checks nothing frozen is involved, then rewrites |
repo.ParseIdentifier |
Reads an identifier back into its type and number |
archdoc renumber |
Resolves the selector, builds the frozen predicate, prints the result |
Steps
- Resolve the selector. A path resolves directly. An identifier carried by exactly one document resolves to it. An identifier carried by more than one document is refused, naming every candidate.
- Refuse if the document is frozen, as ADR-0001 requires.
- Resolve the target. With none given, take one greater than the highest number of the type. With one given, it must be an identifier of the same type, not already used, and within the 9999 bound.
- Find every document referencing the old identifier: in
depends,updates,obsoletesandincludes; as[[<id>]]; and as a link destination naming the old file. Refuse if any of them is frozen, naming it. - Rewrite the document's
idand its H1, and rewrite each reference found. - Write the document at its new path, keeping the slug, and remove the old file.
- Print each path changed and note that the index is not regenerated.
Nothing is written until step 5, so a refusal leaves every file as it was.
Rules
| Rule | Reason stated in the design |
|---|---|
| A path is accepted as well as an identifier | During a collision the identifier names two documents |
| The slug is kept | The number is the identity; the slug is for people |
| The type cannot change | The directory and the required sections follow the type |
| References in editable documents are rewritten; a frozen referrer refuses the whole operation | A reference in a frozen document could never be corrected |
| Bare mentions in prose are left alone | Rewriting a sentence is not this command's business |
Output
rfc/0002-alice.md -> rfc/0003-alice.md
the index is now out of date; run archdoc index
Errors
| Condition | Message names |
|---|---|
| No document has the identifier | the identifier |
| More than one document has it | every candidate path, and that a path must be given |
| The document is frozen | the identifier |
| A frozen document references it | each such document |
| The target is taken | the document holding it |
| The target is of another type | both types |
| The target is beyond 9999 | the bound |
Out of scope
- Regenerating the index.
archdoc indexdoes that, and the command says so. - Rewriting a bare identifier in prose. Not a reference the tooling defines.
Alternatives considered
This design rests on ADR-0001, which is why a frozen document and a frozen referrer are refused, and on ADR-0002, which is why the filename is the thing renamed and the slug kept.
- A numberless draft, numbered by an action at merge. Lint would have to stop requiring
idto match the filename, and the filename to fit the grammar, for every document in every repository. A numberless document could be neither linked to nor indexed, and the numbering would happen after review. - A
proposals/directory for contributions. Discovery is by a fixed list of directories, so nothing in it would be examined by any rule. A contributor's document would pass CI with its sections missing and its links unresolved.
No other alternatives were weighed.
Backwards compatibility
Nothing breaks. The command is new.
Open questions
Changelog
Sources
- 7e1686e adds the command and sets
createdanddecided. Its message states the collision and the three-place edit. docs/ARCHDOC.mdat 7e1686ea, sectionarchdoc renumber, describes the command including the ambiguous-identifier refusal.- The alternatives were weighed in a design session on , not publicly available, and first written down on .
Source rfc/0002-renumbering-a-document.md · commit fd11f56 · published