On Fri, Feb 22, 2013 at 8:29 PM, Jessica Tomechak <jessica.tomec...@gmail.com> wrote: > On Wed, Feb 20, 2013 at 8:29 PM, David Nalley <da...@gnsa.us> wrote: > >> 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. >> > > I don't see any updated docs marked "4.0.1" on the doc website. Can you say > a bit more about this, please? Are we publishing somewhere else now? I am > looking at: > > http://incubator.apache.org/cloudstack/docs/
Browser cache? http://incubator.apache.org/cloudstack/docs/en-US/Apache_CloudStack/4.0.1-incubating/html/Release_Notes/index.html http://incubator.apache.org/cloudstack/docs/en-US/Apache_CloudStack/4.0.1-incubating/html/Installation_Guide/index.html http://incubator.apache.org/cloudstack/docs/en-US/Apache_CloudStack/4.0.1-incubating/html/Admin_Guide/index.html http://incubator.apache.org/cloudstack/docs/en-US/Apache_CloudStack/4.0.1-incubating/html/API_Developers_Guide/index.html > > To your more general comments: If it's technically difficult and/or > philosophically undesirable to update older docs on the website, and that's > the community's consensus, fine. It certainly makes life easier, and makes > better translation possible, as you noted. So docs would be "set in stone" > once they're uploaded to the site? Docs set in stone at release, I'd surmise. > > Would we make any exceptions? Say there are really stupid command errors > that make it impossible to install the software, or "Best Practices" that > turn out to cause huge security holes. Or would we rather just handle those > with addendums, release notes, and blog posts? > I am sure that some room for exceptions would exist, but no thoughts to pre-defining them. --David
