* 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 branch 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. **** Refreshing your mirror of mainline (pulling 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 pull #+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 want to use of them. Thus, after pulling 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 you can still publish branches on your user space in SourceForge or Launchpad. *** 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/trunk/ bzr pull # this is mandatory (pulling from trunk) bzr merge ../TASKNAME/ bzr status # optionally see what has changed <> bzr commit bzr push #+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=. If after merging and resolving any conflicts someone else has committed to the mainline, the =bzr push= will simply fail. In this case, you should use =bzr revert= and start again. In order to decrease the chances you should /merge from trunk/ into your branch before /merging into trunk/. This way, no conflicts will appear and everything will go smoothly. *NOTE*: The =bzr revert= operation will delete all your changes on the mainline, thus the recommendation for /merging from trunk/. *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 *** Having a separate branch for 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. To this purpose, one can create a new branch for this kind of operations: #+BEGIN_SRC sh cd $DEVHOME/cedet bzr checkout bzr+ssh://USERNAME@cedet.bzr.sourceforge.net/bzrroot/cedet/code/trunk #+END_SRC Note that this branch is of a special kind called a /checkout/. The differences are that instead of /pulling from trunk/ you /update from trunk/ and committing changes immediately uploads them to the mainline. So, for each new change, you would: #+BEGIN_SRC sh bzr update # this is mandatory (updating from trunk) <> bzr update # this is optional, but will minimize # conflicts at commit bzr status # optionally see what has changed <> bzr commit #+END_SRC ** 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.