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:
- Publish an unversioned Git definition using
docs_path: docs.
- Change its
docs_path or add an exclude_paths rule without changing the upstream Git commit.
- Run publication again.
- 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.
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:source_commit.A concrete case to cover:
docs_path: docs.docs_pathor add anexclude_pathsrule without changing the upstream Git commit.source_commitcauses 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:
docs_path, exclusions, source selection, or the ingestion revision invalidates the previous fingerprint.This is about derived package freshness, independently of any raw-download cache.