[OPEN-ILS-DOCUMENTATION] ***SPAM*** Re: [OPEN-ILS-DEV] ***SPAM*** Re: Forming Teams by Topic

[Lori Bowen Ayre]

Jason,

As complicated as your description is, I agree that it would be more
burdensome for everyone if we handle documentation as a separate development
project disconnected from the exact code being documented.

Seems to me there is a need for someone on the Equinox side to work closely
with the DIG to set up appropriate workspaces (or workflow) for submitting
the documentation so it can be committed as appropriate (just like you would
with code, right?).  I imagine the bulk of the documentation being developed
will occur in the wild and then the DIG group would have one person
responsible for working closely with ESI to ensure it is submitted to the
right branch.

I'm more interested in working with the context sensitive help and any other
documentation that lives inside the code.  I think a lot of the work being
done by DIG so far has focused on documentation that may refer to a specific
release but doesn't necessarily live inside the code.  Right?  And for that,
I'm not sure it still makes sense to have THAT documentation follow the
branches and bugfixes so closely...does it?  Seems like User and Admin
Manuals could stay at the Major Release level, not?

Lori

On Mon, May 24, 2010 at 11:16 PM, Jason Etheridge <jason at esilibrary.com>wrote:

> > One other topic which may need to be discussed among the DIGers is how to
> handle the minor releases. For example, 1.6.1.x will add a few brand new
> features not in 1.6.0.1 (Booking module and password resetting
> self-service). I wonder if we just need to add a note under the sections
> dealing with these topics informing users that they are only available in
> version 1.6.1+ or if we need entirely different documentation sets for each
> for these minor release versions?
>
> IMO, this sort of thing should be handled with branching just as it is
> with the software.
>
> So we have a trunk, which (especially in Subversion) you can just
> think of as a folder:
>
> trunk/
>
> And we have some other directories for branches and tags (again,
> Subversion mindset, though for implementing concepts from an older
> version control system called CVS) :
>
> branches/
> tags/
>
> And then at some point in time, the developers have stabilized trunk
> enough to branch it, and they do this by copying trunk to
>
> branches/rel_2_0
>
> and maybe after cleaning that up a little they copy that branch to
> make a "bugfix" branch
>
> branches/rel_2_0_0
>
> and then after some love and QA they "tag" it by copying a snapshot of
> rel_2_0_0 to:
>
> tags/rel_2_0_0_0
>
> We package official releases from tags, and we'll never modify the
> contents of a tag, so we always know what we're getting when we refer
> to that tagged release.
>
> Now, let's say the developers add a new feature to trunk, say a Mind
> Reading feature.
>
> The code changes for the new feature doesn't automatically propagate
> to any of the branches derived from trunk, but the tools involved
> (Subversion, Git, etc.) make it easy to "port" those changes to an
> existing branch.  The more similar the branch is to trunk (the more
> recent it is), the easier it is to port this change.
>
> So we copy/merge the change from trunk into branches/rel_2_0.
>
> We leave rel_2_0_0 alone, because it's just for bug-fixes, not new
> features.  And we leave tags alone by definition (a CVS mindset), as
> they're just supposed to be sacrosanct snapshots of specific branches.
>
> But let's say rel_2_0 gets this new feature and a few others, and
> we're itching to make a stable release with them.  So we branch
> rel_2_0 again and copy it into
>
> branches/rel_2_0_1
>
> and then after some testing, etc., we tag it as
>
> tags/rel_2_0_1_0
>
> And now let's say we found a typo or bug originating in trunk and
> existing in all our branches.  We fix trunk, and then port the fix to
> branches/rel_2_0, and and rel_2_0_0, and to rel_2_0_1.  Then we tag
> new releases based on those last two, creating
>
> tags/rel_2_0_0_1
> tags/rel_2_0_1_1
>
> Now, with all these different versions/copies of the software, we're
> not really spending a whole lot of effort updating them, due to our
> tools.
>
> Every set of changes is given a number (a changeset).  That last
> bugfix in trunk may be numbered 1234, and I could do a command like
> this:
>
> svn -c 1234 merge trunk branches/rel_2_0
>
> to take that changeset from trunk and apply it to branches/rel_2_0.  I
> could also use a GUI program integrated with the file browser in
> Windows to do this same thing.
>
> It's also possible to work in the other direction.  If you happen to
> make a change to rel_2_0 first (say, because it's easier or more
> convenient because you have a rel_2_0 development server handy, or
> because trunk may have some other outstanding issues getting in your
> way), you can port that change to trunk after the fact.
>
> Now, let's say documentation is no different than code as far as
> repository software is concerned, and we even let documentation live
> in the same repository as the source code.
>
> Let's say we documented the Mind Reading feature in trunk shortly
> after we developed it.  Then when we merged the feature into rel_2_0,
> the change to the documentation was merged right along with it.
>
> The older version of the software, rel_2_0_0 (and rel_2_0_0_0) does
> not have the feature, and does not have the change to the
> documentation.  When we later fixed a bug and packaged a bugfix
> release, rel_2_0_0_1 (from rel_2_0_0), we were able to bundle
> appropriate documentation along with it, one that does not mention the
> Mind Reading feature.
>
> If we later improve the documentation for the Mind Reading feature, we
> treat that like any other code change or bug fix, and backport it as
> needed, eventually tagging and packaging a new release of the code and
> software together.
>
> Or we could let the documentation reside in a separate repository, and
> mimic the folder names and branching patterns of the software
> repository.  And then when we package a release, we just pull from
> both repositories.
>
> Does any of this make sense?  Help?
>
> If you weren't using docbook or xml, I imagine folks could side-step
> the type of version control software that developers use and make due
> with a wiki or Google Docs, but it seems like it would be more
> cumbersome to manage/synchronize changes between multiple maintained
> versions (if we were to do that).
>
> --
> Jason Etheridge
>  | VP, Tactical Development
>  | Equinox Software, Inc. / The Evergreen Experts
>  | phone:  1-877-OPEN-ILS (673-6457)
>  | email:  jason at esilibrary.com
>  | web:  http://www.esilibrary.com
> _______________________________________________
> OPEN-ILS-DOCUMENTATION mailing list
> OPEN-ILS-DOCUMENTATION at list.georgialibraries.org
> http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20100525/065e8727/attachment-0001.htm