-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
We have used CVS for some time now, and I think we can said to be
generally happy about it. However, until now we have only had small
organizational problems due to the small number of developers with
write access to the repository. This is now beginning to change,
currently we have four(three?) developers that sould get write access.
To make the use of CVS easier for everybody we need to use some of
CVS' featues more, in particular _branching_. We should, when creating
a new feature or makeing extensive modifications to the currect ones,
always do this in a branch. Current projects that could be done in a
branch: new importer, the pointer -> reference switch, NEW_INSETS etc.
What we now need is a document describing how to do this, we also need
to lay down the guidelies for when and how to do this.
I propose this:
1 - developers can generate branches as they see fit. (after a
small discussion)
2 - merging from HEAD can be done by the developer responsible
for te branch as the need arises (read: whenever)
3 - mergint _to_ HEAD should never be done before it has been
approved by the other developers, (read: peer review) and
deemed acceptable.
In more detail:
1. When a developer has some significant changes¹ that needs to be
done, just want to make some experimental changes, he should create
a new branch² to do this in. By doing this he declares himself
"branch maintainer"³. One thing to be very clear about is that
branches should never be long lived.
¹ a sinificant change is a completely new feature, extensive changes
to core structures, or just large changes to existing features/code.
² There will be more on the scheme to name branches later in the
document.
³ We will have a web/txt page describing all branches and their curent
status.
2. When working on a branch the development on HEAD does not stop, so
from time to time the branch maintainer will have to merge the
changes on HEAD into the branch. The branch maintainer does this
whenever deemed needed. The exact procedure for this is described
in detail later in this document.
3. When a branch has fullfilled its task, or has come to a stable
point, we need to merge the branch into HEAD. We should be very
careful about this, because:
- the branch code might have serious impact/interactions on
other code.
- the branch has most likely only been reviewed/tested by a
few.
- the code/implementation in the branch might be non-optimal
and changes might be needed (and those changes are best made in the
branch)
So before the merge a diff to the HEAD should be created so that
the others can have a look at what has been done and comment on it.
Think of this as a Peer Review. Only when the other developers are
satisfied about the code should the merge be done.
[Much of what follows is more or less directly form an article in
Dr.Dobbs Journal #317 octover 2000 p. 108: CVS version control and
branch management]
Naming of branches.
- -------------------
Releases will follow the current scheme, with some small changes.
Branches will have BRANCH_ prepended
Tags will have TAG prepended
Merges will have MERGE in them.
lyx-1_2_0
TAG_CREATE_BRANCH_NEW_INSETS
BRANCH_NEW_INSETS
TAG_HEAD_MERGE_TO_NEW_INSETS
TAG_NEW_INSETS_MERGE_FROM_HEAD
TAG_NEW_INSETS_MERGE_TO_HEAD
TAG_HEAD_MERGE_FROM_NEW_INSETS
lyx-1_3_0
let me try to ascii-draw this example
TAG_NEW_INSETS_MERGE_FROM_HEAD
|
------------------------------|-------------
BRANCH_NEW_INSETS X X
|-----------------------------------------|-
| ^ |
| | TAG_NEW_INSETS_MERGE_TO_HEAD
| | |
branch merge merge
| | |
lyx-1_2_0 | | |
| | | v lyx_1_3_0
- -|--------|----------------------------|--------------|------------------------
X X HEAD X XX
- ----------|----------------------------|-------------|-------------------------
| | |
TAG_CREATE_BRANCH_NEW_INSETS | |
| TAG_HEAD_MERGE_FROM_NEW
TAG_HEAD_MERGE_TO_NEW
This is the algorithm:
1. Create your branch and begin working on it
2. Merge changes in the HEAD the first time
3. Corrent conficts and commit
4. Continue working
5. Merge changes in the HEAD that occurred between
your last merge and now.
6. Go to Step 4 if more work is to be done.
7. When done with the branch, merge changes from
the branch to the HEAD
8. Correct conflicts on the HEAD and commit.
In detail with CVS commands:
Step 1. Create your branch and tag the HEAD where it was made. Then
check out a copy of your module that is on the branch.
cvs rtag TAG_CREATE_<branch name> lyx-devel
cvs rtag -b -r TAG_CREATE_<branch name> BRANCH_<branch name> lyx-devel
cvs checkout -r BRANCH_<branch name> lyx-devel
Step 2. Merge canges in the HEAD te first time. First tag the HEAD to
establish a merge point. Then do the merge.
cvs rtag TAG_HEAD_MERGE_TO_<branch name> lyx-devel
cvs update -jHEAD
Step 3. Correct conflicts and commit. After the commit, tag the
branch. [Concurrency issue: This step assumes that no one is making
changes on the branch from the time of the update in the past step to
te "cvs rtag" operation in this one. If that cannot be assured, tag
the working area instead of te repository (that is, use cvs tag
instead of cvs rtag).]
cvs rtag -r BRANCH_<branch name> TAG_<branch name>_MERGE_FROM_HEAD lyx-devel
Step 4. Continue working on the branch until you want to merge in
changes from the HEAD again.
Step 5. Merge changes in the HEAD that occured between your last merge
and now. This is the important step to understand. Merge from the old
tag on the HEAD to the present.
cvs update -jTAG_HEAD_MERGE_TO_<branch name> -jHEAD
Move the tag. The same concurrency issue from Step 3 applies here as
well.
cvs rtag -F TAG_HEAD:MERGE_TO_<branch name> lyx-devel
Fix conflicts and commit. Update the tag on the branch:
cvs rtag -F -r BRANCH_<branch name> TAG_<branch name>_MERGE_FROM_HEAD lyx-devel
Step 6. If mroe owrk is to be done on the branch, go to step 4.
Otherwise go to te next step.
Step 7. When done with the branch, merge canges from the branch to the
HEAD.
cd to lyx-devel that is cecked-out on HEAD (not BRANCH_<branch name>)
cvs update -jBRANCH_<branch name>
Step 8. Fix conflicts. You will likely see a lot of conflicts here
that you dealt with already on the side branch. The second choide
conflict is the one that came from the branch and usually is the one
you want to choose. This should be straightforward. Fix all conflicts
and commit. Advise others that the side branch is no longer to be
used.
Of course before we continue from step 6 a patch should be created that
can be used for review of the changes. And if any changes are needed
we should move to step 4 and do them and continue from there.
I'd like to get some comments on this, but I will bot put it into
effect until after 1.1.6 is released and we begin working towards 1.2.
Lgb
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.4 (GNU/Linux)
Comment: Processed by Mailcrypt 3.5.5 and Gnu Privacy Guard <http://www.gnupg.org/>
iD8DBQE5/kyoroOTYxRWaasRAlX5AKDE8J6uL9K2mmmYyKkeeqzPcQoXDgCfSQgT
PaDbDSwZuXsVu+ksIuW9kks=
=s90q
-----END PGP SIGNATURE-----
