Skip to content

[Feature] Keep the workspace and catalog versions in fewer places #346

Description

@LeeroyHannigan

Problem or use case

Two version numbers are spelled out by hand in many places, and bumping either one touches far more files than its source of truth.

Workspace version (0.1.11), source of truth Cargo.toml:

Where Copies What keeps it right today
Cargo.toml [workspace.package] 1 the source
packaging/npm/package.json (package version plus five platform-package pins) 6 nothing compares it to Cargo.toml
SOFTWARE-LICENSE-NOTICES.html, -DEV.html, -MONGODB.html 10 each generated by cargo-about, committed; notices-current fails when stale
docs/getting-started.md, docs/manuals/04-quickstart-setup-guide.md 3 crates/storage-postgres/tests/doc_version_literals.rs fails on drift

Catalog version (0.0.4):

Where Copies
crates/storage-postgres/src/lib.rs and crates/storage-sqlite/src/schema.rs, one constant each 2
SQLite SCHEMA_SQL seed literal; PostgreSQL migration closing UPDATE settings 2
Six manual and getting-started pages (sample output) 9 live, 6 historical in the upgrade manual
tests/test_cli_vector_catalog_migration.py 6

The most recent catalog bump touched twelve files, two of which were the constants. The tripwire tests catch drift, but they do so by making each bump larger rather than smaller. The thirty version strings in the three notices files are the workspace's own extenddb-* crates, so every workspace bump regenerates three committed files and notices-current fails until someone does it (#271, #272, #341 are all this).

Proposed solution

In order of payoff:

  1. Exclude workspace member crates from the generated third-party notices. They are Apache-2.0 first-party code, not third-party notices. After this a workspace bump produces no notices diff. Needs the mechanism the pinned cargo-about offers for ignoring workspace or private crates, or a filter in about.hbs; a rule ("workspace members") is preferable to a name list.
  2. One catalog constant in extenddb-core, used by both backends. The SQLite seed writes the version with a parameterised upsert after the schema is applied instead of a literal inside SCHEMA_SQL. The PostgreSQL migrator writes the version from Rust after sqlx::migrate! completes, so future migration files stop carrying an UPDATE settings. Existing migration files are not edited (sqlx checksums applied migrations); the UPDATE in 003 stays and is harmless. The tripwire tests move from "literal equals constant" to "catalog reads the constant back".
  3. tests/test_cli_vector_catalog_migration.py reads the expected catalog version from extenddb version output instead of six literals.
  4. A check that packaging/npm/package.json matches Cargo.toml, or generating its six version fields at publish time in the npm workflow.
  5. Reduce the sample-output blocks that print versions to one per document, keeping doc_version_literals.rs for what remains.

After 1 and 2 a workspace bump is Cargo.toml plus one documentation block, and a catalog bump is one constant plus one documentation block.

Alternatives considered

  • Keep the current layout and rely on the tripwire tests. They work, but they enforce consistency by forcing every bump to touch every copy, which is the complaint.
  • Generate the notices files at release time instead of committing them. Rejected earlier ( Fixes IAM condition evaluation for multivalued condition keys #271, chore(licenses): regenerate notices for 0.1.6 #272): the committed files are what notices-current checks on every pull request so main never becomes unreleasable.
  • A single VERSION file read by everything. Cargo already owns the workspace version and cargo-about reads Cargo metadata, so a second file would add a copy rather than remove one.

DynamoDB API reference

Not applicable; build and release tooling only.

Additional context

Item 2 has one hard constraint: never edit an applied PostgreSQL migration file. The change has to go into the migrator, not into migrations/001 through 003.

Checklist

  • I have searched existing issues and the roadmap for duplicates
  • I have described the use case, not just the desired implementation

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions