incubator-cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jessica Tomechak <jessica.tomec...@gmail.com>
Subject Re: [DOCS] Questions on publishing and updating documentation
Date Sat, 23 Feb 2013 01:29:57 GMT
On Wed, Feb 20, 2013 at 8:29 PM, David Nalley <david@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.tomechak@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/

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?

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?

Thanks,
Jessica T.

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message