Review of the 'Changes since REC-1.0' appendix.

[nxg]

I believe this now matches all of the significant changes in the git change log. It also makes an explicit reference to GitHub (but with an ‘as of 2023’ in case we move from there, and to implicitly acknowledge that the issues list is not in any sense normative).

[nxg]

I'm also somewhat uncomfortable with any explicit GitHub link. I'm not sure who first added explicit mentions of issues in this list (probably me, come to think of it, but I'm not sure), but only as ‘GitHub issue X’ with no further context: the motivation for the edit was to add some sort of acknowledgement that GitHub is external and in principle transient, and the result here is several second thoughts later.

It seems vaguely useful to point to the log of GitHub discussions, if only to provide background when someone says ‘such-and-such a decision is obviously stupid!’ But I wouldn't shed much of a tear if the decision was made to remove mention of them. If it seems useful to keep them, then perhaps putting the paragraph after the list and rephrasing it as below?

Problem reports for the REC-1.0 document were tracked on GitHub; the issue numbers quoted below refer to an issues list there. The issues were discussed on that site, on IVOA mailing lists, and at Interops. This list is now of historical interest only, but as of late 2023 was still visible at https://github.com/ivoa-std/VOUnits/issues

I feel we should either add context such as this, or completely remove mention of GitHub from the list. Writing this, it also occurs to me that since Zenodo will mint you a DOI for a GitHub repo, there's at least some not-entirely-comfortable-with-it precedent to regarding GitHub as a long-term resource in science.

As a tangent: do we still need the 'Changes before REC-1.0' section?

I've added a link to sec:scalingprefixes.

[nxg]

As I was writing the comment above, I see that Tom posted a call for review of VOTable 1.5 WD, where he mentions

The changes since version 1.4 were all made via Github pull requests. Some of these PRs contain useful discussion of the details so can be a useful reference for the ongoing Working Draft discussion. The complete list of PRs included in this working draft can be found here: https://github.com/ivoa-std/VOTable/pulls?q=is%3Apr+is%3Aclosed+milestone%3Av1.5

There may be a larger procedural question here (which I may resist having strong opinions about).

[mbtaylor]

Looks like it was you who added those github issue references (git blame). I agree if they're in there, the additional context should be present as well. If it's good enough for VOTable maybe it's good enough for VOUnits...

[molinaro-m]

I'm a bit worried of having github references in final documents. But the border line should be discussed elsewhere, probably.

I only add a caveat: the snippet from Tom's email is an email only, not in the VOTable version history.

[msdemlei]

On Thu, Sep 14, 2023 at 03:56:09AM -0700, Mark Taylor wrote:

think(?) this is common practice in other IVOA standards. What does @msdemlei think?

Me, I'm rather convinced that if we reference the VCS in change logs, it should be git commit ids (the first 8 characters of the SHA1 hash). That exists independently of any particular platform and will work as long as we're using git (which I forsee will be a long while).

When there's notable off-list discussion on something, the commit message can reference a github PR (or even better, it could contain a summary of that discussion), but something as ephemeral as a github PR should IMHO never be in an IVOA document. The Twitter story should caution us that all these platforms will eventually fail (us), and github PRs (as opposed to commit IDs) are a platform feature.

Which is of course why it'd generally be preferable if more discussions went back to the mailing lists...

[nxg]

Fair enough. So the conclusion is that we/I remove the references to issues from Appx.D.1, yes? For at least some of them, there will be a commit ID which can be straightforwardly associated with the change, which can be added as a replacement. Or just drop the cross-reference entirely?

Any thoughts about removing Appx.D.2 as being of only distractingly historical interest?

[mbtaylor]

I'd drop the references to git/github altogether. In the cases where there are illuminating discussions they tend to be in the issues rather than the commit messages, and people can look at the revision history if they want to anyway.

I would also be happy to see Appendix D.2 disappear at this version, I don't think it provides useful information to the reader.

[nxg]

I've removed the mention of issues, and simply mentioned, as a point of history, that this revision was managed on GitHub. If anyone interested in the archaeology of the document, that's enough of a hint as to where further discussion may be found.

I'm not fond of GitHub (third-party-ness, transience, being Microsoft). But if we collectively overcame our distaste, to the extent of using it in fact, then I feel it's proper to own up to that. I am of course happy to be out-voted here, though, so fire away.

Thinking back (and possibly this is something that should be taken up on a list), I suspect the reason I originally added the issue references was in continued imitation of the W3C process, which did log changes against issues logged in a W3C-hosted service. Something like GitHub probably works better for detailed document changes than an email list, which, though I also tend to prefer in general, makes it too easy to lose track of discussions. I think I've said before that the good thing about GitHub is the 'Hub'.