Adding contributors and verifying with git blame

In EGSnrc files, there is a list contributors in each file's masthead, under Contributors:, below the Author: section.

Adding contributors

EGSnrc has a venerable history, with many people contributing to files over time, well before EGSnrc was ported to git in 2015, and indeed well before the advent of the personal computer! Moreover, EGSnrc might not be versioned under git forever, so at any rate the list of contributors ought to be spelled out explicitly in the file and updated.

There is some ambiguity as to what constitutes a contribution. But keep in mind that this is not an acknowledgment section (though one can be added to the masthead to acknowledge people who contributed otherwise). At the very least, contributors should have in fact modified the content of the file. Conversely, fixing a small typo in a comment or adjusting white space is not worthy of adding a name to the contributor list.

Adding a contributor name remains a judgment call. The overarching recommendation is to add anyone who modifies the file to the list of contributors, even for small functional changes, so as to not diverge from git blame (see below). Again, this is not a recognition section: it serves as a manual record of who modified the file.

Missing contributors

Keeping the list of contributors up-to-date requires attention when merging pull requests, thus oversight is possible. If you know of a contributor name missing (including your own!) from the contributor list in an EGSnrc file, especially historical ones, please let us know! Upon porting to git in 2015, we combed through different legacy version control software archives to recover all contributor names as best we could, but we expect there are a few omissions.

Checking contributors with git

In git, it is possible to check who modified a given file with git log (or git show, git diff, etc.). More comprehensively, the git blame command provides a line-by-line account of changes in a file, listing the commit hash, author and time stamp for each line. See git blame -h for output options; in particular the --color-lines --color-by-age are helpful visually. Thus it is possible to extract from the git blame output unique author names and compare it with the names listed in the file masthead.

Example

For example, let's look at the core EGSnrc mortran source file in HEN_HOUSE/src/egsnrc.mortran:

git blame egsnrc.mortran | cut -d" " -f2-3 | cut -b2- | sort | uniq

Blake Walters
Ernesto 
Ernesto Mainegra
Ernesto Mainegra-Hing
Frederic Tessier
Frédéric Tessier
Reid Townson
victorMalkov

Here we see that some authors have had different user names over time, but that's fine. Now we can compare this git blame output with the list of contributors inside the file masthead, as in:

sed -n '/Contributors:/,/...###/p' egsnrc.mortran 

"  Contributors:    Ernesto Mainegra-Hing                                     "
"                   Blake Walters                                             "
"                   Frederic Tessier                                          "
"                   Reid Townson                                              "
"                   Victor Malkov                                             "
"                                                                             "
"#############################################################################"

This confirm that all everyone who modified egsnrc.mortran (since 2015, when EGSnrc was ported to git) is accounted for in the file. Note that contributor names should never be removed from the file to match the git blame output because, again, past contributors are not known to git, and some contributors may submit their changes via other means than a pull request.