1da177e4c3
Initial git repository build. I'm not bothering with the full history, even though we have it. We can create a separate "historical" git archive of that later if we want to, and in the meantime it's about 3.2GB when imported into git - space that would just make the early git days unnecessarily complicated, when we don't have a lot of good infrastructure for it. Let it rip!
284 lines
12 KiB
Plaintext
284 lines
12 KiB
Plaintext
|
|
Doing the BK Thing, Penguin-Style
|
|
|
|
|
|
|
|
|
|
This set of notes is intended mainly for kernel developers, occasional
|
|
or full-time, but sysadmins and power users may find parts of it useful
|
|
as well. It assumes at least a basic familiarity with CVS, both at a
|
|
user level (use on the cmd line) and at a higher level (client-server model).
|
|
Due to the author's background, an operation may be described in terms
|
|
of CVS, or in terms of how that operation differs from CVS.
|
|
|
|
This is -not- intended to be BitKeeper documentation. Always run
|
|
"bk help <command>" or in X "bk helptool <command>" for reference
|
|
documentation.
|
|
|
|
|
|
BitKeeper Concepts
|
|
------------------
|
|
|
|
In the true nature of the Internet itself, BitKeeper is a distributed
|
|
system. When applied to revision control, this means doing away with
|
|
client-server, and changing to a parent-child model... essentially
|
|
peer-to-peer. On the developer's end, this also represents a
|
|
fundamental disruption in the standard workflow of changes, commits,
|
|
and merges. You will need to take a few minutes to think about
|
|
how to best work under BitKeeper, and re-optimize things a bit.
|
|
In some sense it is a bit radical, because it might described as
|
|
tossing changes out into a maelstrom and having them magically
|
|
land at the right destination... but I'm getting ahead of myself.
|
|
|
|
Let's start with this progression:
|
|
Each BitKeeper source tree on disk is a repository unto itself.
|
|
Each repository has a parent (except the root/original, of course).
|
|
Each repository contains a set of a changesets ("csets").
|
|
Each cset is one or more changed files, bundled together.
|
|
|
|
Each tree is a repository, so all changes are checked into the local
|
|
tree. When a change is checked in, all modified files are grouped
|
|
into a logical unit, the changeset. Internally, BK links these
|
|
changesets in a tree, representing various converging and diverging
|
|
lines of development. These changesets are the bread and butter of
|
|
the BK system.
|
|
|
|
After the concept of changesets, the next thing you need to get used
|
|
to is having multiple copies of source trees lying around. This -really-
|
|
takes some getting used to, for some people. Separate source trees
|
|
are the means in BitKeeper by which you delineate parallel lines
|
|
of development, both minor and major. What would be branches in
|
|
CVS become separate source trees, or "clones" in BitKeeper [heh,
|
|
or Star Wars] terminology.
|
|
|
|
Clones and changesets are the tools from which most of the power of
|
|
BitKeeper is derived. As mentioned earlier, each clone has a parent,
|
|
the tree used as the source when the new clone was created. In a
|
|
CVS-like setup, the parent would be a remote server on the Internet,
|
|
and the child is your local clone of that tree.
|
|
|
|
Once you have established a common baseline between two source trees --
|
|
a common parent -- then you can merge changesets between those two
|
|
trees with ease. Merging changes into a tree is called a "pull", and
|
|
is analagous to 'cvs update'. A pull downloads all the changesets in
|
|
the remote tree you do not have, and merges them. Sending changes in
|
|
one tree to another tree is called a "push". Push sends all changes
|
|
in the local tree the remote does not yet have, and merges them.
|
|
|
|
From these concepts come some initial command examples:
|
|
|
|
1) bk clone -q http://linux.bkbits.net/linux-2.5 linus-2.5
|
|
Download a 2.5 stock kernel tree, naming it "linus-2.5" in the local dir.
|
|
The "-q" disables listing every single file as it is downloaded.
|
|
|
|
2) bk clone -ql linus-2.5 alpha-2.5
|
|
Create a separate source tree for the Alpha AXP architecture.
|
|
The "-l" uses hard links instead of copying data, since both trees are
|
|
on the local disk. You can also replace the above with "bk lclone -q ..."
|
|
|
|
You only clone a tree -once-. After cloning the tree lives a long time
|
|
on disk, being updating by pushes and pulls.
|
|
|
|
3) cd alpha-2.5 ; bk pull http://gkernel.bkbits.net/alpha-2.5
|
|
Download changes in "alpha-2.5" repository which are not present
|
|
in the local repository, and merge them into the source tree.
|
|
|
|
4) bk -r co -q
|
|
Because every tree is a repository, files must be checked out before
|
|
they will be in their standard places in the source tree.
|
|
|
|
5) bk vi fs/inode.c # example change...
|
|
bk citool # checkin, using X tool
|
|
bk push bk://gkernel@bkbits.net/alpha-2.5 # upload change
|
|
Typical example of a BK sequence that would replace the analagous CVS
|
|
situation,
|
|
vi fs/inode.c
|
|
cvs commit
|
|
|
|
As this is just supposed to be a quick BK intro, for more in-depth
|
|
tutorials, live working demos, and docs, see http://www.bitkeeper.com/
|
|
|
|
|
|
|
|
BK and Kernel Development Workflow
|
|
----------------------------------
|
|
Currently the latest 2.5 tree is available via "bk clone $URL"
|
|
and "bk pull $URL" at http://linux.bkbits.net/linux-2.5
|
|
This should change in a few weeks to a kernel.org URL.
|
|
|
|
|
|
A big part of using BitKeeper is organizing the various trees you have
|
|
on your local disk, and organizing the flow of changes among those
|
|
trees, and remote trees. If one were to graph the relationships between
|
|
a desired BK setup, you are likely to see a few-many-few graph, like
|
|
this:
|
|
|
|
linux-2.5
|
|
|
|
|
merge-to-linus-2.5
|
|
/ | |
|
|
/ | |
|
|
vm-hacks bugfixes filesys personal-hacks
|
|
\ | | /
|
|
\ | | /
|
|
\ | | /
|
|
testing-and-validation
|
|
|
|
Since a "bk push" sends all changes not in the target tree, and
|
|
since a "bk pull" receives all changes not in the source tree, you want
|
|
to make sure you are only pushing specific changes to the desired tree,
|
|
not all changes from "peer parent" trees. For example, pushing a change
|
|
from the testing-and-validation tree would probably be a bad idea,
|
|
because it will push all changes from vm-hacks, bugfixes, filesys, and
|
|
personal-hacks trees into the target tree.
|
|
|
|
One would typically work on only one "theme" at a time, either
|
|
vm-hacks or bugfixes or filesys, keeping those changes isolated in
|
|
their own tree during development, and only merge the isolated with
|
|
other changes when going upstream (to Linus or other maintainers) or
|
|
downstream (to your "union" trees, like testing-and-validation above).
|
|
|
|
It should be noted that some of this separation is not just recommended
|
|
practice, it's actually [for now] -enforced- by BitKeeper. BitKeeper
|
|
requires that changesets maintain a certain order, which is the reason
|
|
that "bk push" sends all local changesets the remote doesn't have. This
|
|
separation may look like a lot of wasted disk space at first, but it
|
|
helps when two unrelated changes may "pollute" the same area of code, or
|
|
don't follow the same pace of development, or any other of the standard
|
|
reasons why one creates a development branch.
|
|
|
|
Small development branches (clones) will appear and disappear:
|
|
|
|
-------- A --------- B --------- C --------- D -------
|
|
\ /
|
|
-----short-term devel branch-----
|
|
|
|
While long-term branches will parallel a tree (or trees), with period
|
|
merge points. In this first example, we pull from a tree (pulls,
|
|
"\") periodically, such as what occurs when tracking changes in a
|
|
vendor tree, never pushing changes back up the line:
|
|
|
|
-------- A --------- B --------- C --------- D -------
|
|
\ \ \
|
|
----long-term devel branch-----------------
|
|
|
|
And then a more common case in Linux kernel development, a long term
|
|
branch with periodic merges back into the tree (pushes, "/"):
|
|
|
|
-------- A --------- B --------- C --------- D -------
|
|
\ \ / \
|
|
----long-term devel branch-----------------
|
|
|
|
|
|
|
|
|
|
|
|
Submitting Changes to Linus
|
|
---------------------------
|
|
There's a bit of an art, or style, of submitting changes to Linus.
|
|
Since Linus's tree is now (you might say) fully integrated into the
|
|
distributed BitKeeper system, there are several prerequisites to
|
|
properly submitting a BitKeeper change. All these prereq's are just
|
|
general cleanliness of BK usage, so as people become experts at BK, feel
|
|
free to optimize this process further (assuming Linus agrees, of
|
|
course).
|
|
|
|
|
|
|
|
0) Make sure your tree was originally cloned from the linux-2.5 tree
|
|
created by Linus. If your tree does not have this as its ancestor, it
|
|
is impossible to reliably exchange changesets.
|
|
|
|
|
|
|
|
1) Pay attention to your commit text. The commit message that
|
|
accompanies each changeset you submit will live on forever in history,
|
|
and is used by Linus to accurately summarize the changes in each
|
|
pre-patch. Remember that there is no context, so
|
|
"fix for new scheduler changes"
|
|
would be too vague, but
|
|
"fix mips64 arch for new scheduler switch_to(), TIF_xxx semantics"
|
|
would be much better.
|
|
|
|
You can and should use the command "bk comment -C<rev>" to update the
|
|
commit text, and improve it after the fact. This is very useful for
|
|
development: poor, quick descriptions during development, which get
|
|
cleaned up using "bk comment" before issuing the "bk push" to submit the
|
|
changes.
|
|
|
|
|
|
|
|
2) Include an Internet-available URL for Linus to pull from, such as
|
|
|
|
Pull from: http://gkernel.bkbits.net/net-drivers-2.5
|
|
|
|
|
|
|
|
3) Include a summary and "diffstat -p1" of each changeset that will be
|
|
downloaded, when Linus issues a "bk pull". The author auto-generates
|
|
these summaries using "bk changes -L <parent>", to obtain a listing
|
|
of all the pending-to-send changesets, and their commit messages.
|
|
|
|
It is important to show Linus what he will be downloading when he issues
|
|
a "bk pull", to reduce the time required to sift the changes once they
|
|
are downloaded to Linus's local machine.
|
|
|
|
IMPORTANT NOTE: One of the features of BK is that your repository does
|
|
not have to be up to date, in order for Linus to receive your changes.
|
|
It is considered a courtesy to keep your repository fairly recent, to
|
|
lessen any potential merge work Linus may need to do.
|
|
|
|
|
|
4) Split up your changes. Each maintainer<->Linus situation is likely
|
|
to be slightly different here, so take this just as general advice. The
|
|
author splits up changes according to "themes" when merging with Linus.
|
|
Simultaneous pushes from local development go to special trees which
|
|
exist solely to house changes "queued" for Linus. Example of the trees:
|
|
|
|
net-drivers-2.5 -- on-going net driver maintenance
|
|
vm-2.5 -- VM-related changes
|
|
fs-2.5 -- filesystem-related changes
|
|
|
|
Linus then has much more freedom for pulling changes. He could (for
|
|
example) issue a "bk pull" on vm-2.5 and fs-2.5 trees, to merge their
|
|
changes, but hold off net-drivers-2.5 because of a change that needs
|
|
more discussion.
|
|
|
|
Other maintainers may find that a single linus-pull-from tree is
|
|
adequate for passing BK changesets to him.
|
|
|
|
|
|
|
|
Frequently Answered Questions
|
|
-----------------------------
|
|
1) How do I change the e-mail address shown in the changelog?
|
|
A. When you run "bk citool" or "bk commit", set environment
|
|
variables BK_USER and BK_HOST to the desired username
|
|
and host/domain name.
|
|
|
|
|
|
2) How do I use tags / get a diff between two kernel versions?
|
|
A. Pass the tags Linus uses to 'bk export'.
|
|
|
|
ChangeSets are in a forward-progressing order, so it's pretty easy
|
|
to get a snapshot starting and ending at any two points in time.
|
|
Linus puts tags on each release and pre-release, so you could use
|
|
these two examples:
|
|
|
|
bk export -tpatch -hdu -rv2.5.4,v2.5.5 | less
|
|
# creates patch-2.5.5 essentially
|
|
bk export -tpatch -du -rv2.5.5-pre1,v2.5.5 | less
|
|
# changes from pre1 to final
|
|
|
|
A tag is just an alias for a specific changeset... and since changesets
|
|
are ordered, a tag is thus a marker for a specific point in time (or
|
|
specific state of the tree).
|
|
|
|
|
|
3) Is there an easy way to generate One Big Patch versus mainline,
|
|
for my long-lived kernel branch?
|
|
A. Yes. This requires BK 3.x, though.
|
|
|
|
bk export -tpatch -r`bk repogca bk://linux.bkbits.net/linux-2.5`,+
|
|
|