Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
26 changes: 26 additions & 0 deletions openspec/changes/document-system-architecture/design.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,3 +155,29 @@ rule to a directory named `examples/`. Rejected — the property that matters is
whether the directive crosses a repository boundary, and a rule written against
a directory name would miss a nested tool module and would not survive anyone
choosing a different name.

## The module path was not the only wrong home

Renaming the module surfaced two more declarations naming `retr0h`, neither of
them a module path and neither reachable by the requirement that governs one:

- `docs/docusaurus.config.ts` sets `organizationName: 'retr0h'` three lines
below `url: 'https://osapi-io.github.io/'`. The file contradicts itself, and
the site publishes anyway.
- `contributing.md` links Discussions to `retr0h/go-gilt` — not a former owner
of this repository, but a different project entirely, carried in by whatever
the file was copied from.

A wrong module path fails loudly: the toolchain cannot resolve it. These fail
quietly — the build passes, the site deploys, and the link lands on somebody
else's project. That asymmetry is the reason to state the requirement in terms
of where a repository says it lives rather than in terms of Go modules.

Attribution is excluded. `@retr0h` as a document's author, `NOTE(retr0h)` in a
comment, and the `retr0h` entry in `repos.json` branch protection all name a
person, and a person does not move when a repository does.

*Alternative considered:* fold these into `correct-documentation-drift` under "a
cross-reference resolves to what it names". Rejected for the Docusaurus setting
— a deployment config is not a cross-reference, and stretching that requirement
to cover it would make it mean any wrong string anywhere.
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,35 @@ A Go module SHALL declare a path matching the repository that holds it.
- **THEN** its module path is updated to match, and consumers are updated in the
same change

### Requirement: A repository's declared home matches where it lives

A repository SHALL NOT name an owner, project, or location other than its own.
This covers every place the repository states where it lives — the module path,
site deployment configuration, and links to the project's own issue tracker,
discussions, or releases.

A module path is checked by the toolchain and fails loudly when wrong. These
other declarations fail quietly: the build passes, the site publishes, and the
link resolves to somebody else's project.

#### Scenario: A repository moves between owners

- **WHEN** a repository moves to a different organization
- **THEN** every declaration of where it lives is updated, not only the ones a
compiler checks

#### Scenario: Site deployment names a different organization

- **WHEN** a documentation site declares the organization it deploys under
- **THEN** that organization is the one hosting it, rather than a former owner
the published URL contradicts

#### Scenario: A link points at the author's other project

- **WHEN** documentation links to the project's issue tracker, discussions, or
releases
- **THEN** the link names this repository, not one it was copied from

### Requirement: Dependencies are declared by version

A repository SHALL depend on another repository by a released or pinned version
Expand Down
10 changes: 10 additions & 0 deletions openspec/changes/document-system-architecture/tasks.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,14 +19,24 @@ Sequenced: `osapi` renames and publishes before `osapi-orchestrator` moves.

- [ ] 3.1 `gohai` — describe the consumer relationship it has, not the one
intended

- [ ] 3.2 Confirm no repository documents a `replace`-based linkage

- [ ] 3.3 Confirm no `go.mod` contains a `replace` directive pointing outside
its own repository

- [ ] 3.4 `osapi` — `docs/docusaurus.config.ts` declares
`organizationName: 'retr0h'` three lines below `url: 'osapi-io.github.io'`

- [ ] 3.5 `osapi` — `contributing.md` links Discussions to `retr0h/go-gilt`, a
different project

## 4. Verification

- [ ] 4.1 Confirm every module path matches its repository location
- [ ] 4.2 Confirm every `replace` directive points within the repository that
holds it
- [ ] 4.3 Confirm every documented dependency appears in the corresponding
`go.mod`
- [ ] 4.4 Confirm no repository names an owner or project other than its own,
excluding attribution of a person