gawkworkflow: General practices
6 General Development Practices
*******************************
This major node 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 '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
(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 (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 -d feature/python Still on master, delete feature branch
$ git push -u origin --delete feature/python Delete the branch 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' (Repo Maintenance).
To update the other remaining development branches with the latest
changes on 'master', use the 'helpers/update-branches.sh' script in
the repo.