Questions about h.u.c. branch

[Connor Imes]

Thanks for the quick response Matthew, responses in line.

On 12/04/2010 05:22 AM, Matthew East wrote:
> Hi Connor,
>
> On 4 December 2010 00:07, Connor Imes <rocket2dmn at ubuntu.com> wrote:
>   
>> Hi team,
>>
>> I have some questions regarding our help.ubuntu.com branch [1].  I've
>> recently seen some commits that caught me off guard, so I figured now
>> was a good time to ask to clear up my confusion.
>>
>> I was under the impression that we (Matthew usually) simply copied the
>> html exports here whenever we did an official docs release.  After
>> stable releases, new ones are added, unsupported versions are removed,
>> and the main index is updated appropriately.  Am I correct in assuming
>> that this is the normal approach?
>>     
> Yes, that's correct. I haven't checked some of the recent commits to
> this branch - are they of any concern?
>   
Nothing serious, I think one of them has a typo in it (Messeneger
instead of Messaging or something like that).  Looks like the HTML was
updated directly rather than copied from the build because the docbook
source is correct.
>   
>> When commits are made to the h.u.c branch, does something else have to
>> happen before the changes go live, or is it automatic?
>> If automatic, what is the delay (if any)? Is there a regular export from
>> there every 24 hours?
>>     
> The process is automatic and takes place every 24 hours. I'm not sure
> what time of day. Occasionally the automatic pull from the bzr branch
> breaks, in which case this needs to be reported here and to the
> Canonical Sysadmins.
>
> See https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/BuildingDocumentation
>   
Great, thanks.  I don't recall seeing the info there about h.u.c. in the
past. I guess I should have checked before emailing.
>   
>> If the process is automatic, I wouldn't mind updating the h.u.c. branch
>> more regularly from our stable-release branches - does anybody see any
>> issues there?
>>     
> I don't, as long as we are clear that any update to the h.u.c branch
> should reflect a change which has already been made to the relevant
> stable branch in accordance with our usual practice. I'd be concerned
> if there was a divergence between the documentation. There will be an
> issue that the h.u.c documentation will be slightly ahead of the
> documentation in a particular release, because in order to release
> updates to an existing release, it's necessary to upload the material
> to Launchpad for translation, allow time for translation, import
> translations and upload them to Ubuntu as a stable release update.
>   
I thought I recall that LoCo or other translation teams handle posting
the html docs online in their own languages in their own respective
places.  I understand that we have to upload the translations to LP
before a release in the repos, but I don't think it is critical if we
are only updating the English html docs.  I think having the html docs
more up-to-date than the system docs could be beneficial seeing as a lot
of people use them.  This is especially an issue with broken links as we
have seen recently.
> We really need to document our practice in relation to existing stable
> releases a lot better. I have probably promised this a few times in
> the past but will try to put together a proposal document for
> discussion (unless one already exists somewhere...).
>   
+1, I'd like to see more regular releases, though it appears it is a
fair amount of work.  A couple of questions about updating stable releases:
 - Using good judgment, are we OK to update a stable branch without a
full SRU process if no string changes are required affecting
translations (e.g. URL fixes, Makefile updates)?
 - We have been nominating a lot of bug reports for all affected
versions, many of which are being "accepted" for a release, often by
Brian Murray.  Is this acceptance "approval" to fix the bug in that
version without having to go the translations or SRU mailing list?  In a
few cases I have taken this as approval, I apologize if I broke from the
procedure here.
>   
>> Finally, is there any reason to commit individual fixes here that are
>> normally fixed by editing the docbook source except in critical cases?
>> It seems like duplicate work to me, though mostly harmless.
>>     
> Probably not - again we should ensure that the docbook source doesn't
> get out of date with the html. The docbook source should always be the
> primary place to fix any bug, except where the bug *only* appears in
> the website for whatever reason (e.g. a broken link arising out of a
> problem with our html build system). Ideally, we would keep
> help.ubuntu.com up to date with the package in the relevant release of
> Ubuntu. But we need to get together a good system for doing that. The
> serverguide would be an exception to this, as it is only published
> online.
>
>   
(See my comments above about keeping a more updated html version.)
+1 that the Docbook source is the primary place to fix bugs, let's make
sure this is passed on to all committers, apparently it hasn't been
clear for some of our newer members.

It has not been my intention to call anybody out in these emails, I
think that we have simply failed to pass on all the relevant information
to newer core-doc members.  Thank you (new guys) for all your help
recently, it's been wonderful! Keep it up!

-Connor