* Goal
The goal of this document is twofold:
- describe a workflow that will produce a repository history like [[http://doc.bazaar.canonical.com/bzr.2.2/en/user-guide/zen.html][this one]]
- concisely describe the bazaar commands necessary for such a workflow
The reason for such a workflow is that someone looking at the logs of the main
branches will directly see which features have been added, bugs fixed,
etc. Or, in other words, we should be able to use the log messages as the NEWS
contents.
This will not only make it nice and clear to traverse the log history, but
will also facilitate the task of managing changes and deciding which of them
must be published on each release. That is, it will be much easier for the
release managers to pick pre-arranged groups of closely related changes
instead of manually selecting changes one by one when releasing a new version.
* Organization
The main repository is hosted at [[http://sourceforge.net/projects/cedet/][SourceForge]]. There, code is organized into
two main types of branches:
- =code/trunk= :: Main development branch, where new features, bug fixes,
etc. are merged into by developers.
- =code/cedet-= :: Major release branches. These are managed only by
release managers, whose tasks consist of:
- Creating a new major release branch every time a new major release is
about to be produced.
- Cherry picking changes from =trunk= into the release branch, in order
to advance it into new minor releases.
- Tagging the release branch on every new minor release.
Any other branch is only temporarily available while a new complex feature or
bug fix is being collaboratively developed by many developers. Once the
development of such branch is considered stable, the branch might be deleted.
* The workflow in commands
First of all, the information sources:
- SourceForce repository URLs
https://sourceforge.net/scm/?type=bzr&group_id=17886
You must login to see URLs for read/write acess
- SourceForge-specific information when using bazaar
https://sourceforge.net/apps/trac/sourceforge/wiki/Bazaar
*NOTE*: It is very important to correctly set /whoami/
- Bazaar documentation
http://doc.bazaar.canonical.com
- The workflow adopted at Emacs
http://www.emacswiki.org/emacs/BzrForEmacsDevs
The current document is heavily based on this document, and you can refer to
it for more thorough descriptions and discussions on alternative simplified
workflows.
If you need an introduction on basic terminology and concepts, please read
these:
- http://wiki.bazaar.canonical.com/BzrForCVSUsers
- http://doc.bazaar.canonical.com/bzr.2.2/en/user-guide/core_concepts.html
** Developer workflow
The developer is assumed to develop new features and fix bugs by working on
separate (probably local) branches, that are later merged into the mainline
(the =code/trunk= branch on the CEDET repository).
This precise workflow is a tuned version of the workflows described on this
documents:
- http://doc.bazaar.canonical.com/bzr.2.2/en/user-guide/organizing_branches.html
- http://www.emacswiki.org/emacs/BzrForEmacsDevs
*** Setting up the environment
First you will have to create a /shared repository/ to work on your machine:
#+BEGIN_SRC sh
export DEVHOME=~/Projects/ # suit to your taste
cd $DEVHOME
bzr init-repo cedet/
#+END_SRC
Next step is to create a mirror of the mainline (=code/trunk=), from which
all other branches will be derived:
#+BEGIN_SRC sh
bzr checkout bzr+ssh://USERNAME@cedet.bzr.sourceforge.net/bzrroot/cedet/code/trunk trunk
#+END_SRC
*NOTE*: Here /USERNAME/ stands for your SourceForge username. If you do not
have commit access to the CEDET repositories you should use the read-only
URL instead: bzr://cedet.bzr.sourceforge.net/bzrroot/cedet/code/trunk
Finally, you have to tell bazaar the identity you want to use for your
commits:
#+BEGIN_SRC sh
bzr whoami "USERNAME "
#+END_SRC
*NOTE*: If you do not have a SourceForge account you can use your name and
e-mail instead.
*NOTE*: If you do not want to set this =whoami= information globally, you
must execute =bzr whoami --branch '...'= from inside *every* branch that
you create.
*** Creating a task branch
Once merged back into mainline, all changes added to this branch will appear
grouped under a single log entry (although separate changes are still
available), which makes the review and release management process much
easier.
#+BEGIN_SRC sh
cd $DEVHOME/cedet/
bzr branch trunk/ TASKNAME/
#+END_SRC
Here, /TASKNAME/ could be something like the ticket number of the bug that
is being fixes, or a short descriptive name of a new feature.
*NOTE*: Remember that if you-re setting the =whoami= information locally,
you must change into the =TASKNAME/= directory and execute =bzr whoami
--branch '...'= from there.
*** Working in a task branch
This contains the typical development loop.
**** Making changes
Do not fear committing mutiple small changes if they are conceptually
different, even if they are not complete when separate. Your commits will
not be seen by others until you tell bazaar to do so.
On each commit, you would typically:
- =bzr status= :::
Check the current state of your local branch.
- =bzr add ...= :::
Add new files or directories to the repository.
- =bzr remove ...= :::
Remove files or directories from the repository.
- =bzr mv ...= :::
Move files or directories on the repository. Moved (renamed) files or
directories will still retain their full history.
- =bzr commit ...= :::
Commit changes on current branch.
If given the =-m "..."= flag, the given one-line message will be used as
the commit message; otherwise, your default editor will be fired up for
you to fill-in the message.
*NOTE*: You can use Emacs' [[http://www.gnu.org/software/emacs/manual/html_node/emacs/Version-Control.html][Version Control]] package to simplify the task
with a few simple keystrokes.
- =bzr revert ...= :::
Undo uncommitted changes.
- =bzr shelve/unshelve ...= :::
Temporally undo uncommitted changes.
**** Refreshing your mirror of mainline (updating trunk)
The official mainline will change from time to time, so you should refresh
it whenever you want to work with the changes:
#+BEGIN_SRC sh
cd $DEVHOME/cedet/trunk
bzr update
#+END_SRC
**** Merging the latest mainline into your branch (merging from trunk)
Changes on the mainline could conflict with changes you have added on your
local branch, or you might even want to use them. Thus, after updating
trunk you should merge its changes into your local branch:
#+BEGIN_SRC sh
cd $DEVHOME/cedet/TASKNAME/
bzr merge ../trunk
<>
bzr commit -m "Merge from trunk"
#+END_SRC
*** Publishing a task branch
As said, some tasks require collaboration from multiple developers, or a
thorough review from others. The easiest way to accomplish this is to
publish your branch.
If you have commit access on the CEDET repositories, you can simply:
#+BEGIN_SRC sh
cd $DEVHOME/cedet/TASKNAME/
bzr push bzr+ssh://USERNAME@cedet.bzr.sourceforge.net/bzrroot/cedet/code/TASKNAME
#+END_SRC
If you don't have commit access you can still publish branches on your user
space in SourceForge or Launchpad.
If you want to follow the development of a published task branch, you can:
#+BEGIN_SRC sh
cd $DEVHOME/cedet/
bzr branch bzr+ssh://USERNAME@cedet.bzr.sourceforge.net/bzrroot/cedet/code/TASKNAME
#+END_SRC
And you can update its contents anytime with:
#+BEGIN_SRC sh
cd $DEVHOME/cedet/TASKNAME/
bzr pull
#+END_SRC
*** Sending a bundle for review
Instead of publishing your branch, you can submit your changes for review
through e-mail, where others can look at your changes and decide if they are
suited to be merged into the mainline. If not, don't worry, you can still
modify files, make some more commits to your local branch and generate a new
bundle to send.
#+BEGIN_SRC sh
bzr send -o TASKNAME-v1.txt
#+END_SRC
*** Merging into the mainline (merging into trunk)
Once the modifications are ready for integration into mainline, the steps
are:
#+BEGIN_SRC sh
cd $DEVHOME/cedet/TASKNAME/
bzr missing # see what we and others are missing
cd $DEVHOME/cedet/trunk/
bzr update # make sure we are up-to-date
bzr merge ../TASKNAME/
bzr status # optionally see what has changed
<>
bzr commit # immediately pushes changes
#+END_SRC
The most important note here is that the commit message in here will be the
only one displayed by default on the mainline log for all the changes of
/TASKNAME/ that you have done.
*NOTE*: You can still see all the "intermediate" commits inside every merge
with =bzr log -n0=.
*BIG NOTE*: It is very important to perform one separate merge for each
clearly different feature addition or fix of a ticket on the bug
tracker. Otherwise, if multiple of them are merged at once, they will
appear as a single entry on the "simplified" log, and it will be harder for
release managers to pick them up separately in case they need to.
*** After you've finished your task
You can simply remove the directory =$DEVHOME/cedet/TASKNAME/= and start
with a fresh new branch to develop other features.
** Common workflow shortcuts
*** Performing quick fixes
Some feel that it is uncomfortable to create a new branch for every new
feature when such a feature is just a trivial fix that can be contained on a
single commit.
As /trunk/ is a /checkout/ of mainline (as opposed to a /branch/), it can be
directly used for trivial changes.
The difference between a /checkout/ and a /branch/ is that the former
automatically (and atomically) performs a =push= operation immediately after
each =commit=, as well as it can be updated with =update= instead of =pull=.
The net result is that a /checkout/ provides a workflow very similar to
other well-known centralized version control systems. See also: =bzr help
checkouts=.
See also: =bzr help branches=, =bzr help checkouts=.
** TODO Release manager workflow
How to handle merges into release branches.
* TODO Log messages
How merge log messages should be written. This should allow others to quickly
see which subsystem or feature the merge is about, as well as if it is an
enhancement or a bug fix.