[CVS] HOWTO vendor tracking for Debian package maintainence and development of upstream sources.
>>>>> "Michael" == Michael Sobolev <mss@transas.com> writes:
Michael> On Tue, Jun 13, 2000 at 04:04:22AM -0700, Karl M. Hegbloom wrote:
Karl> Today for some reason I went and put Newt and Slang into my CVS
Karl> repository. I checked in the Woody version of Newt, then went to Red
Karl> Hat and got their latest.
Karl> If it's useful to yous, you may access:
Karl> <URL:http://bittersweet.inetarena.com/~cvsweb/cvsweb.cgi/newt>
This is very much the CVS sandbox. I've got other peoples packages
in here, as exeriments, and stuff I've begun but have put on a back
burner for one reason or another. I'm not homesteading your
packages, I'm just experimenting with CVS and sometimes with upstream
development CVS checkouts and the Debian maintainer's packaging
scripts. There is much for me to learn still, especially from large
packages like `glibc' and `X'... (some of their techniques will be
valuable for the XEmacs-21.2 project I began last summer. It's been
idle a while.)
Karl> There are undoubtedly patches made by Red Hat that you will want to
Karl> merge with your working version...
Michael> Like what? :) Is it possible to find this information directly from your
Michael> repository? Something like:
Michael> cvs diff -ub -r<upstream tag> .
Well, yes, that's the idea. I can give you anoncvs access
instructions.
Vendor Tracking and Debianization
---------------------------------
I noticed something about the way you imported `newt' that I think is
the wrong way to go about it. The way you've done it, it is *not*
possible to obtain the diff between the upstream release and your
modified copy, nor will it be simple to upgrade the upstream version
and join their changes to your own. I think you should rebuild your
repository, or allow me to do so for you.
You imported your editted version, without first checking in a VENDOR
branch. Here's the steps I used to create the repository I gave you
the `cvsweb' URL to. Doing things this way allows you to upgrade
your VENDOR branch from new upstream releases, and makes it easier to
join their changes to your HEAD revisions, and easier for you to
generate patches against their HEAD revisions for submission to the
upstream maintainers. This is an important part of our job, and is
potentially a neglected part of it. It's lazy to expect the upstream
maintainers to come searching for patches to their software.
Hopefully if they borrow something from our tree, they will return
the favor when they make portable modifications.
This is from memory; I believe it's mostly accurate, though the log
entries might not be verbatim. Don't just paste it; think about what
it's doing.
cd /usr/local/src/PKG/woody/main
mkdir newt
cd newt
apt-get -d source newt
mkdir tmp
cd tmp
tar xzf ../newt-0.50.orig.tar.gz
cd newt-0.50
cvs -d /var/cvs/debian import -m 'Initial import of newt-0.50 to vendor tracking branch' newt VENDOR newt_0_50
cd ..
rm -rf newt-0.50
At this point, I now have a repository in /var/cvs/debian with a
toplevel directory "newt". In it is upstream newt-0.50 on a 1.1.1.1
branch tagged with the branch tag "VENDOR". There is also a tag
named "newt_0_50" that tags not a branch, but this specific version.
The VENDOR tag will always get the latest upstream revision that has
been imported, and the version tags will pull out specific versions.
cd ..
pwd
==> /usr/local/src/PKG/woody/main/newt
Ok, now I check out a copy of that, letting it default to the trunk
revision, of course. So if I change anything and commit it, it goes
to the trunk, off the 1.1 branch. The pristine upstream VENDOR
revisions will still exist, and thus be there for generating diff's.
cvs -Q -d /var/cvs/debian checkout newt
cd newt
zcat ../newt-0.50-7.diff.gz | patch -p1
cvs commit -m'Debian patch 0.50-7'
cvs add debian
cd debian
cvs add *
cvs commit -m'Debian patch 0.50-7'
cd ..
cvs tag debian_version_0_50-7
cd ../tmp
I then ran `ncftp', and went to a Red Hat mirror, and got the
newt-0.50.8 source rpm, used `mc' to copy the CONTENTS.cpio out of
the source rpm. I used `cpio' to unpack it, then untarred the
newt-0.50.8 tarball, and ran, from inside tmp/newt-0.50.8:
cvs -d /var/cvs/debian import -m 'Upgrade to newt-0.50.8' newt VENDOR newt_0_50_8
cd ../..
rm -rf tmp # note no leading /
cd newt
cvs update -j newt_0_50 -j newt_0_50_8
I had to fix several conflicts, utilizing XEmacs and `pcl-cvs'...
All of the above shell commands were run in an XEmacs `M-x shell'
buffer. After the `cvs update -j ...', I used `C-r' to locate the
files with conflicts, visited them, fixed the conflicts and saved
them, and noted which files had required merge conflict resolution.
Then, I used `M-x cvs-examine', and used the pcl-cvs interface to
commit those three files, noting in the commit log that this change
is the result of a join and that I've resolved conflicts here.
I then committed the rest of the files that had been patched by the
`cvs update -j ...', noting them as modified by the join, but with no
conflicts. None of the debian/* files, of course, got modified by
the join operation, since they don't exist on the VENDOR branch.
Poke around my repository using the `cvsweb', and you'll see how the
tagging and commit logs worked out, etc. For working with CVS, I
recommend using XEmacs and `pcl-cvs'. (The latest version of
`pcl-cvs' from cvs.xemacs.org is especially nice to use.) There are
other tools available; I've not tried them for long. It's most
convienient to have the CVS interface right inside the editor. You
may need to run `(require 'vc-hooks)' to make it notice when you
visit a CVS controlled file. (If you like `vi', try `xemacs -l
viper' once.)
This is pretty much the same procedure that the `cvs-buildpackage'
set of scripts follows... I've found that by doing by hand, I learn
the process better, and that those scripts don't quite (but almost)
do what I want.
You then have a VENDOR branch, as described by the CVS documentation,
and a trunk branch that contains your Debianization changes, and your
own development.
If it seems complicated at first, be assured that, like anything else
(even emacs), it's really not complicated after a while -- it becomes
second nature. Be prepared to make a few mistakes. It might be good
to create a quick tarball of the repository before doing something to
it you're not sure of, or make a `cp -a' of it and work in that
experimentally. You can `tar' up a set of CVS ,v files, and untar
them elsewhere. There's no special registration of them required;
just open them in a valid $CVSROOT and it'll work.
Debianization of upstream development CVS
-----------------------------------------
If you poke around much in my `cvsweb', you'll find several modules
there that contain only the debian/ stuff. I use those along with
upstream anoncvs checkouts. I run something like:
cvs -d /var/cvs/debian checkout -d debian.librep librep/debian
... which puts a directory named "debian.librep" next to the upstream
anonCVS checkout of `librep', then I cd into the upstream librep and
do `ln -x ../debian.librep debian'. It works very well.
Submitting patches to the upstream maintainers
--------------------------------------------------------------
While I work, especially on code checked out from a remote CVS
repository, I keep a ChangeLog as I go, to act as a guide to what
modifications I've done, so that I don't have to keep reading diff
output to see what I've done. I set up XEmacs so that
`change-log-default-name' is "ChangeLog.karlheg", and that way, when
I use `C-x 4 a' to log something, it doesn't get written to the
upstream "ChangeLog", but rather to my personal one.
Then, when I submit a patch (usually via email, when working with
anoncvs) I paste in the `cvs diff -u' output (generated by `=' in
`pcl-cvs' `M-x cvs-examine'), and above it, the relevant ChangeLog
entries from my personal change log, then above that, type a brief
explanation or rational if one seems appropriate. Now, if that patch
and change log are added upstream, when I `M-x cvs-update', there
will not be a merge conflict in "ChangeLog". Additionally, I'll have
a separate log of my own changes. It is also a good idea to save a
copy of the email you send the patch in, in case it gets lost
upstream or something.
ChangeLogging
-------------
ChangeLogging as you go is essential. It saves a lot of time when
you go to commit your changes or email a patch. You should never
commit to the repository unless the code builds and runs OR you are
syncing for laptop or for shared-burden development (after
communicating with the other project members), and such commits
should bear appropriate (and perhaps standardized) log messages --
"laptop sync", for example. Since, this way, the log entries are
already written, you'll spend less time reviewing diff output looking
for things you'd otherwise "forget" to mention when you commit.
Some will argue that the ChangeLog can be generated from the commit
logs. Logging as you go (and reviewing the diffs + editting your
ChangeLog entries prior to committing) is the only way to ensure that
each important modification gets noted, and thus easily located by
future maintainers. One way to do it would be to keep a
"ChangeLog.<username>" as you go, and use that to generate your
commit log entries, then generate the global project "ChangeLog"'s
automaticly from CVS. The script that creates that ChangeLog could
conceivably filter out "sync" commits, like the laptop example above.
There are a lot of lazy (negligent) programmers who can't hear their
mother calling and who believe that an autogenerated ChangeLog is
sufficient, but do not follow through with detailed commit log
entries. They are either just plain lazy, or have been improperly
trained. Too often I see commit logs that don't really say anything.
They say something inane like "Fixed some bugs.". I think that
people who work with CVS from the command line tend to do that. Use
`pcl-cvs', or one of the other GUI tools, PLEASE.
Keep a ChangeLog as you go, so you can quickly generate _descriptive_
commit log entries from it. The information will be appreciated by
people who are digging for information about when certain changes got
made. It's much easier to find out things about *recorded* *history*
than it is to review the *fossil* *record* of un-commented diffs.
Just finding out which revisions to grab a diff between is half the
battle. The commit logs and ChangeLog are the guide for locating
that information.
No one will get writes in *my* repository without following those
guidelines. There are undoubtedly things I don't know about yet
regarding code maintenence via CVS (or bk). I'd like to hear from
experienced programmers... esp. Cygnus, MIT, and FSF coders.
Reply to: