Project

General

Profile

Ceph contributors list maintenance guide » History » Version 6

Loïc Dachary, 07/25/2015 11:37 AM
attach credits.sh script

1 3 Loïc Dachary
h3. Ceph contributors list maintenance guide
2 1 Jessica Mack
3 1 Jessica Mack
h3. Introduction
4 1 Jessica Mack
5 1 Jessica Mack
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.
6 1 Jessica Mack
Immediately after each Ceph release, an "acknowledgement of the contributors who participated":http://www.spinics.net/lists/ceph-devel/msg18941.html can be published.
7 1 Jessica Mack
8 1 Jessica Mack
h3. Published contributor credits
9 1 Jessica Mack
10 1 Jessica Mack
* 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:
11 1 Jessica Mack
** v9.0.2 Abhishek L: <abhishek.lekshmanan@gmail.com>
12 5 Loïc Dachary
** v9.0.3 Loic Dachary: <loic@dachary.org>
13 5 Loïc Dachary
** v9.0.4 M Ranga Swami Reddy: <swamireddy@gmail.com>
14 5 Loïc Dachary
** v9.0.5 Yann Dupont: <yann@objoo.org>
15 1 Jessica Mack
* "Ceph Metrics":http://metrics.ceph.com/scm.html
16 1 Jessica Mack
17 1 Jessica Mack
h3. Display the contributor list
18 1 Jessica Mack
19 1 Jessica Mack
*Note: The check-mailmap command requires git version 1.9 or higher.*
20 6 Loïc Dachary
The attachment:credits.sh script (attached to this page) can be called with
21 1 Jessica Mack
22 2 Jessica Mack
p(((. @./credits.sh tags/v0.83..origin/next@
23 1 Jessica Mack
24 1 Jessica Mack
to show contributors who authored commits between v0.83 and the master branch.
25 1 Jessica Mack
26 1 Jessica Mack
h3. Fixing the contributor list
27 1 Jessica Mack
28 1 Jessica Mack
When looking at the Commits by organizations displayed by the credits.sh script. For instance if it shows
29 1 Jessica Mack
30 2 Jessica Mack
p(((. @Commits by organizations
31 1 Jessica Mack
...
32 1 Jessica Mack
     4         19 Intel <contact@intel.com>
33 1 Jessica Mack
...
34 1 Jessica Mack
     9          5 xinxin shu <xinxin.shu@intel.com>
35 1 Jessica Mack
...
36 1 Jessica Mack
    17          2 xinxinsh <xinxin.shu@intel.com>
37 2 Jessica Mack
    18          2 Xiaoxi Chen <xiaoxi.chen@intel.com>@
38 1 Jessica Mack
...
39 1 Jessica Mack
40 1 Jessica Mack
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 .
41 1 Jessica Mack
The following oneliner can be used to spot duplicates in the Commits by authors instead of looking for them manually:
42 1 Jessica Mack
43 1 Jessica Mack
44 2 Jessica Mack
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/'@
45 1 Jessica Mack
46 1 Jessica Mack
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.
47 1 Jessica Mack
48 1 Jessica Mack
h3. Commit conventions
49 1 Jessica Mack
 
50 1 Jessica Mack
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.
51 1 Jessica Mack
The subject of the commit message is usually *mailmap: Firstname Lastname affiliation* which is helpful for scripting.
52 1 Jessica Mack
There is one commit per author because this helps the author review the change related to her / his contribution without considering unrelated changes.
53 1 Jessica Mack
Here is an example of commit https://github.com/ceph/ceph/commit/...dd6e547828df41
54 1 Jessica Mack
55 1 Jessica Mack
h3. Mail notification to the author about an update
56 1 Jessica Mack
57 1 Jessica Mack
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:
58 1 Jessica Mack
59 2 Jessica Mack
p(((. @Subject: Ceph contributions : organization affiliation
60 1 Jessica Mack
BCC: loic-bcc@dachary.org
61 1 Jessica Mack
Hi,
62 1 Jessica Mack
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:
63 1 Jessica Mack
    https://github.com/dachary/ceph/commit/{HASH}
64 1 Jessica Mack
This work is done to publish a map of Ceph contributors, as well as the organizations to which they are affiliated.
65 1 Jessica Mack
Cheers
66 1 Jessica Mack
[1] http://ceph.com/
67 2 Jessica Mack
[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@
68 1 Jessica Mack
69 1 Jessica Mack
Sending these emails can be automated with:
70 1 Jessica Mack
71 2 Jessica Mack
p(((. @git log --pretty='%H %s' @{u}..  | # assume all commit subjects contain the author@
72 2 Jessica Mack
  @sed -e 's/affiliation//' -e 's/name normalization//' | # remove subject noise@
73 2 Jessica Mack
  @while read hash mailmap name ; do@
74 2 Jessica Mack
    @to=$(sed -ne "s/.*$name/$name/p" < .organizationmap | head -1) # fetch the author mail@
75 2 Jessica Mack
    @echo "$to" # debug information@
76 2 Jessica Mack
    @( echo "To: $to"@
77 2 Jessica Mack
      @sed -e "s/{HASH}/$hash/" < mailmap.txt # the template mail above@
78 2 Jessica Mack
    @) | # create the mail from the template@
79 2 Jessica Mack
    @sendmail -v -F 'Loic Dachary' -f 'loic@dachary.org' -t@
80 2 Jessica Mack
  @done@
81 1 Jessica Mack
82 1 Jessica Mack
The Reviewed-by: field is added to the commit message when the author answers.
83 1 Jessica Mack
84 1 Jessica Mack
h3. Affiliation change over time
85 1 Jessica Mack
86 1 Jessica Mack
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:
87 1 Jessica Mack
88 2 Jessica Mack
p(((. @David Zafman <dzafman@redhat.com> David Zafman <david.zafman@inktank.com>
89 2 Jessica Mack
John Spray <jspray@redhat.com> John Spray <john.spray@inktank.com>@
90 1 Jessica Mack
...
91 1 Jessica Mack
92 1 Jessica Mack
h3. Sponsoring organizations
93 1 Jessica Mack
94 1 Jessica Mack
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:
95 1 Jessica Mack
 
96 2 Jessica Mack
p(((. @Unaffiliated <no@organization.net> Michael Nelson <mikenel@tnld.net>
97 2 Jessica Mack
Unaffiliated <no@organization.net> Michael Riederer <michael@riederer.org>@
98 1 Jessica Mack
99 1 Jessica Mack
h3. Sorting entries
100 1 Jessica Mack
101 1 Jessica Mack
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.
102 1 Jessica Mack
103 1 Jessica Mack
h3. HOWTO maintain the contributor list
104 1 Jessica Mack
105 1 Jessica Mack
# Run *./credits.sh origin/firefly...origin/master* on a fresh checkout of the master branch
106 1 Jessica Mack
# Check each entry in the *Commits by authors* section for lines that show the same author under two mails
107 1 Jessica Mack
** If the duplicate is an accident *update the .mailmap* to map the two names into one
108 1 Jessica Mack
** If the duplicate is intentional (change of organization) *update the .peoplemap* to map the two names into one
109 1 Jessica Mack
# Check each entry in the *Commits by organizations* section for lines that shows an author instead of an organization
110 1 Jessica Mack
** Look for the name in *git log --pretty='%aN <%aE>' | sort | uniq*
111 1 Jessica Mack
** If the *author is found under a different name, update the .mailmap* to map the two names into one
112 1 Jessica Mack
** If the *author is not found, update the .organizationmap* with the organization sponsoring the commit
113 1 Jessica Mack
** Commit the change with a subject *mailmap: Firstname Lastname affiliation*
114 1 Jessica Mack
** Go back to step 1
115 1 Jessica Mack
# Send a pull request with all commits with a cover *DNM: mailmap updates* to avoid duplicated work
116 1 Jessica Mack
# Send a mail to each author with a link to the commit of their update for review
117 1 Jessica Mack
# When an author replies
118 1 Jessica Mack
** If modifications are suggested, *amend the commit*
119 1 Jessica Mack
** Update the commit message with *Reviewed-by: Firstname Lastname <email>*
120 1 Jessica Mack
** *git push --force* so the change shows in the pull request
121 1 Jessica Mack
** Reply with a link to the updated commit
122 1 Jessica Mack
# A week after sending the mails, merge all updates
123 1 Jessica Mack
# 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 )
124 1 Jessica Mack
# Update the schedule at https://wiki.ceph.com/Community/Ceph...ntenance_guide