Ceph

h3. Ceph contributors list maintenance guide

h3. Introduction

The "mailmap":https://www.kernel.org/pub/software/scm/git/docs/git-shortlog.html#_mapping_authors file fixes spelling mistakes in commit authors names or emails. It can also be used to map authors to organizations sponsoring their commits. For instance the ".mailmap file":https://github.com/ceph/ceph/blob/master/.mailmap found in the Ceph repository normalizes author names and is piped to the ".organizationmap file":https://github.com/ceph/ceph/blob/master/.organizationmap to map them to the sponsoring organizations.

Immediately after each Ceph release, an "acknowledgement of the contributors who participated":http://www.spinics.net/lists/ceph-devel/msg18941.html can be published.

h3. Published contributor credits

* After a Ceph release is announced, a mail is sent to the ceph-devel mailing list (for example "acknowledgement of the contributors who participated":http://www.spinics.net/lists/ceph-devel/msg18941.html ). The contributor list for the next Ceph releases are going to be published by:

** v11.2.0 Abhishek L: <abhishek.lekshmanan@gmail.com>

** v12.0.0 Loic Dachary: <loic@dachary.org>

** v12.0.1 M Ranga Swami Reddy: <swamireddy@gmail.com>

** v12.0.2 Abhishek L: <abhishek.lekshmanan@gmail.com>

* "Ceph Metrics":http://metrics.ceph.com/scm.html

h3. Display the contributor list

*Note: The check-mailmap command requires git version 1.9 or higher.*

The "credits.sh":https://github.com/ceph/ceph/tree/master/src/script/credits.sh script (/src/script/credits.sh in main Ceph repo) can be called with

p(((. @./credits.sh tags/v0.83..origin/next@

to show contributors who authored commits between v0.83 and the master branch.

h3. Fixing the contributor list

When looking at the Commits by organizations displayed by the credits.sh script. For instance if it shows

p(((. @Commits by organizations

...

     4         19 Intel <contact@intel.com>

...

     9          5 xinxin shu <xinxin.shu@intel.com>

...

    17          2 xinxinsh <xinxin.shu@intel.com>

    18          2 Xiaoxi Chen <xiaoxi.chen@intel.com>@

...

Because of the domain name, the contributions of Shu Xinxin and Chen Xiaoxi should be counted for Intel and that can be fixed by "updating the .organizationmap":https://github.com/dachary/ceph/commit/55227aaeec3f524e1b2aaeb83214b2d7089e4296#diff-dab6a7efce64a6e066009e19abaf8da1R114 . The two lines showing Shu Xinxin contributions instead of one come from the fact that two different names were used and that can be fixed by "updating the .mailmap":https://github.com/dachary/ceph/commit/55227aaeec3f524e1b2aaeb83214b2d7089e4296#diff-c9d540715cff3469b65ddd01f614848bR120 .

The following oneliner can be used to spot duplicates in the Commits by authors instead of looking for them manually:

p(((. @git log --pretty='%aN <%aE>' $range | git -c mailmap.file=.peoplemap check-mailmap --stdin | sort | uniq | sed -e 's/\(.*\) \(<.*\)/\2 \1/' | uniq --skip-field=1 --all-repeated | sed -e 's/\(.*>\) \(.*\)/\2 \1/'@

It will for instance show Ross Turk twice, once with his Inktank email and another with his Red Hat email. These must not be normalized in the .mailmap because the contributions are affiliated to two different organizations. Instead it can be added to the .peoplemap.

h3. Commit conventions

The commit message starts with *mailmap*: prefix and it allows people working on Ceph to quickly identify the commits related to the maintenance of the contributor list. Although it may involve modifying more than just the *.mailmap* file, the prefix stays the same.

The subject of the commit message is usually *mailmap: Firstname Lastname affiliation* which is helpful for scripting.

There is one commit per author because this helps the author review the change related to her / his contribution without considering unrelated changes.

Here is an example of commit https://github.com/ceph/ceph/commit/...dd6e547828df41

h3. Mail notification to the author about an update

It is best to send "a pull request with one commit per author":https://github.com/ceph/ceph/pull/2273 so that they can be reviewed independently. A mail should be sent to the author to review the update. For example:

p(((. @Subject: Ceph contributions : organization affiliation

BCC: loic-bcc@dachary.org

Hi,

You are participating in the making of Ceph[1]. The mailmap files[2] were updated to reflect your affiliation and possibly to normalize your mail, in case it was misspelled. You can verify the update at:

    https://github.com/dachary/ceph/commit/{HASH}

This work is done to publish a map of Ceph contributors, as well as the organizations to which they are affiliated.

Cheers

[1] http://ceph.com/

[2] https://github.com/ceph/ceph/blob/master/.mailmap and https://github.com/ceph/ceph/blob/master/.peoplemap and https://github.com/ceph/ceph/blob/ma...rganizationmap@

Sending these emails can be automated with:

p(((. @git log --pretty='%H %s' @{u}..  | # assume all commit subjects contain the author@

  @sed -e 's/affiliation//' -e 's/name normalization//' | # remove subject noise@

  @while read hash mailmap name ; do@

    @to=$(sed -ne "s/.*$name/$name/p" < .organizationmap | head -1) # fetch the author mail@

    @echo "$to" # debug information@

    @( echo "To: $to"@

      @sed -e "s/{HASH}/$hash/" < mailmap.txt # the template mail above@

    @) | # create the mail from the template@

    @sendmail -v -F 'Loic Dachary' -f 'loic@dachary.org' -t@

  @done@

The Reviewed-by: field is added to the commit message when the author answers.

h3. Affiliation change over time

A given email reflects the affiliation of an author. There is no way to say, for instance, that loic@dachary.org is affiliated to Cloudwatt until August 2014 and to Red Hat after this date. To avoid duplicates in the author list, the .peoplemap file is updated and will be used by the credits.sh script above:

p(((. @David Zafman <dzafman@redhat.com> David Zafman <david.zafman@inktank.com>

John Spray <jspray@redhat.com> John Spray <john.spray@inktank.com>@

...

h3. Sponsoring organizations

Searching internet to find the current employer of the author is likely to be the simplest method to discover the organization sponsoring the commit. Note that organizations can be either companies, non-profit organzations or government agencies. If nothing shows up or if the author does this as a hobby, she/he should be listed as unaffiliated in the .organizationmap file such as:

p(((. @Unaffiliated <no@organization.net> Michael Nelson <mikenel@tnld.net>

Unaffiliated <no@organization.net> Michael Riederer <michael@riederer.org>@

h3. Sorting entries

The .organizationmap, .peoplemap and .mailmap content should be alphabetically sorted because it makes it easier to spot unintended duplicates and it reduces the risk of a merge conflict.

h3. HOWTO maintain the contributor list

# Run *./credits.sh origin/firefly...origin/master* on a fresh checkout of the master branch

# Check each entry in the *Commits by authors* section for lines that show the same author under two mails

** If the duplicate is an accident *update the .mailmap* to map the two names into one

** If the duplicate is intentional (change of organization) *update the .peoplemap* to map the two names into one

# Check each entry in the *Commits by organizations* section for lines that shows an author instead of an organization

** Look for the name in *git log --pretty='%aN <%aE>' | sort | uniq*

** If the *author is found under a different name, update the .mailmap* to map the two names into one

** If the *author is not found, update the .organizationmap* with the organization sponsoring the commit

** Commit the change with a subject *mailmap: Firstname Lastname affiliation*

** Go back to step 1

# Send a pull request with all commits with a cover *DNM: mailmap updates* to avoid duplicated work

# Send a mail to each author with a link to the commit of their update for review

# When an author replies

** If modifications are suggested, *amend the commit*

** Update the commit message with *Reviewed-by: Firstname Lastname <email>*

** *git push --force* so the change shows in the pull request

** Reply with a link to the updated commit

# A week after sending the mails, merge all updates

# After the announcement of a Ceph release, send the mail to ceph-devel, including the output of *./credits.sh tags/previous-version...tags/released-version* ( for instance ./credits.sh tags/v0.85...tags/v0.86 )

# Update the schedule at https://wiki.ceph.com/Community/Ceph...ntenance_guide