git-workflow.md: Edited and expanded

Spell out the activities that contribute to Snabb Switch maintenance.

Revise the description of how to submit a change. Emphasise that the
goal is to land the change on a branch that somebody is going to merge
with master and once that is done you can mostly relax. (You don't
have to push your change for a whole month until it lands in a release
- only until somebody else merges it onto a branch that they are going
to push upstream.)

Rephase from role-oriented ("Casual users should do this") to
task-oriented ("How to download the latest release"). Ideally
everybody will be a user, developer, and maintainer to varying
extents.

src/doc/git-workflow.md

@@ -18,63 +18,69 @@ Snabb Switch development follows a few well-known patterns:
 
 ## HOWTO
 
-### For users
+### Download and update the latest release
 
 1. Clone the [SnabbCo/snabbswitch](/~https://github.com/SnabbCo/snabbswitch) repository.
 2. Check out and build the `master` branch.
 3. Pull when you want to update to the latest stable release.
 
-### For contributors
+### Develop and contribute an improvement
 
 1. [Create your own fork](https://help.github.com/articles/fork-a-repo/) of Snabb Switch on Github.
-2. Develop and debug your contribution on a new [topic branch](https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows#Topic-Branches).
+2. Develop and debug your contribution on a new [topic branch](https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows#Topic-Branches) based on the latest `master`.
 3. Make a final cleanup of your code before review. (Last chance to rebase.)
 4. Submit a Github [Pull Request](https://help.github.com/articles/using-pull-requests/#initiating-the-pull-request)
-   to the master branch.
+   to the `master` branch.
 5. Respond to feedback and correct problems by pushing additional commits.
 
-There are two milestones in the process of your accepting your contribution:
+There are two milestones in the process of accepting your change:
 
-1. Your work is merged onto `next` to be tested for inclusion in the next release.
-2. Your work is released by merge onto `master`.
+1. Your change is merged onto a branch that feeds `master`, for
+   example `next`, `fixes`, `documentation-fixes`, or `nfv`. From this
+   point the owner of that branch will push your work upstream
+   together with other related changes. They might ask you for help
+   but otherwise your work is done.
+2. Your change is merged onto `master`. This could happen in a series
+   of merge steps, for example `nfv->next->master`. Once this happens
+   your code has been officially released as part of Snabb Switch.
 
-Your Pull Request will automatically close when the contribution has
-been released. The whole process should take about one month from
-initial contribution to inclusion in an official release.
+### Develop and maintain a new program
 
-### For application developers
+Snabb Switch includes programs like `snabbnfv`, `packetblaster`, and
+`snsh`. Here is how you can create a new program and take charge of
+its development.
 
 1. [Fork](https://help.github.com/articles/fork-a-repo/) your own
    repository on Github.
-2. Create a [long-lived branch](branches.md) where new development of your application will be done.
-3. Create a directory `src/program/myapplication/` and develop your application.
+2. Create a [long-lived branch](branches.md) where new development of your program will be done.
+3. Create a directory `src/program/myapplication/` and develop your program.
 4. `git merge master` regularly to stay synchronized with the main line of development.
-5. Optional: Send releases of your application to master with Pull Requests.
+5. Optional: Send releases of your application to `master` with Pull Requests.
 
 The code in your `src/program/myapplication/` directory is developed
 according to your own rules and tastes. If there are parts of this
 code that you especially want to have reviewed (or do not want to have
 reviewed) then please explain this in your Pull Request. The only
-necessary review is to make sure that applications do not negatively
+necessary review is to make sure that programs do not negatively
 impact each other or change shared code without enough review.
 
-Common Snabb Switch code should be updated with individual changes
-according to the *For contributors* workflow. Please do not bundle
-substantial changes to the core software with updates to the
-application.
+Pull Requests that make changes to your application will be referred
+to you for merge onto your branch.
 
-If you do not want to include your application in the main Snabb
-Switch release then this is no problem. You can simply pull from the
-master branch to receive updates and skip the step of pushing back.
+Use the *Develop and contribute an improvement* workflow to make
+changes to the core Snabb Switch code. Please do not bundle
+substantial changes to the core software with updates to your program.
 
-### For maintainers
+If you do not want to include your program in the main Snabb Switch
+release then this is no problem. You can simply pull from `master` to
+receive updates and skip the step of pushing back.
 
-Goals:
+### To help maintain Snabb Switch
 
-1. Quickly merge good features onto the `next` branch.
-2. Quickly merge good bug fixes onto the `fixes` branch.
-3. Make sure `next` is stable when it is time to make a release.
-4. Merge `next` and `fixes` merge to master according to the release schedule.
+Here are the best ways to help maintain Snabb Switch:
 
-More verbiage to follow...
+1. Review Pull Requests to help people quickly improve them.
+2. Test the `next` branch and help fix problems before releases.
+3. Contribute new `selftest` cases to make our CI more effective.
+4. Maintain a [branch](branches.md) where you accept Pull Requests and push them upstream.