search

ivoa-std / ProvenanceDM

Provenance Data Model
Creative Commons Attribution Share Alike 4.0 International
3 stars 3 forks source link

Mark document releases in the repository #4

Open olebole opened 3 years ago

olebole commented 3 years ago

During its evolution, ProvenanceDM issues a number of Internal Drafts, Working Drafts, Proposed Recommendations, and an official release. They should be marked in the repository. I already tagged them in my fork:

Version Type
v0.1_20141008 Internal draft
v0.2_20160428 Internal draft
v1.0_20161121-wd Working Draft
v1.0_20170514-wd Working Draft
v1.0_20170921-wd Working Draft
v1.0_20180530-wd Working Draft
v1.0_20181015-pr Proposed Recommendation
v1.0_20190614-wd Working Draft
v1.0_20190719-pr Proposed Recommendation
v1.0_20191125-pr Proposed Recommendation
v1.0_20191214-pr Proposed Recommendation
v1.0 Final Release

I volunteer to do both tagging and adding the PDFs to the official repository. From https://github.com/ivoa-std/ProvenanceDM/pull/1#issuecomment-705602463, it may be useful to add changelog entries to the release text, which I would volunteer to do as well if the discussion here results in that.

lmichel commented 3 years ago

Ole, 1- The PDFs are note supposed to be in the repo. 2- I've nothing against reporting the former tags if the authors agree.

olebole commented 3 years ago

@lmichel

1- The PDFs are note supposed to be in the repo.

The PDFs would be not in the repository, but attached as assets to the releases. This way interested people can directly download them. A similar (automated) was is done with the "Auto PDF preview", like here for the latest commit.

You won't get them with git clone. It is just to make the work more comfortable.

2- I've nothing against reporting the former tags if the authors agree.

I don't see why this needs agreement of the authors; it does not change anything of the document. It just tags the previous releases.

@mservillat what is your opinion here?

olebole commented 3 years ago

Pinging @mservillat - this issue is now more than 4 months old. How to proceed here?

lmichel commented 3 years ago
olebole commented 3 years ago

Again, this is not about having the assets in the Git repository. There is no Release folder in the repository, there is a Tags (resp. "Releases") tab on the Github web page; see my fork as an example. And as you clearly see, the current REC is highlighted as "latest" on the main page, so this will not confuse people. When listing all releases, pre-releases (llike PR, WD, or internal drafts) are clearly marked as such, and the PDFs are attached to the individual (pre-) releases and to a general "Release" folder. Having the PDFs there makes it comfortable for people wanting to check older pre-releases, and I don't see why they would confuse people more than on the Wiki page. Especially as they reflect the document's life cycle as defined by the IVOA flowchart.

Why would one restrict the PDFs to "incoming versions" and not have it complete? The only reason I would see is the required efforts, and this is what I volunteer to do (so it is basically for free).

My proposal is exactly what people would expect from a Github repository, and this is what the "Tags" and "Releases" features of Github were made for. If you think the list is too long, we could shorten it by removing the "Internal Drafts" from the Releases (but keep them as tags, so that they can be found).