[petsc-dev] Summarizing history with topic branches

[Jed Brown]

We now have an early example of the ability of topic branches to provide
summaries. To start with, what is in 'barry/ams', but not in master?

$ git log --abbrev-commit --pretty=oneline master..barry/ams
0acecf5 add AMS viewer for PC, server can only run without any memory debugging
f05ece3 changed AMS publishing to use the Viewer model [...]
dbbc0cd Merge branch 'barry/convergence-history' into barry/ams
bfb9721 more work on moving AMS model to viewer
7a1ec6d Fix for SNESSetConvergenceHistory() when input a is null
ce8c27f fixed calls to PetscObjectAMSTake/GrantAccess() to cast first argument to PetscObject
c8b2999 Merge branch 'master' into barry/ams
a75c43b make KSP AMS monitor use default AMS communicator
38dc153 cleanup of AMS viewer, handle JSON-RPC multiple Comms
ec7429e work on AMS interface, consistent naming, ams.h not included in petscviewer.h, no ifdefs


I clipped the extremely long line [1] which makes the summary hard to
read. Note that this commit is shown:

7a1ec6d Fix for SNESSetConvergenceHistory() when input a is null

It came into the topic branch via a merge declaring this bug fix as a
dependency:

dbbc0cd Merge branch 'barry/convergence-history' into barry/ams

Merges can bring in many more commits so if we want to only see the
commits that are *part* of the feature 'barry/ams' (not just a
dependency), we can add '--first-parent' [2]:

$ git log --abbrev-commit --pretty=oneline --first-parent master..barry/ams

which shows the same as above, minus the bug fix commit. It still
includes the two merges, which we can screen out by adding '--no-merges'
to see only the "interesting" commits. That gives:

$ git log --abbrev-commit --first-parent --no-merges --pretty=oneline master..barry/ams
0acecf5 add AMS viewer for PC, server can only run without any memory debugging
f05ece3 changed AMS publishing to use the Viewer model [...]
bfb9721 more work on moving AMS model to viewer
ce8c27f fixed calls to PetscObjectAMSTake/GrantAccess() to cast first argument to PetscObject
a75c43b make KSP AMS monitor use default AMS communicator
38dc153 cleanup of AMS viewer, handle JSON-RPC multiple Comms
ec7429e work on AMS interface, consistent naming, ams.h not included in petscviewer.h, no ifdefs

This is a nice compact summary of what happened on 'barry/ams'. We can
add '--stat' for a diffstat of each commit or '-p' for the body of those
changes.

Following the first parent along an integration branch gives a nice
summary of what is currently there, e.g., these topics are cooking in
'next':

$ git log --abbrev-commit --first-parent --pretty=oneline master..next
e5e0692 Merge branch 'barry/ams' into next
d8866d7 Merge knepley/plex into next
2f878aa Merge branch 'barry/convergence-history' into next
4a37446 pulled next from bitbucket Merge branch 'next' of bitbucket.org:petsc/petsc into next
a42e7c1 AMS fixed now goes into next Merge branch 'barry/ams' into next
8de993d Bug fix for MatLoad_MPIBAIJ() buffer size for rank zero read was wrong size; [...]


This first-parent summary was interrupted by 4a37446, which was created
by a "race" merging to 'next'. It's possible to resolve those races
[2,3], but they should be rare if maintainers always 'git pull' before
merging to an integration branch. If not for that race (and using the
first line from the default merge commit message), the above would have
looked like:

e5e0692 Merge branch 'barry/ams' into next
d8866d7 Merge branch 'knepley/plex' into next
2f878aa Merge branch 'barry/convergence-history' into next
f37663b Merge branch 'barry/matload-mpiaj-bugfix-maint' into next
a42e7c1 Merge branch 'barry/ams' into next


Our new "topic branch" workflow provides many quick ways to summarize
history. Consistent structure in commit messages and following merging
principles makes those summaries more useful and easier to read. Matt is
currently beating all of us in terms of consistent commit message
structure (play around with 'git shortlog' over recent history).


[1] The full line is (all on one line)

f05ece3 changed AMS publishing to use the Viewer model added simple AMS viewer for mat,ksp,snes,ts added --ksp/snes/ts_view_pre for starting the viewer before the solve (ugly but useful for AMS) added PetscStackCalls around AMS function calls when appropriate (note do not want these in webserver because do not webserver stopping just because AMS server is down

https://bitbucket.org/petsc/petsc/commits/f05ece33fd483fcf0ae47f3ecf85fefd993a83b6

If Barry had left a blank line after the subject, it would display
nicely on one line.

https://bitbucket.org/petsc/petsc/wiki/writing-commit-messages    


[2] http://git-blame.blogspot.com/2012/03/fun-with-first-parent.html
[3] https://plus.google.com/107978208786843979508/posts/5idXQ5MJ8wU