6 General Development Practices

This chapter discusses general practices for gawk development. The discussion here is mainly for developers with commit access to the Savannah repo.

Propagating Fixes

Usually, bug fixes should be made on the current “stable” branch. Once a fix has been reviewed and approved, you can commit it and push it yourself. Typically, the maintainer then takes care to merge the fix to master and from there to any other branches. However, you are welcome to save him the time and do this yourself.

Directory ownership

Some developers “own” certain parts of the tree, such as the pc and vms directories. They are allowed to commit changes to those directories without review by the mailing list, but changes that also touch the mainline code should be submitted for review.

New feature development

Unless you can convince the maintainer (and the other developers!) otherwise, you should always start branches for new features from master, and not from the current “stable” branch.

Use ‘git checkout -b feature/feature_name’ to create the initial branch. You may then elect to keep it purely local, or to push it up to Savannah for review, even if the feature is not yet totally “ready for prime time.”

During development of a new feature, you will most likely wish to keep your feature branch up to date with respect to ongoing improvements in master. This is generally easy to do. There are two different mechanisms, and which one you use depends upon the nature of your new feature branch.

As long as your branch is purely local

You should use ‘git rebase’ to the keep the branch synchronized with the original branch from which it was forked:

$ git checkout master             Move to master
$ git pull                        Bring it up to date
$ git checkout feature/python     Move to your new feature branch
$ git rebase master               Rebase from master

The rebasing operation may require that you resolve conflicts (see Dealing With Merge Conflicts). Edit any conflicted files and resolve the problem(s). Compile and test your changes, then use ‘git add’ and ‘git commit’ to indicate resolution, and then use ‘git rebase --continue’ to continue the rebasing. Git is very good about providing short instructions on how to continue when such conflicts occur.

Once the branch has been pushed up to Savannah

You must use ‘git merge’ to bring your feature branch up to date. That flow looks like this:

$ git checkout master             Move to master
$ git pull                        Bring it up to date
$ git checkout feature/python     Move to your new feature branch
$ git merge master                Merge from master

Here too, you may have to resolve any merge conflicts (see Dealing With Merge Conflicts). Once that’s done, you can push the changes up to Savannah.

When the changes on your branch are complete, usually the maintainer merges the branch to master. But there’s really no magic involved, the merge is simply done in the other direction:

$ git checkout feature/python     Checkout feature branch
$ git pull                        Bring it up to date
$ git checkout master             Checkout master
$ git pull                        Bring it up to date
$ git merge feature/python        Merge from feature/python into master

If you’ve been keeping ‘feature/python’ in sync with master, then there should be no merge conflicts to resolve, and you can push the result to Savannah:

$ git push                        Push up to Savannah

Since ‘feature/python’ is no longer needed, it can be gotten rid of:

$ git branch                                  Still on master
  …
* master
$ git branch -d feature/python                Delete feature branch
$ git push -u origin --delete feature/python  Delete on Savannah

The ‘git push’ command deletes the feature/python branch from the Savannah repo.

Finally, you should send an email to developer’s list describing what you’ve done so that everyone else can delete their copies of the branch and do a ‘git fetch --prune’ (see Keeping Your Repo Organized).

To update the other remaining development branches with the latest changes on master, use the ‘helpers/update-branches.sh’ script in the repo.