Project

General

Profile

Ceph contributors list maintenance guide » History » Version 18

Loïc Dachary, 05/14/2016 10:42 AM

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