GNU GRUB Workflow

GNU GRUB project recently switched its VCS from subversion to modern
distributed VCS, Bazaar.  Distributed nature of Bazaar provides much
better support for working off-line and independently than Subversion.
So GRUB developers now recommend below workflows for contributors.

* For Occasional Contributors

This workflow is recommended for users/developers who want to fix
just-one GRUB issue.  This involves a trunk checkout, some local
commits (as necessary for fixing the issue) and sending the patch to
[[http://lists.gnu.org/archive/html/grub-devel][grub-devel]] mailing list.  GRUB maintainers would take care of
committing it to the trunk.

If any changes are suggested by others in the mailing list, developer
can then implement them as many times as necessary and can send the
updated patch.

Note that, since GNU GRUB project is based on volunteer work, a patch
may not immediately get committed into the trunk.  So after a patch is
mailed to the mailing list and accepted by others, it is safe to
assume it would be eventually gets committed to the trunk.

An example workflow would look as below:

#+BEGIN_SRC shell-script
$ bzr branch http://bzr.savannah.gnu.org/r/grub/trunk/grub grub
$ cd grub

# ... hack hack hack ...
grub$ bzr commit -m 'fixed my issue'

# ... ah, you forgot adding somefile ...
grub$ bzr commit -m 'added missing somefile'

# create a patch and send to mailing list
grub$ bzr diff -r submit: > ~/my-issue-fix.diff

# update as per review comments
grub$ bzr commit  -m 'updated as per review comments'

# create a new patch and resend to mailing list
grub$ bzr diff -r submit: > ~/my-issue-fix-updated.diff
#+END_SRC

Notice that GRUB 2 is =trunk/grub= directory, instead of =trunk= itself.


* For Regular GRUB Contributors

Regular GRUB developers are advised to work in separate branches for
each bug fix or feature they work on.  They need to merge the trunk
periodically into their branches until their work gets reviewed and
merged into the trunk.  So it would be more beneficial to keep a
pristine trunk locally.

For example:

#+BEGIN_SRC shell-script
# Make a pristine trunk mirror
$ bzr branch sftp://address@hidden/srv/bzr/grub/trunk/grub/ trunk

# Create feature branches from trunk
$ bzr branch trunk feature-foo
$ cd feature-foo

# ... hack on feature-foo ...
feature-foo$ bzr commit -m 'initial foo support
# ... hack more ...
feature-foo$ bzr commit -m 'more of foo'

# create a patch for review
feature-foo$ bzr diff -r submit: > ~/feature-foo.diff

# add code review suggestions
feature-foo$ bzr commit -m 'added code review suggestions'

# its too long, pull-in trunk
feature-foo$ bzr merge ../trunk

# resolve conflicts
feature-foo$ bzr commit -m 'merged trunk'

# send updated patch for review again
feature-foo$ bzr diff -r submit: > ~/feature-foo-updated.diff

# when review finishes, push it to branches
feature-foo$ bzr push sftp://address@hidden/srv/bzr/grub/branches/feature-foo
#+END_SRC

Workflow for multiple features would also look similar to above,
except that pristine trunk checkout is not necessary.

Sometimes it might be useful to push partially complete feature
branches to bzr.sv.gnu.org/srv/bzr/grub/branches before it can be
reviewed.

** Experimental Branch

When a feature development is complete, i.e. code is reviewed and
accepted, it goes through a staging branch, =experimental= where it
gets tested for sometime before it is migrated into the trunk.

This staging area would allow the trunk branch always in a valid and
releasable state.

** Handling inter-dependent features

Sometimes one feature may depend on another feature which is not yet
merged into the trunk; in these scenarios also, it is advised to
create all feature branches from trunk.  A dependant branch can pull
in its dependencies appropriately.

A dependant branch can be committed to trunk only after all feature
branches it depends on are committed into trunk.  Any changes happened
in its dependencies can be pulled in later by performing a periodic
trunk merge.

Taking =bzr diff= of a feature branch can become tricky if it has
merges from multiple feature branches, so developers should try to
minimize such dependencies across features.

** Using Per Developer Branches

GRUB developers can make use per developer branches to share their
incomplete works with others or to be able to work from different
machines at different places.  After creating a per developer branch,
following /centralized/ workflow model using "bzr checkout" is
sufficient.

For example:

#+BEGIN_SRC shell-script

# Create a per developer branch
$ bzr branch sftp://address@hidden/srv/bzr/grub/trunk/grub/ \
    sftp://address@hidden/srv/bzr/grub/branches/feature-foo

# Checkout a copy
$ bzr checkout sftp://address@hidden/srv/bzr/grub/branches/feature-foo
$ cd feature-foo

# ... hack hack hack ...
feature-foo$ bzr commit -m 'commit message'
#+END_SRC

In this model, every =bzr commit= updates the repository at the
server.  In cases when internet connection is not available,
developers can make use of "bzr commit --local" command to commit
locally.