Tagging, versioning and releases

[JJ]

The problem

We need releases in this documentation repo for several reasons. First, it's an actual module that can be downloaded from the ecosystem. Second, we need a way for the people to download old versions, just in case they are using (for any reason) an old version of the compiler.

For the time veing, there's nothing like that. Meta6.json version is changed from time to time, mainly when dependencies change. We don't have a new release for 6.d #2632 , not to mention 2019.03 #2673

Tagging and releasing would at least easen the fact that we are not tagging specific examples or features, as suggested as early as #302. It could even be automatic: anything new that has been added from last release is automatically tagged with this release (with some additional tweaking maybe). But in absence of that, a roadmap for releases would really help. We could even simply use tags in the website for creating different versions of it.

Suggestions

Well, I don't know. I don't think we have the resources to keep up with the monthly or even the star release cycle. But we should try at least to create a roadmap for every release, and be able to tell if we're there or not. Yearly would be doable (but hard), every major release would be also doable (if we do work on new features in parallel with new releases). Anything, anyway, passes through the fact that we need some more resources to actually work in the documentation. GSoC will help (at least with tooling), and there's the season of docs after that (for which we intend to apply).

[JJ]

It would really clarify things to peg releases to Rakudo releases. It would also help prioritize "checklist" issues. Work our way down from the first one, release when that's done, for instance.

[Altai-man]

Well, for this one needs to introduce API-like versioning, as was suggested multiple times in documentation mailing list, instead of overwriting the old content as was done for years.
This proposal, alas, has fallen as yet another victim of constant quarrels and bike-shedding within the community, so it is very unlikely this will be ever resolved.

[JJ]

I don't think we're talking about the same thing here. I was talking about releases of the documentation, or rather, the documentation repo, as checkpoints to, for instance, run more extensive tests (or forcibly deploy, which is done now by hand)

[Altai-man]

How is it different from what I mentioned?

[JJ]

Totally? As far as I can tell, you're talking about versions of Rakudo reflected in the documentation, and over which there was a certain amount of argument.
That's totally different (although admittedly has some points of contacts) with what I'm talking about here. You may or may not tag content with versions or releases if you tag the repo with releases, which is what I'm talking about here. You want to additionally add metadata to content, that's fine; tagging the repo might help (in a roundabout way, but it might make things a bit easier, even down to not really needing content metadata). But I'm not talking about changing API or content or anything, just tagging the repo so that we can, for instance, run more extensive tests when doing so and know, more or less precisely, which Rakudo release the documentation belongs to.

[Altai-man]

As far as I can tell, you're talking about versions of Rakudo reflected in the documentation, and over which there was a certain amount of argument.

No, it seems there is a misunderstanding. While I pondered on both issues in the past (the one you described now and the one in this ticket), I mean the one in this ticket.

To save the time I will just copy-paste a bit from my email in the docs mailing list, the thread is "Reset and WHAT!".

1)Right now, any major documentation content changes are effectively blocked. How? Almost every page consists of some sections divided by headings. Headings are used to generate relative URL bits, for example https://docs.raku.org/language/classtut#Consuming_our_class <- see #Consuming_our_class. What happens if we want to rewrite this whole page into a better tutorial? If one of the headings is changed (removed or edited), BOOM, we have a new dangling link immediately. And a lot of pages really need restructuring, say migration tutorials. The obvious way to prevent such a way to embarrass ourselves regularly breaking outer links is to make documentation versioned. Say you have a docs v1.1 and it provides a stable link to the docs of this exact state, all the URLs working. Then you add changes on top of this and produce v1.2 which can have a different structure and be much better (easier to digest etc) and it will have stable links as well and so on and so on. Right now, documentation writers are effectively blocked from any improvements beyond "fix an example output" and the goal is to fix that, unblocking changes.

