Re: Dealing with levels in specs

> Hi all,
> 
> Thanks Tobie for starting the thread of that topic. Levels on /TR have
> indeed started to cause of a lot of problems because so far, we
> don't have a good way to manage the different versions of a
> specification.
> After discussing with different people, we came up with a document
> listing 3 proposals aiming at normalizing the latest version links. It
> is available at:
> 
> https://w3c.github.io/tr-links/versioning/
> 
> 
> The idea is to introduce new links to help the different
> audiences (browser implementors, web developers, etc) find the
> version of the specification they are looking for.
> 
> Please take a look at the document and I encourage you to create
> issues on the Github repository [1] if you have any questions/comments.
> FYI, I created an issue for each proposal [2][3][4]. Feel free to
> comment on it and/or +1 on your preferred proposal.
> 
> Thank you,
> 
> Denis
> 
> [1] https://github.com/w3c/tr-links
> 
> [2] https://github.com/w3c/tr-links/issues/1
> 
> [3] https://github.com/w3c/tr-links/issues/2
> 
> [4] https://github.com/w3c/tr-links/issues/3


This is interesting, but I think it is missing on two critical pieces: how these various drafts get produced, and the fact that there is typically not a single ED that represents the bleeding edge, but 1 ED per level, the latest of which typically does represent the bleeding edge, and the others being preparation for updates to the various TR versions. The fact that these various EDs tend to be updated fairly inconsistently adds a fair bit of confusion, as well as overhead, when the time to reconcile them comes.

The various TR version cannot simply be snapshots of the latest ED at different points in time, since the latest ED typically combines a mix of mature features taken from the previous REC (if any), stabilizing features meant to become the next REC, and foward looking features meant to move to TR after that.

I think that one way to solve this would be to embrace git at a deeper level than we do now, and mandate a particular branching and merging workflow that deals with what we are trying to accomplish.

Here is an example of a possible workflow, presented not as The One True Way, but as food for thought:

- A stable branch
- A staging branch
- A latest branch
- multiple feature or bugfix branches

The stable and staging branches branch would take no direct commit, only merges. Each merge commit on the stable branch would be equivalent to what we today consider a publication on TR. The necessary legal requirements (currently verified in transition calls and the like) would be preconditions to approving a merge to the stable branch

Any change, whether a bug fix or a new feature or an editorial change, must always be done in a separate branch.

* Merging to the latest branch is equivalent to putting something in the ED of the newest level today.
* Merging to the staging branch is equivalent to putting something in the ED of the stabilizing TR version today
* Merging the staging branch to the stable branch would be equivalent to various things depending on the situation:
  - there has been no REC or CR yet: equivalent to pushing a new WD out to TR, or to pushing out the first CR if tagged appropriately
  - There has been a CR, but no REC yet: equivalent to updating the CR, or to pushing out the first REC if tagged appropriately
  - There has been a REC already, and the changes are minor: equivalent to publishing errata on a REC
  - There has been a REC already, the the changes are substantial: equivalent to publishing a new level REC
* The Equivalent of PR would be handled by a specially tagged version on the staging branch, to be reviewed there.

This is in line with the way many software project work and manage their release versions, beta versions, nightly channels, and so on.
In my experience, the trickiest part of such workflows is to get people into the habit of starting their feature/bugfix branches not from the tip of the latest branch, but from what they wish to be able to merge into. Something that needs to be independently merge-able into stable/staging (in addition to latest) without bringing unintended dependencies should be branched off stable/staging, although it is possible to work around that by cherry picking changes from latest to staging.

As today for Pull Requests, you would need to go to github directly for the feature branches that have not been merged anywhere yet, but everything else could be exposed to the web through something like this, with appropriate links and redirects generated automatically:

/TR/shortname/
/TR/shortname/stable/
/TR/shortname/stable/YYYYMMDD/
/TR/shortname/staging/
/TR/shortname/staging/YYYYMMDD/
/TR/shortname/latest/
/TR/shortname/latest/YYYYMMDD/
/TR/shortname/index/

—Florian

Received on Saturday, 17 December 2016 06:18:00 UTC