[OPEN-ILS-DEV] #help Evergreen 2.2 Release

[Soulliere, Robert]

Hi Dan,

I agree with your proposals for more single sourcing and providing the docs in the tarball. Our switch to AsciiDoc makes this more viable given the usability of AsciiDoc in its "raw" form compared to DocBook XML. I am not sure of other processed formats (HTML, PDF, etc...). I guess we need to consider a balance of providing mulitple formats vs the size of the tarball?

Note that I think Developers can currently commit to the DIG repository.
 The actual live git repository which can be committed to is located on the same server as Evergreen Code: http://git.evergreen-ils.org/?p=Evergreen-DocBook.git;a=summary. I gained access by sending SSH keys to Galen. I am assuming that developers an also gain access the same way if they don't already have commit access given their current access to the Evergreen code repo.
The github repository (https://github.com/rsoulliere/Evergreen-DocBook/) I usually refer to is the a mirror of the main evergreen documentation repo.

Regards,
Robert


Robert Soulliere, BA (Hons), MLIS
Systems Librarian
Mohawk College Library
robert.soulliere at mohawkcollege.ca
Telephone: 905 575 1212 x3936
Fax: 905 575 2011
________________________________________
From: open-ils-dev-bounces at list.georgialibraries.org [open-ils-dev-bounces at list.georgialibraries.org] On Behalf Of Dan Scott [dan at coffeecode.net]
Sent: April 5, 2012 2:56 PM
To: Evergreen Development Discussion List
Subject: Re: [OPEN-ILS-DEV] #help Evergreen 2.2 Release

Hi Robert:

I apologize, I was supposed to respond to this weeks ago.

On Tue, Feb 28, 2012 at 2:01 PM, Soulliere, Robert
<robert.soulliere at mohawkcollege.ca> wrote:
> Hi Anoop,
>
> Does the release-notes-writer role basically take what is in the raw release notes from the master file as added by developers here:
> http://git.evergreen-ils.org/?p=Evergreen.git;a=blob_plain;f=docs/RELEASE_NOTES_2_2.txt;hb=master
>
> and get them into the official docs such as here?:
> http://docs.evergreen-ils.org/2.2/_release_notes.html

That's a good short term model, I think. We just started trying to
keep release notes up to date late in the 2.2 cycle, so they're pretty
limited this time around, but hopefully we'll get better in future
releases.

> If so, perhaps I can help with that and take on that role?

That would be great, in my opinion.

> Can we just use one source for that in the official docs or do we need to add a wiki page as well?

Yes, ideally we would only need one source for that. I would
personally prefer to avoid adding a wiki page to the mix.

> Also note that we have upgrade instruction in the official docs here:
> http://docs.evergreen-ils.org/2.2/_upgrading_the_evergreen_server.html
> -- this is based on the alpha release, but if you give me a few days heads up before the official release will be released, I could get those updated to reflect the official tarball version. It might also be good to have a few folks review the upgrade instructions chapter as well.

Yes, single-sourcing the upgrade instructions would be a really good
idea too. Just taking a quick peek at the current version, there are a
number of things that I think we would want to change. Holding an
official review would be a good idea, I think.

> In general I think DIG has more documentation ready to go for 2.2 than we did for past releases.
> See:
> http://docs.evergreen-ils.org/2.2/

Yes, it's exciting to see this progress! DIG++

Here's a crazy longer-term idea: what if, as part of the release
process, we pulled the documentation repository into the Evergreen
tarball - effectively replacing what we have in the /doc/ directory
today with the DIG documentation? We could do that manually, or
automate it as part of Thomas' release-cutting script, or we could use
git "submodules" (http://book.git-scm.com/5_submodules.html) to do it
more formally.

The advantage would be that users would get a copy of the Evergreen
documentation with the tarball - and it would be truly single sourced.
(We could also talk about building the HTML & PDF & ePub versions of
the documentation in the distributed tarball as well; depends on how
far we want to go with that).

Developers would need to be able to commit to the DIG repository if we
wanted to continue to maintain the install intructions and release
notes as we do today, and add upgrade instructions to our bailiwick,
but that seems to be a small price to pay for a pretty big win
overall.

This E-mail contains privileged and confidential information intended
only for the individual or entity named in the message.  If the reader
of this message is not the intended recipient, or the agent responsible
to deliver it to the intended recipient, you are hereby notified that
any review, dissemination, distribution or copying of this communication
is prohibited.  If this communication was received in error, please
notify the sender by reply E-mail immediately, and delete and destroy
the original message.