[petsc-dev] Summarizing history with topic branches

[Brad Aagaard]

Jed,

This is a nice summary of how to use this feature. Can you add it to the 
Wiki?

Thanks,
Brad


On 3/13/13 9:05 PM, Jed Brown wrote:
> 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
>