gawkworkflow: General practices

1 
1 6 General Development Practices
1 *******************************
1 
1 This major node discusses general practices for 'gawk' development.  The
1 discussion here is mainly for developers with commit access to the
1 Savannah repo.
1 
1 "Propagating Fixes"
1      Usually, bug fixes should be made on the current "stable" branch.
1      Once a fix has been reviewed and approved, you can commit it and
1      push it yourself.  Typically, the maintainer then takes care to
1      merge the fix to 'master' and from there to any other branches.
1      However, you are welcome to save him the time and do this yourself.
1 
1 "Directory ownership"
1      Some developers "own" certain parts of the tree, such as the 'pc'
1      and 'vms' directories.  They are allowed to commit changes to those
1      directories without review by the mailing list, but changes that
1      also touch the mainline code should be submitted for review.
1 
1 "New feature development"
1      Unless you can convince the maintainer (and the other developers!)
1      otherwise, you should _always_ start branches for new features from
1      'master', and not from the current "stable" branch.
1 
1      Use 'checkout -b feature/FEATURE_NAME' to create the initial
1      branch.  You may then elect to keep it purely local, or to push it
1      up to Savannah for review, even if the feature is not yet totally
1      "ready for prime time."
1 
1    During development of a new feature, you will most likely wish to
1 keep your feature branch up to date with respect to ongoing improvements
1 in 'master'.  This is generally easy to do.  There are two different
1 mechanisms, and which one you use depends upon the nature of your new
1 feature branch.
1 
1 "As long as your branch is purely local"
1      You should use 'git rebase' to the keep the branch synchronized
1      with the original branch from which it was forked:
1 
1           $ git checkout master             Move to master
1           $ git pull                        Bring it up to date
1           $ git checkout feature/python     Move to your new feature branch
1           $ git rebase master               Rebase from master
1 
1      The rebasing operation may require that you resolve conflicts
1      (⇒Merge Conflicts).  Edit any conflicted files and resolve
1      the problem(s).  Compile and test your changes, then use 'git add'
1      and 'git commit' to indicate resolution, and then use 'git rebase
1      --continue' to continue the rebasing.  Git is very good about
1      providing short instructions on how to continue when such conflicts
1      occur.
1 
1 "Once the branch has been pushed up to Savannah"
1      You _must_ use 'git merge' to bring your feature branch up to date.
1      That flow looks like this:
1 
1           $ git checkout master             Move to master
1           $ git pull                        Bring it up to date
1           $ git checkout feature/python     Move to your new feature branch
1           $ git merge master                Merge from master
1 
11      Here too, you may have to resolve any merge conflicts (⇒Merge
      Conflicts).  Once that's done, you can push the changes up to
1      Savannah.
1 
1      When the changes on your branch are complete, usually the
1      maintainer merges the branch to 'master'.  But there's really no
1      magic involved, the merge is simply done in the other direction:
1 
1           $ git checkout feature/python     Checkout feature branch
1           $ git pull                        Bring it up to date
1           $ git checkout master             Checkout master
1           $ git pull                        Bring it up to date
1           $ git merge feature/python        Merge from feature/python into master
1 
1      If you've been keeping 'feature/python' in sync with 'master', then
1      there should be no merge conflicts to resolve, and you can push the
1      result to Savannah:
1 
1           $ git push                        Push up to Savannah
1 
1      Since 'feature/python' is no longer needed, it can be gotten rid
1      of:
1 
1           $ git branch -d feature/python                 Still on master, delete feature branch
1           $ git push -u origin --delete feature/python   Delete the branch on Savannah
1 
1      The 'git push' command deletes the 'feature/python' branch from the
1      Savannah repo.
1 
1      Finally, you should send an email to developer's list describing
1      what you've done so that everyone else can delete their copies of
1      the branch and do a 'git fetch --prune' (⇒Repo Maintenance).
1 
1      To update the other remaining development branches with the latest
1      changes on 'master', use the 'helpers/update-branches.sh' script in
1      the repo.
1