Fork of [http://emacswiki.org/emacs/BzrForEmacsDevs Emacswiki article] as on 13:42, 27 March 2012 (EEST).

Fork of [http://emacswiki.org/emacs/BzrForEmacsDevs Emacswiki article] as on 13:42, 27 March 2012 (EEST).

−

This is a quick-start guide to using [[Bazaar]] for Emacs development.

+

This is a quick-start guide to using [[Bazaar]] for Emacs development. Please upgrade to '''GNU Bazaar >= 2.0''' before proceeding ahead.

−

−

Use of GNU BaZaar >= 1.17 is desirable but GNU Bazaar >= 2.0 is recommended.

In the workflows described below, a quick "bzr status" is inserted before each commit.

In the workflows described below, a quick "bzr status" is inserted before each commit.

−

= Prior Read =

+

= The Bazaar Work Routine =

−

−

[http://bazaar-vcs.org/BzrForCVSUsers Bazaar for CVS Users]

−

The mainline branch of the public Emacs repository will be called the /master branch/, /master/ for short, or /upstream master branch/ for emphasis. (The mainline branch is the one containing the changes targeted for future public releases.)

+

Here is a quick overview of the Bazaar work routine. Each of the following steps is explained in detail later.

−

Bazaar doesn't provide extensive Unix-style man pages, or Info. Instead, use ##bzr help##, and see [[#Other Resources]] for more documentation.

+

# Tell Bazaar your name and email address

+

# Create a bzr shared repository locally, to hold all your branches.

+

# Create your first local branch: a mirror of the upstream project trunk (it will be "bound to" the upstream trunk; more on that below)

# Do trivial, single-commit work in your local trunk mirror and commit to upstream from there; do your non-trivial work in dedicated branches, committing locally as you go (more about that below).

+

# From time to time, update to get upstream newness into your mirror branch (this is like <tt>cvs update</tt>), and then merge the newness into your dev/task branches from there (also sort of like <tt>cvs update</tt>).

+

# When a task is finished (a local branch's changes are complete), then either

+

## merge them into the master branch (if you're a maintainer and have the necessary access rights --- this is analogous to committing in CVS), /or/

+

## package up your changes and send them as a "bundle" to the project mailing list (analogous to posting a patch).

+

# Receive feedback.

+

# Lather, rinse, repeat until the change is accepted.

+

# If you did all this on a local feature branch, you can remove the branch now. The change history will live upstream.

= Personalizing Bazaar =

= Personalizing Bazaar =

Line 20:

Line 27:

bzr whoami "J. Random Hacker <jrandom@gnu.org.invalid>"

bzr whoami "J. Random Hacker <jrandom@gnu.org.invalid>"

−

=== Where is Emacs? ===

+

= Where is Emacs? =

; See branches in Emacs repository

; See branches in Emacs repository

Line 27:

Line 34:

; Browse entire repo with Loggerhead

; Browse entire repo with Loggerhead

: http://bzr.savannah.gnu.org/lh/emacs/

: http://bzr.savannah.gnu.org/lh/emacs/

−

−

−

To make a local branch or branches based on upstream Emacs, start at [[#InitializingYourBzrRepo]] and follow instructions from there. (This is the Bazaar equivalent of `cvs checkout`.)

On MS-Windows, you need either to remove the quotes around the arguments to the ##echo## command or use a ported GNU ##echo##.

TIP-2

Finally, do //not// use "##nosmart+##" in any bzr command but the initial ##bzr branch##, because the "smart" operation is much faster for routine work. Even the initial ##bzr branch## command should be faster without "##nosmart+##, so use it only if the initial branch command takes forever.

Importan

all your branches should be sibling directories under ##$DEVHOME/emacs/## -- this way they will all share history data, which makes Bazaar operations, including ##bzr branch##, orders of magnitude faster.

Doing Quick Fixes

You can do quick, self-contained fixes (one-line patches and the like) directly in ##trunk## if you want:

Because ##trunk## is "bound" to upstream, this commit will automatically push the changes upstream.

Important

If you are integrating another developer's work, you can use ##--author 'J. Other Hacker <jhacker@gnu.org.invalid>'## to identify JO Hacker as the author of the change.

Note

For larger tasks, such as a complicated bug fix or new feature that might require multiple commits and rounds of feedback, we always recommend creating a "task branch" dedicated to that fix or feature -- see #FeatureBranch.

//Note://

Another Way: Using a Dedicated Branch for Quick Fixes

Some people don't like doing development work in ##trunk## at all, they prefer it to remain a pristine mirror of the upstream trunk at all times. Instead, they keep a special branch for quick changes, and keep reusing that branch. Like trunk, it is bound to upstream, so that commits will be sent upstream automatically. To create such a branch:

This will create a directory ##quickfixes##, populated with the Emacs source tree, and bind it to upstream.

However, it still takes time to check out the source tree for a new branch (which we just did), and bootstrapping a new tree takes an annoyingly long time. That is why reusing the same branch for small changes makes sense. After you have bootstrapped a branch once, the subsequent update, build, and commit steps of the update-edit-build-test-commit cycle are each very fast, as long as you continue working in the same branch.

Once you have created and bootstrapped the ##quickfixes## branch, the routine work in it is as shown above for the trunk:

Because ##quickfixes## is "bound" to upstream, this commit will automatically push the changes upstream.

[:InitializeBranch]
[:FeatureBranch]
[:RegularDevelopmentBranch]

Workflow for Regular Development

Creating a Task Branch

When you are working on a task that touches many files, or requires a lot of thought and several stages, or for any reason may take a fair amount of time, it's a good idea to work on a separate branch to keep the changes from interfering with concurrent work (including your own!), and to keep the history separate from other work. This makes review easier, too. So first create a new branch:

cd $DEVHOME/emacs
bzr branch trunk/ TASKNAME/
cd TASKNAME

...where "TASKNAME" could be, e.g., the bug tracker ticket number of the bug you're trying to fix, or just a short, descriptive name for the task.

Working in a Task Branch

At this point, you're ready to do work. You edit the source files, build and test as needed. When you've accomplished a subtask, it's a good idea to stop and commit your work to the branch. Here, you often have a larger ChangeLog than can comfortably be entered on the command line with ##-m##. In this case, you put the log message in a file we'll call ##log-message.txt##. Then

You can also do ##bzr commit -m "blah blah blah"##, if your log message is short enough to fit on one line. Remember, these commits are local: they affect only the task branch, since it is not bound to upstream. The commits don't affect the upstream master branch, and they don't even affect your local trunk mirror. No one else will see the commits until you send them upstream.

If the task isn't done yet, keep working. Edit yet more source files, until you reach a good stopping point:

The reason you use "##merge##" instead of "##update##" in the task branch is that your task branch is an independent branch (not bound to anything else) and has its own local commits. In other words, it has diverged (a bit) from the upstream master, and so any changes from upstream have to be merged with your local changes.

The merge may fail due to an upstream change that conflicts with your branch. You'll need to fix the problem (looking for conflict markers and editing, just as in CVS). When you save the files which had conflict markers, Emacs will automatically invoke "bzr resolve" for you, to tell Bazaar that conflicts were resolved. If for some reason you don't use Emacs to fix the conflicts, you will need to do it manually:

Publishing a Task Branch

A common practice in Bazaar is to publish your entire branch for review (most of the branch consists of stuff from upstream, and Bazaar easily shows the reviewers the differences -- that is, your changes). Posting a branch is sort of like posting a patch, but carries more information, such as the commit messages.

You can publish your branch anywhere that can host Bazaar branches. One convenient place is Launchpad.net. Once you have a Launchpad account, publishing is just:

(The "USERNAME" in that last command is your username, not the reviewer's, of course.)

As you make new changes to your branch, you can repeatedly push to the same location to publish them. The ##--remember## flag to ##bzr push## may be handy, if you don't want to keep typing the same destination URL.

If you are a committer, you could also push the branch to Savannah by a similar command, and people can pull it from there for review. Or if you have your own server somewhere, it's fine to post branches there too. It doesn't really matter. Wherever it is, as long as you can provide a URL to it, other developers can get the data.

[:SendABundle]

Sending a Bundle for Review

Another way to post changes for review is to create a "bundle", which is a file containing your change, in a special "merge directive" format that bzr understands but that also contains a human-readable diff:

bzr send -o PATCHNAME.txt

where ##PATCHNAME## is some brief mnemonic name for the change. Send a mail to the Emacs Devel list describing the change; attach ##PATCHNAME.txt## to that mail (please use MIME type ##text/plain##). If the reviewers ask for further tweaks, repeat the cycle. Edit the files, build and test as necessary, and

When revising your change, even though nobody else knows about your first commit yet, it is simplest to just make more commits. (It's possible to "uncommit" in Bazaar, but it's not straightforward, and there's no compelling reason to do it if you're just revising a change.) Although in the ##quickfixes## branch a plain ##bzr log## will show you all your changes, when you do plain ##bzr log## after your changes have been merged in ##trunk##, you will see only a merge commit log, which describes the whole series of commits for this task. It will typically look something like "Merge: fix bla bla bla (closes Bug #1)."

[:PushToUpstream]
[:MergeToUpstream]

Merging Into the Upstream Master

If you are a committer, you can merge to the upstream master directly. To do this, first update your mirror:

which automatically merges all your new commits to the upstream master, because the mirror is set up as bound branch. In this process, updating your ##trunk## with ##bzr update## is not really optional. There is a race condition here, just as in CVS: if your mirror is not up-to-date because another developer has committed since you last updated, your commit will fail. In this case you should abort the merge

bzr revert

do another ##bzr update##, merge from the ##TASKNAME## branch again, and commit. After you successfully commit, the changes will appear grouped as a single merge in ##bzr log## on the mainline, but anyone can use ##bzr log -n0## to see the sub-commits (or "nested commits") within that merge.

It might occur to you to save some effort by just doing ##bzr push## directly to the upstream master from inside the ##TASKNAME## branch:

//Do not do this// --- it can cause history to be displayed in a strange way in the upstream master, any mirrors or branches of it, and your own branch later. Search for the word "hidden" in this mail for more details.

[:FinishTask]

After You've Finished Your Task

When you're done with your work and it's all been sent upstream, you can delete your task branch...

cd ..
rm -rf TASKNAME/

...and update your mirror to receive your own changes:

cd trunk/
bzr update
cd ..

Note that you will still be able to see the entire history of your branch in the trunk by using ##bzr log -n0##, even though you've deleted the local copy.