-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathauthorship.html
304 lines (259 loc) · 15.9 KB
/
authorship.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Contributor & Authorship Tracking — rever 0.5.0 documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/numpy_friendly.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="_static/graphviz.css" />
<link rel="stylesheet" href="//fonts.googleapis.com/css?family=Noticia+Text|Open+Sans|Droid+Sans+Mono" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/jquery.cookie.js"></script>
<script src="_static/cloud.base.js"></script>
<script src="_static/cloud.js"></script>
<link rel="shortcut icon" href="_static/longship.ico"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Activities" href="activities.html" />
<link rel="prev" title="News Workflow" href="news.html" />
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="canonical" href="http://xon.sh/authorship.html"/>
</head><body>
<div class="relbar-top">
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> </li>
<li class="right" >
<a href="activities.html" title="Activities"
accesskey="N">next</a> </li>
<li class="right" >
<a href="news.html" title="News Workflow"
accesskey="P">previous</a> </li>
<li><a href="index.html">rever 0.5.0 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Contributor & Authorship Tracking</a></li>
</ul>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="contributor-authorship-tracking">
<h1>Contributor & Authorship Tracking<a class="headerlink" href="#contributor-authorship-tracking" title="Permalink to this headline">¶</a></h1>
<p>Rever helps you keep up-to-date with who is contributing to your project.
This is through the <code class="docutils literal notranslate"><span class="pre">authors</span></code> activity. To get started, just add
<code class="docutils literal notranslate"><span class="pre">authors</span></code> to your activities and then run <code class="docutils literal notranslate"><span class="pre">rever</span> <span class="pre">setup</span></code>.</p>
<p><strong>rever.xsh:</strong></p>
<div class="highlight-xonsh notranslate"><div class="highlight"><pre><span></span><span class="nv">$ACTIVITIES</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"authors"</span><span class="p">]</span>
</pre></div>
</div>
<p>And then run,</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>$ rever setup
</pre></div>
</div>
<p>The above generates a few files for us and can be applied even to an existing
project. By default, the author setup creates:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">AUTHORS</span></code>, a plain-text listing of the authors</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">.authors.yml</span></code>, a YAML file for storing an configuring contributor information</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">.mailmap</span></code>, a git file for mapping names and emails to alternatives.</p></li>
</ul>
<p>These filenames can be configured via the <code class="docutils literal notranslate"><span class="pre">$AUTHORS_FILENAME</span></code>,
<code class="docutils literal notranslate"><span class="pre">$AUTHORS_METADATA</span></code>, and <code class="docutils literal notranslate"><span class="pre">$AUTHORS_MAILMAP</span></code>, environment variables in the
<code class="docutils literal notranslate"><span class="pre">rever.xsh</span></code> file, as with other activities.</p>
<p>If you have a long running, project, you may need to seed the <code class="docutils literal notranslate"><span class="pre">.authors.yml</span></code>
metadata file with some information that disambiguate your contributors
before <code class="docutils literal notranslate"><span class="pre">rever</span> <span class="pre">setup</span></code> will complete successfully. Don’t worry! This is
totally normal and rever will present best guesses for you to choose from
in order to obtain a clean set of metadata.</p>
<div class="section" id="metadata-format">
<h2>Metadata Format<a class="headerlink" href="#metadata-format" title="Permalink to this headline">¶</a></h2>
<p>The metadata that is kept about authors is a mix of manually-supplied, optional
information (such as GitHub usernames) and data that can be mined from
version control (such as emails, number of commits, etc.). The YAML file is a
list of mappings as follows:</p>
<p><strong>authors.yaml:</strong></p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="c1"># required fields</span>
<span class="p p-Indicator">-</span> <span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">Princess Buttercup</span>
<span class="nt">email</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">[email protected]</span>
<span class="c1"># optional fields</span>
<span class="nt">github</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">bcup</span>
<span class="nt">is_org</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">False</span>
<span class="nt">aliases</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">Buttercup</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">beecup</span>
<span class="nt">alternate_emails</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">[email protected]</span>
<span class="c1"># autogenerated fields</span>
<span class="nt">num_commits</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">1000</span>
<span class="nt">first_commit</span><span class="p">:</span> <span class="s">'1987-09-25'</span>
<span class="p p-Indicator">-</span> <span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">Westley</span>
<span class="nt">email</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">[email protected]</span>
<span class="nt">github</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">westley</span>
<span class="nt">aliases</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">Dread Pirate Roberts</span>
<span class="nt">alternate_emails</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="l l-Scalar l-Scalar-Plain">[email protected]</span>
<span class="p p-Indicator">-</span> <span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">Florin</span>
<span class="nt">email</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">[email protected]</span>
<span class="nt">github</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">florin</span>
<span class="nt">is_org</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">True</span>
</pre></div>
</div>
<p>Feel free to edit this file as much as you want, especially for <code class="docutils literal notranslate"><span class="pre">aliases</span></code>
and <code class="docutils literal notranslate"><span class="pre">alternate_email</span></code>. It is the source of all downstream information.
The <code class="docutils literal notranslate"><span class="pre">rever</span> <span class="pre">setup</span></code> command will generate a minimal version of this file
that contains names and emails. Every release, the <code class="docutils literal notranslate"><span class="pre">num_commits</span></code> and
<code class="docutils literal notranslate"><span class="pre">first_commit</span></code> fields will be recomputed and the metadata will be
written back out.</p>
</div>
<div class="section" id="authors-file">
<h2>AUTHORS File<a class="headerlink" href="#authors-file" title="Permalink to this headline">¶</a></h2>
<p>The authors file is generated from the metadata and the following environment
variables:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">$AUTHORS_TEMPLATE</span></code>: string that dictated how the authors file looks.
It has the format keys <code class="docutils literal notranslate"><span class="pre">sorting_text</span></code> and <code class="docutils literal notranslate"><span class="pre">authors</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$AUTHORS_FORMAT</span></code>: string the dictates how each author is formatted in the
file. The fields of this string are the same as for the metadata.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">$AUTHORS_SORTBY</span></code>: string flag that specifies how authors should be sorted in
the authors file. Valid options are:</p>
<ul>
<li><p><code class="docutils literal notranslate"><span class="pre">"num_commits"</span></code>: Number of commits per author</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">"first_commit"</span></code>: Sort by first commit.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">"alpha"</span></code>: Alphabetically.</p></li>
</ul>
</li>
</ul>
<p>So for example, the following configuration,</p>
<p><strong>rever.xsh:</strong></p>
<div class="highlight-rever notranslate"><div class="highlight"><pre><span></span>$PROJECT = "acme"
$ACTIVITIES = ["authors"]
$AUTHORS_FILENAME = "AUTHORS.md"
$AUTHORS_TEMPLATE = """
The $PROJECT project has some great contributors! They are:
{authors}
These have been sorted {sorting_text}.
"""
$AUTHORS_FORMAT= "* [{name}](https://github.com/{github})\n"
$AUTHORS_SORTBY = "alpha"
</pre></div>
</div>
<p>And say that Alice and Bob are our contributors, then we would generate:</p>
<p><strong>AUTHORS.md:</strong></p>
<div class="highlight-markdown notranslate"><div class="highlight"><pre><span></span>The acme project has some great contributors! They are:
<span class="k">*</span> [<span class="nt">Alice</span>](<span class="na">https://github.com/al1ce</span>)
<span class="k">*</span> [<span class="nt">Bob</span>](<span class="na">https://github.com/b0b</span>)
These have been sorted alphabetically.
</pre></div>
</div>
</div>
<div class="section" id="latest-contributors">
<h2>Latest Contributors<a class="headerlink" href="#latest-contributors" title="Permalink to this headline">¶</a></h2>
<p>Additionally, the authors activity will generate a file that stores the (sorted)
emails of all of the contributors since the last tag. This file is usually at
<code class="docutils literal notranslate"><span class="pre">$REVER_DIR/LATEST-AUTHORS.json</span></code>, but may be configured by <code class="docutils literal notranslate"><span class="pre">$AUTHORS_LATEST</span></code>.
This allows other activities (such as <code class="docutils literal notranslate"><span class="pre">changelog</span></code>) to access the list of
all contributors for a particular version. Since this operates from the last
tag, it is important to run the <code class="docutils literal notranslate"><span class="pre">authors</span></code> activity before the <code class="docutils literal notranslate"><span class="pre">tag</span></code> activity.</p>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html" title="index">
<img class="logo" src="_static/longship-256.png" alt="Logo"/>
</a></p><div class="sphinx-toc sphinxlocaltoc">
<h3><a href="index.html">Page contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Contributor & Authorship Tracking</a><ul>
<li><a class="reference internal" href="#metadata-format">Metadata Format</a></li>
<li><a class="reference internal" href="#authors-file">AUTHORS File</a></li>
<li><a class="reference internal" href="#latest-contributors">Latest Contributors</a></li>
</ul>
</li>
</ul>
</div>
<div class="sphinxprev">
<h4>Previous page</h4>
<p class="topless"><a href="news.html"
title="Previous page">← News Workflow</a></p>
</div>
<div class="sphinxnext">
<h4>Next page</h4>
<p class="topless"><a href="activities.html"
title="Next page">→ Activities</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/authorship.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="sidebar-toggle-group no-js">
<button class="sidebar-toggle" id="sidebar-hide" title="Hide the sidebar menu">
«
<span class="show-for-small">hide menu</span>
</button>
<button class="sidebar-toggle" id="sidebar-show" title="Show the sidebar menu">
<span class="show-for-small">menu</span>
<span class="hide-for-small">sidebar</span>
»
</button>
</div>
<div class="clearer"></div>
</div>
<div class="relbar-bottom">
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> </li>
<li class="right" >
<a href="activities.html" title="Activities"
>next</a> </li>
<li class="right" >
<a href="news.html" title="News Workflow"
>previous</a> </li>
<li><a href="index.html">rever 0.5.0 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Contributor & Authorship Tracking</a></li>
</ul>
</div>
</div>
<div class="footer" role="contentinfo">
© Copyright 2017, Anthony Scopatz.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.5.4.
</div>
<!-- cloud_sptheme 1.4 -->
</body>
</html>