Decide on document version marking
thoni56 opened this issue · comments
In a comment to #74, I layed out a minimalistic process to work with the manual until we find actual reason/need to do something more complicated (other documents might require different handling).
- master will continously evolve but should describe the latest official release (currently 3.0 beta 7)
- the dev branch should be reserved for changes that add descriptions of features upcoming in the next official release
- extra branches may be used for experimental changes in the toolchain, or descriptions of features not even scheduled for implementation
If we can agree on this procedure, then the only thing we need to decide is how to mark the document. I propose that the primary information of interest to a reader is
- Which SDK/Alan version is it describing
- Is this the same as the one I already have?
We can handle 1) by marking the document with that version, so the one on master should always have "3.0 beta 7" as long as that is the most recent official released version of Alan/the SDK. For the snapshots we would have to devise some naming like (currently) "3.0 beta 8 - dev" or maybe even "3.0 beta 8 - development snapshot" to be inline with the SDK development snapshots.
For 2) we could just use the date it was produced. This implies that we should perhaps not have the generated pdf and html versions in the repository, but instead generate them in a CI-jobs somewhere and upload them (to github, presumably).
For 2) we could just use the date it was produced. This implies that we should perhaps not have the generated pdf and html versions in the repository, but instead generate them in a CI-jobs somewhere and upload them (to github, presumably).
That's more of a "political decision" really. Maybe you could just upload them on the ALAN website, which is were most users will be downloading the documents from anyhow.
In any case, the links to the documents are not going to change in time — if you point to master branch, you'll always get the latest official Beta edition, if you point on dev-man you'll always get the latest WIP previews.
But probably using a CI job to create a Zip package with both the PDF and HTML docs is a good ideas. Downloading the PDF from GitHub can be done via the "raw links", but HTML documents can't be previewed without an external service like GitHub/Bitbucket Live HTML Preview.
Probably moving everything on www.alanif.se is better, offering both the HTML and PDF on their own, or in Zip file (possibly together with the ALAN SDK package?).
The IF writer should be spared having to go to GitHub to fetch the documents. But of course, he/she should be provided a link to this repo, in case curiosity sets in, and wants to learn more.
Publishing and Version Info
AsciiDoc offers us three distinctive adjectives for marking a document version info:
:revnumber:— Version number of the document.:revdate:— Date of document version.:revremark:— Version comments.
And it also allows to customize the :version-label: preceding the revnumber in a converted document’s byline.
Right now, the current document's byline is:
- Version 0.1.101-PreReleaseBeta7
- September 20, 2020
- Beta7 Ed. work
I agree that public releases on master should always be clearly associated to the latest ALAN Beta release (at least, until ALAN reaches stable release).
As for the dev-man versions, I suggest the following two scenarios:
-
Alpha SDK — always indicate the latest Alpha version, because we might be including features were added in recent Alpha updates. The idea is that
dev-manshould always be "nightly" — as in, whenever we lay hands on the document, and update it, it is in relation to the latest Alpha release.This way, if a users sees that the Alpha version indicated in the Manual lags behind the latest SDK release, he/she'll know that the Manual might not have been updated to describe some new features of the latest Alpha (as mentioned in its Changelog).
It should also be reasonable to expect that any new Alpha features would be described in the Manual as soon as possible (if not immediately, at least we'll create an Issue to remind us to do so, and might be working on the update in a sub-branch).
-
Beta-RCs — it might also happen (like it's happening right now) that a new Beta release is out but the Manual is not ready to be published for that Beta version. In that case, we'll be switching from
AlphatoBeta<X>-RC, i.e. working on a candidate release.The
-RCfragment is really just a way to avoid confusion and having multiple "Beta7" versions going around — there will be many-RCdocument versions, but a single official Beta7 (Beta8, etc.) release.
Of course, we could eventually decide to publish updated version of the Manual for the same Beta SDK, e.g. in case a year has passed and many new contents were added to the Manual. In that case the publishing date would be what distinguishes one edition from another.
In other words, any public edition is clearly identified by the SDK version it refers to, and the publishing date. That's really all that matters for public releases.
As for the "WIP documents" in dev-man, they are not to be considered releases at all, they are just preview documents. For that reason we might adopt extra qualifies in those preview builds, to avoid confusion when comparing/diffing different snapshots — but, ultimately, these are all unofficial documents, for internal use, although end users should be able to access them via the dev-man branch, although we don't really offer any guarantees on their completeness, except that usually if a commit made it into the dev-man baseline it's fairly polished and verified.
Conclusion
Public Beta Releases
For official releases of the Manual (i.e. Beta SDK releases), the only important markers are:
:revnumber:→ ALAN SDK Beta version.:revdate:→ public release date of the document.
The :revremark: attribute should probably be set to an empty string, for we don't need it — unless it's something like an "Anniversary Edition", in which case we could use it to mark a special edition.
Although there might be multiple updates for the same ALAN Beta release, these are probably going to be rare, and avoided too (just because they introduce the risk of an Alpha features that was described in the manual to end up in the update).
Alpha Previews
There are no "Alpha releases" of the Manual, just previews for the curious who wants as sneak-peak at the latest WIP document. I suggest it should be safe to rebuild both the HTML and PDF in dev-man, both for our benefits (so we can compare the generated docs from different commits), both for end users (who can safely use the branch-based preview links to access the WIP docs).
For WIP documents, we need to use more markers:
:revnumber:→ Latest ALAN SDK Alpha (updated whenever we edit).:revdate:→ updated with every commit, for the sake of diffing.:revremark:→ only useful when dealing with candidate releases of the upcoming Beta, if we need to add some extra info.
In reality, all we need is the :revnumber:, for the -RC marker is part of the SemVer version info. But :revremark: can be useful to mark specific aspects of the work in progress, at our discretion.
References
I completely agree. Done. Except for doing it ,-)
Looking forward to a PDF/HTML of what we now have accomplished, and a branch where I can put the block comment documentation ;-)
Looking forward to a PDF/HTML of what we now have accomplished,
Well, both the PDF and HTML are available on the dev-man branch, so having them ready for public release depends on whether we want to keep editing until the StdLib update is ready (mid Nov.) or if we instead prefer to go ahead with the final chores and merge into master straight away — technically speaking, the Manual is ready to go, we only need to edit the version info in the Header, and then merge.
and a branch where I can put the block comment documentation ;-)
We can either wait for the merge on master, and then do it on dev-man directly, or (if we postpone to Nov. the release), start working on it on a new dev-man_<feature> branch.
BTW, is the block comments feature already available in the Alpha SDK? I couldn't find any release notes on the websites, and didn't have a chance to download the latest Alpha SDK and peek inside its Changelog.
As mentioned in #8, let's go!
Block comments are implemented and working on a branch but not merged, so it's not in a snapshot yet. Nor is it documented ;-)