cloudstack-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Nalley <da...@gnsa.us>
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
<jessica.tomechak@gmail.com> wrote:
> 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/

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

Mime
View raw message