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 |