Open Stack

On 30/03/13 11:27, Laura Alves wrote:
> 
> 
> On Fri, Mar 29, 2013 at 7:47 PM, Anne Gentle <anne at openstack.org
> <mailto:anne at openstack.org>> wrote:
> 
>     Hi all,
>     Would you be okay if we stop using /trunk/ for the current "built
>     from git" versions of the documentation and copied the files to
>     docs.openstack.org/current <http://docs.openstack.org/current>
>     instead? The word "trunk" is leftover from bzr/Launchpad days of yore.
> 
>     The tasks that have to happen for this to occur are:
>     - Change all the /trunk/ build jobs in openstack-infra/config to
>     /current/
>     - Check all the pom.xml files for mentions of trunk
>     - Ensure that the sitemap.xml stored on the web server contains
>     /current links
>     - Ensure comments are turned off for /current just like they are for
>     /trunk
>     - Change all the openstack-manuals/www/ pages to point to /current
>     instead of /trunk
>     - Change the Google Custom Search Engine from /trunk to /current (we
>     hide /trunk from the CSE searches)
> 
>     Anything else? Warn the mailing list or get further input?
> 
>     If no one objects by next Tuesday, I'll put this on my to-do list
>     for next week. 
> 
>     Thanks,
>     Anne
> 
>     P.S. Note that this rename is similar to cutting a doc release,
>     documented here: https://wiki.openstack.org/wiki/Documentation/Release
> 
>     _______________________________________________
>     Openstack-docs mailing list
>     Openstack-docs at lists.openstack.org
>     <mailto:Openstack-docs at lists.openstack.org>
>     http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> 
> 
> +1
> 
> If there is consensus about this, does it sound like a good idea to
> split the tasks? 
> I can certainly help with the pom.xml files, since I've got some patches
> in review and some others to submit, I could check for trunk in them.
> 
> Regards!
> Laura

One note for consideration (just putting this out there - no strong
feelings):

>From a user perspective, 'trunk' and 'current' could come across quite
differently. As an Operator, when I see 'trunk' I think "oh, that's
something to do with the code. I'm running a production system, so I'll
ignore that and find the stable release". When I see 'current', I
associate that with the current stable release.


One thing I noticed about the development cycle is that a bunch of
deprecation happened early. Options slated for removal tended to be
deleted as soon as the code freeze was over. I may be living in a dream
world, but I feel that we should be putting these changes into the
documentation as soon as we can after we spot them - an automated system
(which I think is the aim for config options) would certainly do this.
With changes in this manner, the 'current' doc would be quite quickly
inconsistent with 'current stable release' and that could cause confusion.

All this can likely be fixed by some careful wording in the release
selection page for those coming via docs.openstack.org, but I worry
about those who come in direct via Google. Perhaps a little 'draft' or
'pre-release' banner with a link to the current release is needed in the
template.


Thoughts?


Regards,


Tom