-
Notifications
You must be signed in to change notification settings - Fork 29
/
contributing.html
219 lines (197 loc) · 12.9 KB
/
contributing.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
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Contribution Guide — PagerDuty Python REST API Sessions 5.1.2 documentation</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/alabaster.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="prev" title="Module Reference" href="module_reference.html" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="contribution-guide">
<h1>Contribution Guide<a class="headerlink" href="#contribution-guide" title="Permalink to this heading">¶</a></h1>
<p>Bug reports and pull requests to fix issues are always welcome, as are
contributions to the built-in documentation.</p>
<p>If adding features, or making changes, it is recommended to update or add tests
and assertions to the appropriate test case class in <code class="docutils literal notranslate"><span class="pre">test_pdpyras.py</span></code> to
ensure code coverage. If the change(s) fix a bug, please add assertions that
reproduce the bug along with code changes themselves, and include the GitHub
issue number in the commit message.</p>
<section id="initial-setup">
<h2>Initial Setup<a class="headerlink" href="#initial-setup" title="Permalink to this heading">¶</a></h2>
<p>To be able to rebuild the documentation and release a new version, first make
sure you have <a class="reference external" href="https://www.gnu.org/software/make/">make</a> and <a class="reference external" href="https://pip.pypa.io/en/stable/installation/">pip</a> installed in your shell
environment.</p>
<p>Next, install Python dependencies for building and publishing as well as
testing locally:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>pip install -r requirements.txt
pip install -r requirements-publish.txt
</pre></div>
</div>
</section>
<section id="running-unit-tests">
<h2>Running Unit Tests<a class="headerlink" href="#running-unit-tests" title="Permalink to this heading">¶</a></h2>
<p>Assuming that all dependencies are installed, running <code class="docutils literal notranslate"><span class="pre">test_pdpyras.py</span></code> in
the root path of the repository will run the unit test suite:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>./test_pdpyras.py
</pre></div>
</div>
</section>
<section id="updating-documentation">
<h2>Updating Documentation<a class="headerlink" href="#updating-documentation" title="Permalink to this heading">¶</a></h2>
<p>The <code class="docutils literal notranslate"><span class="pre">.rst</span></code> files in <code class="docutils literal notranslate"><span class="pre">sphinx/source</span></code> are where most of the documentation
lives. To rebuild the HTML documentation from the source, run:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>make docs
</pre></div>
</div>
<p>To force a rebuild, run <code class="docutils literal notranslate"><span class="pre">touch</span> <span class="pre">CHANGELOG.rst</span></code> first.</p>
</section>
<section id="releasing-a-new-version">
<h2>Releasing a New Version<a class="headerlink" href="#releasing-a-new-version" title="Permalink to this heading">¶</a></h2>
<p>You will first need valid user accounts on both <code class="docutils literal notranslate"><span class="pre">pypi.org</span></code> and <code class="docutils literal notranslate"><span class="pre">test.pypi.org</span></code>
that have the “Maintainer” role on the project, as well as the requirements
installed (see above).</p>
<p>It is strongly recommended that you <a class="reference external" href="https://pypi.org/help/#apitoken">use an API token</a> to upload new releases to PyPI.</p>
<section id="perform-end-to-end-publish-and-installation-testing">
<h3>Perform end-to-end publish and installation testing<a class="headerlink" href="#perform-end-to-end-publish-and-installation-testing" title="Permalink to this heading">¶</a></h3>
<p>To test publishing and installing from the package index, first make sure you
have a valid user account on <code class="docutils literal notranslate"><span class="pre">test.pypi.org</span></code> that has publisher access to the
project as on <code class="docutils literal notranslate"><span class="pre">pypi.org</span></code>.</p>
<p>Note, once a release is uploaded, it is no longer possible to upload a release
with the same version number, even if that release is deleted. For that reason,
it is a good idea to first add a suffix, i.e. <code class="docutils literal notranslate"><span class="pre">-dev001</span></code>, to <code class="docutils literal notranslate"><span class="pre">__version__</span></code>
in <code class="docutils literal notranslate"><span class="pre">setup.py</span></code> while testing.</p>
<p>To perform end-to-end tests, run the following, entering credentials for
<code class="docutils literal notranslate"><span class="pre">test.pypi.org</span></code> when prompted:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>make testpublish
</pre></div>
</div>
<p>The make target <code class="docutils literal notranslate"><span class="pre">testpublish</span></code> performs the following:</p>
<ul class="simple">
<li><p>Build the Python egg in <code class="docutils literal notranslate"><span class="pre">dist/</span></code></p></li>
<li><p>Upload the new library to <code class="docutils literal notranslate"><span class="pre">test.pypi.org</span></code></p></li>
<li><p>Test-install the library from <code class="docutils literal notranslate"><span class="pre">test.pypi.org</span></code> into a temporary Python
virtualenv that does not already have the library installed, to test
installing for the first time</p></li>
<li><p>Tests-install the library from <code class="docutils literal notranslate"><span class="pre">test.pypi.org</span></code> into a temporary Python
virtualenv where the library is already installed, to test upgrading</p></li>
</ul>
<p>If any errors are encountered, the script should immediately exit. Errors
should be investigated and mitigated before publishing. To test again,
temporarily change <code class="docutils literal notranslate"><span class="pre">__version__</span></code> so that it counts as a new release
and gets uploaded, and set it to the desired version before the actual
release.</p>
</section>
<section id="merge-changes-and-tag">
<h3>Merge changes and tag<a class="headerlink" href="#merge-changes-and-tag" title="Permalink to this heading">¶</a></h3>
<p>A pull request for releasing a new version should be created, which along with
the functional changes should also include at least:</p>
<ul class="simple">
<li><p>An update to the changelog, where all items corresponding to community
contributions end with (in parentheses) the GitHub user handle of the
contributor, a slash, and a link to the pull request (see CHANGELOG.rst for
preexisting examples).</p></li>
<li><p>A change in the version number in both setup.py and pdpyras.py, to a new
version that follows <a class="reference external" href="https://semver.org/">Semantic Versioning</a>.</p></li>
<li><p>Rebuilt HTML documentation</p></li>
</ul>
<p>The HTML documentation can be rebuilt with the <code class="docutils literal notranslate"><span class="pre">docs</span></code> make target:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>make docs
</pre></div>
</div>
<p>After rebuilding the documentation, it can then be viewed by opening the file
<code class="docutils literal notranslate"><span class="pre">docs/index.html</span></code> in a web browser. Including rebuilt documentation helps
reviewers by not requiring them to have the documentation-building tools
installed.</p>
<p>Once the pull request is approved, merge. Then (locally) checkout main and tag:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>git checkout main <span class="o">&&</span> <span class="se">\</span>
git pull origin main <span class="o">&&</span> <span class="se">\</span>
git tag <span class="s2">"v</span><span class="k">$(</span>python -c <span class="s1">'from pdpyras import __version__; print(__version__)'</span><span class="k">)</span><span class="s2">"</span> <span class="o">&&</span> <span class="se">\</span>
git push --tags origin main
</pre></div>
</div>
</section>
<section id="publishing">
<h3>Publishing<a class="headerlink" href="#publishing" title="Permalink to this heading">¶</a></h3>
<p>Once the changes are merged and tagged, make sure your local repository clone
has the <code class="docutils literal notranslate"><span class="pre">main</span></code> branch checked out at the latest available commit, and the
local file tree is clean (has no uncommitted changes). Then run:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>make publish
</pre></div>
</div>
<p>When prompted, enter <code class="docutils literal notranslate"><span class="pre">__token__</span></code> as your username and your API token as the password.</p>
<p>Finally, <a class="reference external" href="https://github.com/PagerDuty/pdpyras/releases/new">create a new release</a>, and fill in some
details:</p>
<ul class="simple">
<li><p>Select “Choose a tag” and select the new latest tag.</p></li>
<li><p>If a new patch version is being released, update the existing release for
that major and minor version.</p></li>
<li><p>Name the release after the major and minor version, i.e. 5.1, and very brief
summary of changes.</p></li>
<li><p>Compose a description from the pull requests whose changes are included.</p></li>
</ul>
</section>
</section>
</section>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<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" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
<h3><a href="index.html">Table of Contents</a></h3>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="changelog.html">Changelog</a></li>
<li class="toctree-l1"><a class="reference internal" href="user_guide.html">User Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="module_reference.html">Module Reference</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Contribution Guide</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#initial-setup">Initial Setup</a></li>
<li class="toctree-l2"><a class="reference internal" href="#running-unit-tests">Running Unit Tests</a></li>
<li class="toctree-l2"><a class="reference internal" href="#updating-documentation">Updating Documentation</a></li>
<li class="toctree-l2"><a class="reference internal" href="#releasing-a-new-version">Releasing a New Version</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#perform-end-to-end-publish-and-installation-testing">Perform end-to-end publish and installation testing</a></li>
<li class="toctree-l3"><a class="reference internal" href="#merge-changes-and-tag">Merge changes and tag</a></li>
<li class="toctree-l3"><a class="reference internal" href="#publishing">Publishing</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©2023, PagerDuty Inc..
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 5.2.2</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
|
<a href="_sources/contributing.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>