Skip to content

Rebuild documentation when its definition or ingestion pipeline changes #144

Description

@TheRealBecks

Publication freshness checks currently consider the source release or Git commit, but not the definition or ingestion pipeline that produced the documentation package. As a result, fixes to parsers, docs_path, or exclusions can leave an already-published package unchanged.

At upstream commit 149f112:

A concrete case to cover:

  1. Publish an unversioned Git definition using docs_path: docs.
  2. Change its docs_path or add an exclude_paths rule without changing the upstream Git commit.
  3. Run publication again.
  4. The unchanged source_commit causes a skip, although the expected package content has changed.

The same issue affects parser fixes: the source documentation need not change for its indexed representation to need rebuilding. For example, the filename-filtering work in #125 and HTML conversion work in #137 can affect existing packages.

Proposed behavior:

Record a deterministic build fingerprint containing the resolved source revision, the definition fields that affect output, and an explicit ingestion/package-format revision. Use it when deciding whether an artifact is current.

Also provide an explicit rebuild path with documented publication semantics. Versioned packages need a deliberate policy for artifact revisions or replacement: the registry API specification permits servers to reject overwrites with HTTP 409, so rebuilding locally must not silently assume that every server accepts replacement uploads.

Acceptance criteria:

  • Identical relevant inputs still skip unnecessary work.
  • Changing docs_path, exclusions, source selection, or the ingestion revision invalidates the previous fingerprint.
  • Definition serialization/order differences alone do not trigger a rebuild.
  • Packages and servers without fingerprint metadata have a documented backward-compatible behavior.
  • An explicit rebuild command or flag reports publication conflicts clearly.
  • Tests cover both unchanged-source Git packages and already-published explicit versions.

This is about derived package freshness, independently of any raw-download cache.

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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions