Lets version lock the docs!

[Jeff Pihach]

+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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/juju/attachments/20150115/bc70568b/attachment.html>