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

[Jason Etheridge]

> 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