qooxdoo
qooxdoo copied to clipboard
qooxdoo
Release archiving workflow (Suggestion)
This is a proposal to create a workflow that will automatically create an archived version of the documentation, the applications (api, demobrowser...) and the landing page (website) in an archive repository, and expose that archive via redirection from qooxdoo.org.
Terminology: "current" : last stable release, including minor and patch releases "devel": current master
The current (last stable) release is deployed to archive repo and available at
- qooxdoo.org/current/(docs|apps)
- qooxdoo.org/6.1.2/(docs|apps) (example version)
In addition/alternatively, make these resources accessible via a dedicated subdomain such as https://archive.qooxdoo.org/x.y.z/...
This would allow versioning the documentation and the apps (above all, the apiviewer content) at that specific release time.
It would also allow us to remove the documentation from the framework code, since we would have a copy of the documentation with the release which corresponds to the code at release time.
The devel version is simply the version available on the main website: qooxdoo.org/(docs|apps).
Maybe an additional /api shorthand for /apps/apiviewer might make sense for convenience.
Thoughts?
I would previously get to the api viewer with api.qooxdoo.org which was a really nice shorthand.
Examples: https://archive.qooxdoo.org/5.0.2/ (old website) https://archive.qooxdoo.org/5.0.2/api (apiviewer, old structure) https://archive.qooxdoo.org/6.0.2/ (v6 website) https://archive.qooxdoo.org/6.0.2/apps/apiviewer (new structure) https://archive.qooxdoo.org/6.0.2/docs (new structure)
My only concern would be that any general purpose archive needs remains curated and not be just a dumping ground - but at the same time we should limit the work that would take.
The old manuals and api docs would be important to maintain in there (and would be relatively straightforward) for lots of versions, but with each passing major revision the usefulness of the rest (like demo browser, playground etc) is increasingly useless & also harder to maintain.
So for example, the last major version of the framework would have API docs, manual, playground & demo browser but nothing else; all older major versions would be just API docs and manual.
Similarly it seems a bit unnecessary to keep individual patch releases, so keep it down to major+minor version - but only do this for the current and previous major version. EG once 6.x is out, we would have 5.0.2, 5.1.0, and 6.0.0 - but when 7.x comes out, we drop 5.0.2.
@johnspackman I wonder though, if it's really necessary to delete stuff from the Github pages' file tree - since all files are stored in the commit history anyways and you don't know in advance which the release wil be the final one within a major version? Or would you want to delete them completely from the git history, which seems to require some contortions?
No, not delete completely - but AIUI this archive is for the old website as well as having new things to be archived? So the idea is that this is the basis for a public website which makes various resources available to anyone, based on a simple URL.
EG if someone needs to access the 5.1.0 docs, they are always available at something like https://archive.qooxdoo.org/5.1.0/ .
My comment on curating was that we just need a policy on how to handle mapping one version number to another, and how to routinely trim that tree of information - for example, anyone who needs 5.x docs probably just needs "the latest 5.0.x docs" and does not need to distinguish 5.0.2 from 5.0.1 - but there might be a reason to distinguish 5.1.x from 5.0.x. Once you get to older major revisions, IMHO it's just "latest 4.x" docs.
If you look at the contents of the old website, there is loads of stuff that just needs to be lost into the history of the github repo - there is docs for version 0.6.7 !! There cannot be anyone who still needs that, and if there is then they would get it from git.
Im just cautious that you can get a problem with loads of "stuff" that accumulates uncontrolled, which is that eventually it gets really big and then we have to have a sit down and think about whether it would be used any more, have a group discussion, pick through it etc. With really old "0.x.x" docs and a pretty simple (although large) archive that's probably a pretty easy decision to make :) but if we're adding more things to this archive, IMHO we should be clear about what we're using it for and when to add and when to delete.
If I remember correctly, the clone of https://github.com/qooxdoo/website-archive weighs about 5 GB (or was it 10GB)? So it's pretty big, because of all the applications that have been deployed there with website and docs for all of the releases that can be seen in the repo. As long as GitHub doesn't impose size limits on the repo, I don't see a problem with simply adding to that repo which nobody ever needs to check out as a clone, it will just sit there and grow in size, and be a historical archive that maybe one day someone might use to do a study on how code evolves. In addition, what will be added is of a much smaller size than it used to be, since we are no longer deploying the whole suite of apps. My suggestion would be to store only the documentation and the APIViewer, since these need to be versioned along with the code. The rest of the apps will be archived in their own repositories.
Alternatively, we can certainly begin a new release archive with v6 to get rid of the big fat repo. However, as said, since noone ever needs to check out the repo, size doesn't really matter, does it?