Ceph contributors list maintenance guide » History » Version 32
Anthony D'Atri, 08/08/2023 03:29 PM
1 | 3 | Loïc Dachary | h3. Ceph contributors list maintenance guide |
---|---|---|---|
2 | 1 | Jessica Mack | |
3 | h3. Introduction |
||
4 | |||
5 | 32 | Anthony D'Atri | 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 email addresses. 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 | |||
8 | h3. Published contributor credits |
||
9 | |||
10 | 27 | Anthony D'Atri | * After a Ceph release is announced, a message 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 | 1 | Jessica Mack | ** v12.0.2 Abhishek L: <abhishek.lekshmanan@gmail.com> |
13 | 24 | Swami Reddy | ** v12.0.4 M Ranga Swami Reddy: <swamireddy@gmail.com> |
14 | 15 | Loïc Dachary | |
15 | 1 | Jessica Mack | * "Ceph Metrics":http://metrics.ceph.com/scm.html |
16 | |||
17 | h3. Display the contributor list |
||
18 | |||
19 | *Note: The check-mailmap command requires git version 1.9 or higher.* |
||
20 | 20 | Patrick McGarry | 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 |
21 | 1 | Jessica Mack | |
22 | 2 | Jessica Mack | p(((. @./credits.sh tags/v0.83..origin/next@ |
23 | 1 | Jessica Mack | |
24 | 32 | Anthony D'Atri | to show contributors who authored commits between v0.83 and the main branch. |
25 | 1 | Jessica Mack | |
26 | h3. Fixing the contributor list |
||
27 | |||
28 | 32 | Anthony D'Atri | When looking at the Commits by organizations displayed by the @credits.sh@ script. For example: |
29 | 1 | Jessica Mack | |
30 | 2 | Jessica Mack | p(((. @Commits by organizations |
31 | 1 | Jessica Mack | ... |
32 | 4 19 Intel <contact@intel.com> |
||
33 | ... |
||
34 | 9 5 xinxin shu <xinxin.shu@intel.com> |
||
35 | ... |
||
36 | 17 2 xinxinsh <xinxin.shu@intel.com> |
||
37 | 2 | Jessica Mack | 18 2 Xiaoxi Chen <xiaoxi.chen@intel.com>@ |
38 | 1 | Jessica Mack | ... |
39 | |||
40 | 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 | 32 | Anthony D'Atri | The following one-liner can be used to spot duplicates in the Commits by authors instead of looking for them manually: |
42 | 1 | Jessica Mack | |
43 | |||
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 | 32 | Anthony D'Atri | It will for instance show Ross Turk twice, once with his Inktank address and another with his Red Hat address. These must not be aggregated in the @.mailmap@ file because the contributions are affiliated to two different organizations. Instead it can be added to the @.peoplemap@ file. |
47 | 1 | Jessica Mack | |
48 | h3. Commit conventions |
||
49 | |||
50 | 32 | Anthony D'Atri | The commit message starts with *mailmap*: prefix and it allows people working on Ceph to quickly identify 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 | There is one commit per author because this helps the author review the change related to her / his contribution without considering unrelated changes. |
||
53 | Here is an example of commit https://github.com/ceph/ceph/commit/...dd6e547828df41 |
||
54 | |||
55 | h3. Mail notification to the author about an update |
||
56 | |||
57 | 29 | Anthony D'Atri | 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 message 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 | Hi, |
||
62 | 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 | https://github.com/dachary/ceph/commit/{HASH} |
||
64 | This work is done to publish a map of Ceph contributors, as well as the organizations to which they are affiliated. |
||
65 | Cheers |
||
66 | [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 | 30 | Anthony D'Atri | Sending these messages can be automated: |
70 | 1 | Jessica Mack | |
71 | 2 | Jessica Mack | p(((. @git log --pretty='%H %s' @{u}.. | # assume all commit subjects contain the author@ |
72 | @sed -e 's/affiliation//' -e 's/name normalization//' | # remove subject noise@ |
||
73 | @while read hash mailmap name ; do@ |
||
74 | @to=$(sed -ne "s/.*$name/$name/p" < .organizationmap | head -1) # fetch the author mail@ |
||
75 | @echo "$to" # debug information@ |
||
76 | @( echo "To: $to"@ |
||
77 | @sed -e "s/{HASH}/$hash/" < mailmap.txt # the template mail above@ |
||
78 | @) | # create the mail from the template@ |
||
79 | @sendmail -v -F 'Loic Dachary' -f 'loic@dachary.org' -t@ |
||
80 | @done@ |
||
81 | 1 | Jessica Mack | |
82 | The Reviewed-by: field is added to the commit message when the author answers. |
||
83 | |||
84 | h3. Affiliation change over time |
||
85 | |||
86 | 32 | Anthony D'Atri | A given email address reflects the affiliation of an author. There is no way to say, for instance, that @loic@dachary.org@ is affiliated with Cloudwatt until August 2014 and with 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 | John Spray <jspray@redhat.com> John Spray <john.spray@inktank.com>@ |
||
90 | 1 | Jessica Mack | ... |
91 | |||
92 | h3. Sponsoring organizations |
||
93 | |||
94 | 32 | Anthony D'Atri | Searching the web to find the current employer of the author is likely the simplest method to discover the organization sponsoring the commit. Note that organizations can be 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 | Unaffiliated <no@organization.net> Michael Riederer <michael@riederer.org>@ |
||
98 | 1 | Jessica Mack | |
99 | h3. Sorting entries |
||
100 | |||
101 | 32 | Anthony D'Atri | The contents of the @.organizationmap@, @.peoplemap@ and @.mailmap@ files should be alphabetically sorted to more easily spot unintended duplicates to reduce the risk of a merge conflict. |
102 | 1 | Jessica Mack | |
103 | 26 | Jos Collin | h3. HOW TO maintain the contributor list |
104 | 1 | Jessica Mack | |
105 | 32 | Anthony D'Atri | # Run *./credits.sh origin/firefly...origin/master* on a fresh checkout of the main branch |
106 | # Check each entry in the *Commits by authors* section for lines that show the same author with two email addresses |
||
107 | 1 | Jessica Mack | ** If the duplicate is an accident *update the .mailmap* to map the two names into one |
108 | ** If the duplicate is intentional (change of organization) *update the .peoplemap* to map the two names into one |
||
109 | # Check each entry in the *Commits by organizations* section for lines that shows an author instead of an organization |
||
110 | ** Look for the name in *git log --pretty='%aN <%aE>' | sort | uniq* |
||
111 | ** If the *author is found under a different name, update the .mailmap* to map the two names into one |
||
112 | ** If the *author is not found, update the .organizationmap* with the organization sponsoring the commit |
||
113 | ** Commit the change with a subject *mailmap: Firstname Lastname affiliation* |
||
114 | ** Go back to step 1 |
||
115 | # Send a pull request with all commits with a cover *DNM: mailmap updates* to avoid duplicated work |
||
116 | # Send a mail to each author with a link to the commit of their update for review |
||
117 | # When an author replies |
||
118 | ** If modifications are suggested, *amend the commit* |
||
119 | ** Update the commit message with *Reviewed-by: Firstname Lastname <email>* |
||
120 | ** *git push --force* so the change shows in the pull request |
||
121 | ** Reply with a link to the updated commit |
||
122 | # A week after sending the mails, merge all updates |
||
123 | # 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 | # Update the schedule at https://wiki.ceph.com/Community/Ceph...ntenance_guide |