Re: Bazaar workflow for GRUB

[Colin D Bennett]

On Thu, 14 Jan 2010 15:01:41 +0530
BVK Chaitanya <address@hidden> wrote:

> Hi,
> 
> 
> Attached is the initial version of workflow document for GRUB
> contributions.  I am yet to get right DVCS right, so I suspect it
> might have minor differences from what other developers are following
> already.
> 
> Let me know your comments.
> 
> 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.

I would avoid using the word “checkout” except when an actual Bazaar
checkout (heavyweight or lightweight) is being used.  I think the
workflow you describe (avoiding checkouts) keeps things simpler since
checkouts behave differently than branches in some cases, and branches
with the “pull” command can do everything that a regular checkout can.

> 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

Why not use “bzr send -o ~/my-issue-fix.patch” to create a merge
directive+patch+revision bundle?  The benefit of bzr send over plain bzr
diff is that individual revisions within the change are preserved,
which can provide richer history.  Merge directives can simply be
applied with “bzr merge my-issue-fix.patch”.

As well as including detailed revision data (including file move/rename
operations), a merge directive also indicates to Bazaar the base
revision of GRUB trunk that the patch's revisions are made against;
making merging it much easier in case other changes have been made to
GRUB trunk in the interval before the patch is committed to trunk.
Bazaar will automatically do a real three-way merge with a merge
directive, whereas applying a patch with the regular “patch” command
would not have as much information and would make the user do much more
work in the even of a conflict.

It is also easy to discard sub-revisions when merging a revision bundle
into mainline, if for some reason the committer so desires.

> # 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:

I would recommend or at least mention the option of creating a shared
repository before branching the remote branch.  Whenever a branch is
downloaded to a directory underneath a shared repository in the
directory hierarchy, its revisions are stored in the shared repository
instead of directly in the branch directory.  This means the you can
cheaply clone the branch (or download other remote branches related to
it, for instance) and the common revisions will not be duplicated on
your hard disk or re-transferred across the network.

Before executing the “bzr branch” command, run “bzr init-repo .” in a
directory under which you wish to put your branches.  After this, all
other commands will be the same whether a shared repository is in use
or not.

> #+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

Again I would strongly recommend using bzr send instead of bzr 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.

Do you want to mention how GRUB committers should merge features to the
official trunk branch?  I think the appropriate process, assuming
(1) either a merge directive or a feature branch provides the change
the we want to merge, and (2) we already have a local mirror branch of
GRUB's trunk branch:

  # 1. Update local trunk mirror.
  cd trunk
  bzr pull

  # 2. Merge the feature branch or merge directive.
  bzr merge URL_OF_BRANCH
  # (Or bzr merge /path/to/merge_directive.patch)
  # If there are conflicts reported, fix them and use “bzr resolve” to
  # mark them as resolved.
  [ make grub ... and test it ]

  # 3. Commit the change locally.
  bzr commit

  # 4. Push to the upstream trunk.
  bzr push :parent
  #   (The :parent argument can be omitted after the first time you do
  #   this, since Bazaar will remember the given location from that
  #   point on as the “push location” for the local branch.)
  # Note that in the unlikely event that someone happened to commit to
  # upstream trunk in the meantime since you did “bzr pull”, Bazaar
  # will tell you that the branches have diverged.  You should try
  # again, doing “bzr pull --overwrite” and go back to step 2.

When you are done pushing your change to upstream trunk, running
“bzr missing” in your local trunk mirror should indicate there are no
extra or missing revisions in your local trunk.


Good work on the document!

Regards,
Colin

signature.asc
Description: PGP signature