Re: Proposal: GNOME Docs String Freeze

[Shaun McCance <shaunm gnome org>]

The subject of a docs string freeze has been tossed around for as long
as I've been involved (something like 14 years now). We all generally
agree that it would be a good thing if we could do it, but our tight
release schedule and understaffed docs team makes it hard.

One thing I've been wanting to do for a long while now is to make it
possible for us to explicitly mark pages as final, and to have that
show up in the PO files, so translators can prioritize.

We already have a way to mark pages as final with the revision tag.

<revision version="3.26" status="final"/>

But that information doesn't make it into the PO files. When I was on
the ITS 2.0 working group, a group of us wanted to do an ITS rule to
indicate translation readiness. Unfortunately, we failed to get it
ready in time. But I could still do an extension rule in itstool. It
would look something like this:

<itst:readinessRule
  selector="/mal:page[mal:info/mal:revision
    [@version = $curversion][@status = 'final']]"
  readiness="ready"/>

Note the variable $curversion. The ability to use variables is a new
addition to ITS 2.0. We'd just have to update it each release cycle.

With this, messages in PO files would have a marker like this:

#. (itstool) readiness: ready

For extra special bonus points, we could teach PO editors about this
marker so they could present a better UI.

Is this something the team would be interested in pursuing?

--
Shaun

On Tue, 2017-05-30 at 16:03 -0400, Jeremy Bicha wrote:
> Hi!
>
> The Ubuntu Docs team currently intends to ship gnome-user-docs in the
> Ubuntu 17.10 default install with a minimal "overlay" to keep a few
> Ubuntu-specific customizations in the separate package ubuntu-docs.
> Furthermore, the Ubuntu Docs team intends to ship the GNOME
> translations for gnome-user-docs. I see one issue: Ubuntu tries not
> to
> break translations when providing stable release updates.
>
> Specific example (but I don't intend to criticize anybody here):
> gnome-user-docs 3.24.0 had a string change about an hour and a half
> before the tarball was released, which was not enough time for any
> language to get translations for that string. More changes were made
> after that point but there was not much translating done before
> 3.24.2
>
> My understanding of why GNOME doesn't have a docs string freeze is
> that to some extent, the UI needs to be frozen for docs to be
> finalized. Also, we don't want to put arbitrary roadblocks in the way
> of anyone making great contributions to our docs.
>
> Proposed gnome-user-docs schedule for GNOME 3.26
>
> 1. Docs String Freeze at the GNOME 3.26.0 release. At that point, a
> gnome-user-docs tarball would be released and the gnome-user-docs git
> repo branched for gnome-3-26. Any new string changes can go to the
> master branch.
> 2. gnome-user-docs tarball release for 3.26.1 and .2. The 3.26.1
> release should be on time for it to be included in Ubuntu 17.10,
> assuming Ubuntu 17.10 goes with GNOME 3.26.
>
> Reference
> ---------------
> https://wiki.gnome.org/ThreePointTwentyfive
>
> Thanks,
> Jeremy Bicha
> _______________________________________________
> gnome-doc-list mailing list
> gnome-doc-list gnome org
> https://mail.gnome.org/mailman/listinfo/gnome-doc-list