When should we deprecate references to 6.c?

[JJ]

The problem

Some references to 6.c are still here and there. For the time being we are simply putting them in past tense, but there will come a time when they will be more confusing than helpful.

Suggestions

This goes way back to #302. I don't think that we will really have the resources to version documentation; we can barely keep up with actually documenting current version (see #2632 #2673 ). Let's discuss here what can be done about these deprecations and how to deal with them.

[coke]

The ideal state for me is that there is a combined version of the docs that includes the various documented versions, and/or a way to generate a version of the docs that is for a specific version of the language.

Ideally, for the public site, we'd default to latest, and allow a user to switch the desired version of the language they want to see the docs for.

While 6.c is no longer the latest, it's definitely still available in recent rakudo releases; while it's tempting to remove the docs at that point, ideally they would still be available for reference. (Just like old versions of Java docs.)

[JJ]

There's a new document file spec page: https://github.com/perl6/doc/wiki/Document-file-specification. Ideally, we could tag, at least at the level we have an actual Pod6 block surrounding the version-specific code. Problem is, we can barely keep up with major (c →d changes), as you might have seen in the pinned issue, not to mention minor changes. So _when_ we have that new file specification working (or some other, it's a wiki, any suggestion or change is welcome) _and_ we have a faster way of incorporating new changes (ideally through parsing specific commits that add new features, it should have to be automated, anyway, because it's impossible with the resources at hand) we might tag _new_ stuff with major or even minor version. If we don't have any of that (which is not unlikely), I'll simply try to have a roadmap for deprecating at least references to old versions. 1 year from release, for instance. We can git-tag every release we do from them on, but we don't have a roadmap or release cycle for documents, so that might be haphazard at best...

[rafaelschipiura]

6.c will be used for a long time. 1 year after release is a really short time.

[coke]

Current planning for dealing with versions is to have a single version of the documentation for all supported versions of the language, and 6.c as noted, is going to be around for a while. If there's a plan in the community to deprecate older versions, we can consider our approach then. Eliminating support for 6.c in the rakudo compiler would be a huge undertaking.

In the meantime, we should be moving towards tags on classes/methods etc. when they are specific to a given version.