Have In-Document Errata

[msdemlei]

In DocStd 2.0, Errata are linked to from the document page, but the documents themselves are never touched. Now that (essentially) all active documents are in version control, we can to better.

Here's an attempt to sketch something that might work:

• Errata are taken off the wiki (existing errata remain there).
• Future errata consist of an issue and a PR, where the issue contains the current sections on rationale and impact assessment, while the content is in the PR.
• Issues for errata have an errata tag. Their identifiers are their github URIs (rather than our current identifiers).
• Errata are started by the acting editors. It is their responsiblity to announce it on the TCG list, the TCG coordination will link active errata from the TCG twiki page
• As in current practice, Errata are reviewed by the TCG
• Abandoned errata get their PR and Issue closed. No further trace will be left
• Accepted errata are merged into a branch -updated. They cause an entry in the in-document changelog, in a section called "Accepted Errata", where the version control issue is being linked
• The title page receives a new section "Errata applied", again giving version control links
• We bump a micro version: After the first Erratum is applied, it's m.m.1, then m.m.2, and so on
• For documents without acting editors, all this is up to the WG coordination.

I give you that brings us even deeper into github lock-in. But then we can probably write this in a way that lets us swap in a software management system (I'd like gittea) run "by us" if we have to flee github in a hurry.

[mcdittmar]

On the document update:

• Accepted errata are merged into a branch (major-version)-updated. They cause an entry in the in-document changelog, in a section called "Accepted Errata", where the version control issue is being linked

I'm not sure I follow 'merged into a branch -updated'.
Are you saying:

• Errata are documented as Git Issues (rather than on the twiki)
• Implemented on a branch from the associated release commit.
• PR generated (branch -> main) to be reviewed by TCG
• if approved, this branch is merged to main and a new Release tag with micro-version update is generated.

Questions/Comments:
Currently the TCG only reviews the erratum content. This outline indicates that the PR would include changes to the title page ( version, date ) and in-document change log as well. It might be better to move the title page updates to after TCG approval, so it could assign the approval date, and correct version number (in the rare event there are multiple errata for a document in play at the same time).

This would create a new REC with micro-version update.. without the Exec in the loop?

These micro-version updates live only in the Repo? not pushed to the D&S page or registered?
If that is the case, we still need something specific on the REC landing page for the errata. This currently traces to the twiki page which includes the description and actual change. In this workflow, that content is split between the Issue and the PR, which I think will not be as clear as the current one.

[msdemlei]

On Wed, Jun 17, 2026 at 07:19:49AM -0700, Mark Cresitello-Dittmar wrote: > Accepted errata are merged into a branch -updated. They cause an entry in the in-document changelog, in a section called "Accepted Errata", where the version control issue is being linked I'm not sure I follow 'merged into a branch -updated'.

Oh, that was a markup glitch (I think github swallowed by <major version>). What I meant is that errata to REC-1.1 will be applied in a long-lived branch 1.1-updated (or so).

Are you saying: - Errata are documented as Git Issues (rather than on the twiki)

Yes.

- Implemented on a branch from the associated release commit.

Yes.

- PR generated (branch -> main) to be reviewed by TCG

Not sure about technical details of where, say, PDFs to be reviewed should be kept. My hope would be that Errata can be reviewed as patches, frankly.

- if approved, this branch is merged to main and a new Release tag with micro-version update is generated.

No merges into main, no. Of course, many of the patches will end up in main, too, but in general I don't think errata commits would be mergeable into the current development version.

Currently the TCG only reviews the erratum content. This outline indicates that the PR would include changes to the title page ( version, date ) and in-document change log as well. It might be better to move the title page updates to after TCG approval, so it could assign the approval date, and correct version number (in the rare event there are multiple errata for a document in play at the same time).

Sure. The updates on the docrepo will only happen at commit time.

This would create a new REC with micro-version update.. without the Exec in the loop?

I'd keep the language from the existing DocStd for that matter: For each meeting of the Executive Committee, the TCG chair prepares a list of the errata passed since the last meeting of the Executive Committee with a summary of their history. The Executive Committee can withdraw an erratum with an explanation of the withdrawal reason. Such errata will be marked as rejected in the document repository, possibly with a reference to a superseding erratum. Since the Exec never canceled an Erratum so far, I don't think we need to plan for this eventuality. I'd do the docrepo upload immediately after TCG approval.

These micro-version updates live only in the Repo? not pushed to the D&S page or registered?

No, "repo" here doesn't mean git repo, but docrepo, i.e., <http://ivoa.net/documents/>. In contrast to minor versions, however, I'd say for the micro versions we indeed only show the latest version. Anyone interested in unpatched versions would have to go to the git repo and build these (I don't think there's a case for that except for editors and similar).