This is so important I mentioned it as №1 of things I wanted to work on. And as you see I think that just tagging the repo as you suggest, while overwriting the old content, is insufficient, this approach is a dead end, it's impossible to avoid breakage when overwriting the old content is the only way used.

OTOH, some members actively try to block any changes, as changes == BAD, SCARY, then we bike-shed and perish.

[JJ]

Well, it certainly looks like you are trying to block this change, which I'm certainly open to discuss. But it is (almost) totally unrelated to what you mention (and it can certainly help, if you want to take it that way; please read on). You mention documentation content changes are "blocked". This is certainly not a documentation content change; it would be solved by writing a couple of GitHub actions (and, of course, tagging the repo when it's ripe to do so)
But I probably didn't manage to get through the intention of this issue, or the intention of reviving this issue. Let's see if I can get this through a bit more clearly.
First, getting this issue back to life comes from #3935. Right now there's a level of content testing, but thorough testing is not automatized. There are also other things we might want to test, with a certain level or not.
In the (more or less) real world, the level of testing you receive in every push is totally different from the level of tests you receive when doing a release; this is done usually by tagging the repo and creating specific GitHub actions for tags, for instance (but it could be done in some other way).
Tagging/releasing will also help us more or less find out where we are, and which release is totally documented in what's released. That's why I suggested to peg doc releases to Rakudo releases. We could certainly have some other strategy, which would maybe be less prone to confusion to your valuable proposal. For instance, release what we have every second Sunday of every month, and tag it with the month name. What gets in, gets in, what doesn't, left for the next one. That would have the advantage of releasing confusion, and also keep a regular schedule of releases. I don't see myself with the strength (or time) to do so, however. But it's certainly something that we could consider. Running lengthy tests (like spelling) once a month, regularly, certainly has its value. It can also be totally automated. So there's that.
On the other hand, pegging Raku/doc releases to rakudo releases has the advantage of clarity. Here's release 2019.03, it covers everything that was included up to that version. It goes after the previous release (whatever it was), will be followed by the next Rakudo release (whatever that is, maybe it was done 3 years ago). Again, this gives some leverage to what you propose, meta-tagging content (which is why I don't really understand why you're against it, but hey, you're entitled to your opinions, of course; in principle, you could simply use tags to tag content, without actually needing to change content itself), but it's in principle unrelated to it; it's simply a strategy to clarify doc releases, provide a simple roadmap for them, and back to its origin, provide an easy way to run those long-running tests which is what it was designed to provide a immediate solution in the first place.

[Altai-man]

Well, it certainly looks like you are trying to block this change

How? I am simply noting there is more to add to this issue.

This is certainly not a documentation content change

I did not imply this.

I see my words are very lacking, I apparently just cannot convey my point anymore. :/

Let's try with something more organized then, maybe this way we can understand each other.

In my understanding, what you are conveying with this ticket is:

"We need to have a better testing strategy for xt tests" -> "They are not managed, let's create a schedule for them" -> "The schedule will be based on this repo versions, just tag the repo once in a month, run the tests and it's good".

What I am trying to convey is that while this fixes the original "We need to have a better testing strategy for xt tests", there is a much worse underlying issue which must be fixed by introducing versioning. So my point is:

"During editing we overwrite old content, which leads to breaking URLs and confusing users with any major re-arrangements on pages" -> "To preserve that, we need to store both old versions and new versions" -> "To do this we need to introduce versioning on all levels (this repo plus URL schema for the website plus serving the appropriate versions to users when requested)" -> "(yes, as a bonus point we certainly can take care of the xt/ tests, we'll have a release cycle anyway)".

As you may see, one bit of the equation ("we need to version the repo") is the same, but I am suggesting that just tagging the repo to do tests while leaving the rest of the process the same, neglecting the issue with broken URLs, is not sufficient.

[coke]

This item never reached consensus; I think to get there, if anyone feels strongly about any of the issues raised here, please open a new discussion on this repo and we can try to hash it out there.