Lets version lock the docs!

Marco Ceppi marco at ondina.co
Thu Jan 15 19:57:05 UTC 2015


I think we should be updating older versions and this would require a bit
of work on the team maintaining the docs to recognize content that needs to
be backported and perform the cherry pick to do so.

On Thu Jan 15 2015 at 2:54:12 PM Jeff Pihach <jeff.pihach at canonical.com>
wrote:

> +1 with a note.
>
> I've been involved with projects who have versioned docs with users on
> multiple versions and an issue which came up quite frequently was that it
> was a hassle to update legacy versions with more information.
>
> A somewhat contrived example could be that we want to add additional
> information to how users should deploy local charms. This information is
> still valid for old versions but the author has to go and backport the
> information for each version manually because other details on each tag
> might conflict. This of course could be mitigated a few ways, one of which
> is simply by saying that we just won't update old versions, but that's not
> always wise if you have a large number of users still using old versions.
>
> -Jeff
>
> On Wed, Jan 14, 2015 at 11:54 AM, Marco Ceppi <marco.ceppi at canonical.com>
> wrote:
>
>> Hey everyone,
>>
>> There's currently quite a few version of juju available [0] from various
>> sources (cloud archive, ubuntu archive, stable ppa, source). While I know
>> the release team is doing a great job in making sure that versions of juju
>> are consistent across platforms, it's inevitable that users will be on
>> different versions. As more features land in juju, documentation will
>> become inconsistent for users. This, again, is a topic that has undergone
>> quite a bit of discussion from when the docs were originally migrated to
>> Markdown at various UDS and vUDS meetings what I'd like to do is get the
>> ball moving on completing this: offering multiple version of the docs for
>> released version of juju.
>>
>> The proposal is as follows. The juju docs repository will continue to
>> have a "master" branch which will be "tip of trunk" for juju and
>> documentation bits, essentially "devel". As the release team gears up for a
>> release we will create a branch for that release milestone (1.20, 1.21,
>> 1.22, etc). From there, the jujucharms.com/docs website will offer
>> latest release as default view (ie: jujucharms.com/docs/getting-started)
>> and a drop down to select previous versions of docs, which will be
>> available at docs/VERSION (ie: jujucharms.com/docs/1.21/getting-started).
>>
>> Any issues, typos, or mistakes that need to be addressed and previous
>> versions of the docs can take place in that branch and will continued to be
>> built periodically with the rest of the doc. We're pretty confident this
>> model will work out great for those writing the docs, not wanting to land
>> fixes too soon while improving overall user experience in reading the
>> documentation.
>>
>> Ideally, we'd like this to coincide with the next juju release, 1.21, so
>> before that lands we'd like to call for feedback about the process outlined
>> above, concerns, or questions.
>>
>> [0]: http://packages.ubuntu.com/search?keywords=juju
>>
>> Thanks,
>> Marco Ceppi
>>
>> --
>> Juju mailing list
>> Juju at lists.ubuntu.com
>> Modify settings or unsubscribe at:
>> https://lists.ubuntu.com/mailman/listinfo/juju
>>
>>
> --
> Juju mailing list
> Juju at lists.ubuntu.com
> Modify settings or unsubscribe at: https://lists.ubuntu.com/
> mailman/listinfo/juju
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju/attachments/20150115/3c1421e3/attachment.html>


More information about the Juju mailing list