Document Promotion Modeling in Subversion (was Re: Dropping Subversion)

On Fri, Apr 02, 2004 at 06:01:26PM -0600, Brad Appleton wrote:
> On Fri, Apr 02, 2004 at 01:39:21AM -0300, Nicol?s Lichtmaier wrote:
> > I've read your interesting message about using branches to
> > signify "code states".
> > [ in
> http://subversion.tigris.org/servlets/ReadMsg?list=users&msgNo=9075
> > and
> http://subversion.tigris.org/servlets/ReadMsg?list=users&msgNo=9147
> > ]
> >
> > I've talked to the person in charge of CMM, andhe told me
> > the issue is not just code, but documentation. And not only
> > these kind of tags, but also lots of per-file non-moveable
> > tags like "DRAFT-A", which would work like a stamp/seal. And
> > the key part of this is "per file". When you talk about code
> > is true that you'd better considere the set of changes as a
> > whole. But we seem to have the need to classify and order
> > individual files, and put labels to them. I don't see how
> > Subversion could help us here. =( In fact it's very probable
> > we end up not using subversion because of this very problem.

I still have yet to see why a "Doc" promotion branch would
not work. In fact I know of many shops who do this successfully
with other tools without using a per-file mechanism, and they
have no problem meeting "CMM" requirements.

In fact I can think of at least a few ways I've seen this done.

1. Doc-task branches
--------------------
* Make each "doc" update on its own "task-branch".
* Every time you do a "commit" of the task-branch, associate
  the appropriate PromotionLevel property value with the tip
  of the branch.
* When you port the doc-task branch to the trunk, associate the
  doc-task name and promotion-level as properties of the
  corresponding trunk revision
* If desired, additional promotion can be done on the trunk by
  incrementing the promotion level of the revision associated
  with the corresponding doc-change-task

This gives you an arbitrary number of draft/review promotion
levels (unconstrained by the number of branches used, I can
have as many or as few promotion levels as a need for each
promotion branch, on a per-task bases).

And each revision (change-task) will be able to know which files it
changed/added/removed, so associating the promotion level property
with the revision in fact does allow me to "bump up" the promotion
attribute (like moving a label) on the corresponding versions of
just those files.

2. Single doc-branch
--------------------
Similar to the above but without the need for doc-task branches at all
* Use a single "doc-branch" for all doc updates.
* Each "commit" identifies the name of the corresponding doc change-task
  (and/or doc-id(s)) using a property
* Each revision associated with a change-task (and/or doc-id) can
  also have a promotion-level property associated with it that can
  be independently incremented

This uses only one branch (and uses it solely for documentation)
and uses a "moveable" promotion-level property on the same
revision (change-task) which again is capable of identifying
only the set of files that were changed/added/removed as part
of the commit (but each commit must be a separate change-task
and doc-update, a constraint the doc-change-task branch approach
doesn't have).

In both approaches an svn log of the trunk and/or doc branch
should be able to show the status (promotion-level) of all
doc-updates on the branch. And if one wants to be really
nitpicky one can even compute the corresponding per-doc status
(regardless of whether a "doc" comprises multiple files or
just one file)

-- 
Brad Appleton <brad@bradapp.net> www.bradapp.net
  Software CM Patterns (www.scmpatterns.com)
   Effective Teamwork, Practical Integration
"And miles to go before I sleep." -- Robert Frost
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org