diff options
Diffstat (limited to 'Documentation/BK-usage/bk-kernel-howto.txt')
| -rw-r--r-- | Documentation/BK-usage/bk-kernel-howto.txt | 283 |
1 files changed, 283 insertions, 0 deletions
diff --git a/Documentation/BK-usage/bk-kernel-howto.txt b/Documentation/BK-usage/bk-kernel-howto.txt new file mode 100644 index 00000000000..b7b9075d291 --- /dev/null +++ b/Documentation/BK-usage/bk-kernel-howto.txt @@ -0,0 +1,283 @@ + + 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`,+ + |