So I've written some inline responses to this message - but when I got to the bottom, I realized that the disconnect here is likely caused by the differences in how releases and more importantly, git branches are handled here. So, hopefully this will explain it.
For each feature release (4.1, 4.2, 4.3, etc) there is a release branch. This branch is created at feature freeze for that feature release. At that point, the code will never have any more features. We begin bugfixes, QA, docs, etc on that release. When we cut a release, we don't branch, but instead, tag the version (which essentially is a bookmark in the git repos timeline of commits) work continues in the release branch for the next bugfix release (i.e. 4.0.2 that's going on right now) and each of those bugfix releases is a tag from the release branch. This is pretty different than the way release branches were handled pre-ASF. In that case we had main version branch (AKA 3.0.x), and each point release had it's own branch as well (i.e. 3.0.2) This meant you could 'patch' things in 3.0.2 if you needed a specific bugfix. For all practical purposes you can't do that here. (well you technically can, but lets just say it's messy and bad form to do so, and lots of extra work) On Wed, Feb 20, 2013 at 8:49 PM, Jessica Tomechak <jessica.tomec...@gmail.com> wrote: > There's a question of how to publish docs, and how often to update docs for > previous releases, if at all. > > Publishing new docs: > As far as I know, docs aren't auto-uploaded to the doc site [1] every time > a new doc build results in new output. I think there's a manual upload, and That is correct. There is no autoupdate. Reasoning for this below. > I don't know whether it's documented. I wish that I had the steps and > permissions, because I would like to be able to push doc fixes when it's > appropriate. At the least, more than one person should have the know-how. > If some subset of people are already "maintainers" on this process, let's > add that info somewhere in the Doc Writers part of the project wiki.[2] > I think several folks have the knowledge. Joe and I worked through this one day on IRC and he has the logs, not sure whether he's transitioned that to wiki documentation or not. > Updating old docs: > My practice with CloudStack docs pre-Apache was always to propagate fixes > backwards to whatever releases they affected, put a new "Updated On:" date > on the title page, and republish. I don't know whether we want to be that > exhaustive about backwards-maintaining published docs. It's possible we > want to do this only for real "showstopper" errors in the docs...like, say, > incorrect installation instructions or security holes. Or maybe we do want > true real-time updates to all docs in all versions. > Well 'real time' causes other problems. For instance - if you update something, is that update valid for the version that being updated? (it's technically version+1 in the codebase, so where does that update apply, version already released, or version +1?) We also have to remember that we have a growing l10n community, our various content pieces are being translated into ~14 different languages. Every change we make means those fall out of sync, and we have to know two things to be able to go back in time and update: 1) At what point in time (commit reference) were those documents generated? (we need to be able to generate pots, potentially regenerate the site, etc) 2) If I begin updating from that reference, what's the impact? Let me explain the problem. We currently have 4.0.0 and 4.0.1 - they both began life in the 4.0 release branch. If you made an update to docs, and push it out - are we sure it applies to both 4.0.0 and 4.0.1? (It should, except in the case of release notes) Now, suppose I want to translate the docs, how do I know what point in time the published docs are from? How do I get that translation incorporated and docs built? (the short answer is some nasty branching, that I'd really prefer not to do, but it is technically possible, just ill-advised). For this (and several other) reason, the code and docs at freeze are the released documentation. Because we have relatively rapid bugfix releases, it's pretty easy to release bugfixes to docs as well when those happen (which was very much the case in the 4.0.1 release.) > So far in the life of ACS, it seems we have frozen the docs for release > 4.0.0 and have not updated them since they were first posted on > http://incubator.apache.org/cloudstack/docs/. (I am not sure, because I > don't see an Updated: timestamp.) If any doc bug-fixes have been checked in > to a 4.0.0 branch since then, it would be great to rebuild and upload those > docs again. > So a couple of clarifications. There is no 4.0.0-incubating branch - there is only a 4.0.0-incubating tag. The tag is a point in time of the 4.0 branch. (We handle branching and releases significantly differently than we used to pre-ASF, there is much more rigor here to the release philosophy) Because it's a tag and not a branch, there is no way to check into 4.0.0, just the update stream for 4.0 (which is more akin to the 3.0.x branch pre-ASF) > It does not appear we published updated docs for 4.0.1. So that brings up > another question. Do we want to update docs for every minor release? Or > just for moves like 4.0 to 4.1? > We did publish for 4.0.1 - the day it released, from what was tagged as 4.0.1.
