cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Nalley <>
Subject Re: [DOCS] Questions on publishing and updating documentation
Date Sat, 23 Feb 2013 09:55:00 GMT
On Fri, Feb 22, 2013 at 8:29 PM, Jessica Tomechak
<> wrote:
> On Wed, Feb 20, 2013 at 8:29 PM, David Nalley <> 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
>> <> 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,
>> 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
>> > (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:

Browser cache?

> 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.


View raw message