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
|
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Guidelines for PROJ code contributors — PROJ 9.0.0 documentation</title>
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="shortcut icon" href="../_static/favicon.png"/>
<link rel="canonical" href="https://proj.orgcommunity/code_contributions.html"/>
<!--[if lt IE 9]>
<script src="../_static/js/html5shiv.min.js"></script>
<![endif]-->
<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/doctools.js"></script>
<script src="../_static/js/theme.js"></script>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Code of Conduct" href="code_of_conduct.html" />
<link rel="prev" title="Contributing" href="contributing.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" style="background: #353130" >
<a href="../index.html">
<img src="../_static/logo.png" class="logo" alt="Logo"/>
</a>
<div class="version">
9.0.0
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../about.html">About</a></li>
<li class="toctree-l1"><a class="reference internal" href="../news.html">News</a></li>
<li class="toctree-l1"><a class="reference internal" href="../download.html">Download</a></li>
<li class="toctree-l1"><a class="reference internal" href="../install.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../usage/index.html">Using PROJ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../apps/index.html">Applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../operations/index.html">Coordinate operations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../resource_files.html">Resource files</a></li>
<li class="toctree-l1"><a class="reference internal" href="../geodesic.html">Geodesic calculations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../development/index.html">Development</a></li>
<li class="toctree-l1"><a class="reference internal" href="../specifications/index.html">Specifications</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Community</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="channels.html">Communication channels</a></li>
<li class="toctree-l2"><a class="reference internal" href="contributing.html">Contributing</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Guidelines for PROJ code contributors</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#id1">Code contributions.</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#making-changes">Making Changes</a></li>
<li class="toctree-l4"><a class="reference internal" href="#submitting-changes">Submitting Changes</a></li>
<li class="toctree-l4"><a class="reference internal" href="#coding-conventions">Coding conventions</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="#tools">Tools</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#reformatting-c-code">Reformatting C++ code</a></li>
<li class="toctree-l4"><a class="reference internal" href="#cppcheck-static-analyzer">cppcheck static analyzer</a></li>
<li class="toctree-l4"><a class="reference internal" href="#clang-static-analyzer-csa">Clang Static Analyzer (CSA)</a></li>
<li class="toctree-l4"><a class="reference internal" href="#typo-detection-and-fixes">Typo detection and fixes</a></li>
<li class="toctree-l4"><a class="reference internal" href="#include-what-you-use-iwyu">Include What You Use (IWYU)</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="code_of_conduct.html">Code of Conduct</a></li>
<li class="toctree-l2"><a class="reference internal" href="rfc/index.html">Request for Comments</a></li>
<li class="toctree-l2"><a class="reference internal" href="index.html#conference">Conference</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../faq.html">FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../zreferences.html">References</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" style="background: #353130" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">PROJ</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home"></a> »</li>
<li><a href="index.html">Community</a> »</li>
<li>Guidelines for PROJ code contributors</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/OSGeo/PROJ/edit/8.2/docs/source/community/code_contributions.rst" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul><div class="rst-breadcrumbs-buttons" role="navigation" aria-label="Sequential page navigation">
<a href="contributing.html" class="btn btn-neutral float-left" title="Contributing" accesskey="p"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="code_of_conduct.html" class="btn btn-neutral float-right" title="Code of Conduct" accesskey="n">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="guidelines-for-proj-code-contributors">
<span id="code-contributions"></span><h1>Guidelines for PROJ code contributors<a class="headerlink" href="#guidelines-for-proj-code-contributors" title="Permalink to this headline">¶</a></h1>
<p>This is a guide for PROJ, casual or regular, code contributors.</p>
<section id="id1">
<h2>Code contributions.<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h2>
<p>Code contributions can be either bug fixes or new features. The process
is the same for both, so they will be discussed together in this
section.</p>
<section id="making-changes">
<h3>Making Changes<a class="headerlink" href="#making-changes" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li><p>Create a topic branch from where you want to base your work.</p></li>
<li><p>You usually should base your topic branch off of the master branch.</p></li>
<li><p>To quickly create a topic branch: <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">checkout</span> <span class="pre">-b</span> <span class="pre">my-topic-branch</span></code></p></li>
<li><p>Make commits of logical units.</p></li>
<li><p>Check for unnecessary whitespace with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">diff</span> <span class="pre">--check</span></code> before
committing.</p></li>
<li><p>Make sure your commit messages are in the <a class="reference external" href="http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html">proper
format</a>.</p></li>
<li><p>Make sure you have added the necessary tests for your changes.</p></li>
<li><p>Make sure that all tests pass</p></li>
</ul>
</section>
<section id="submitting-changes">
<h3>Submitting Changes<a class="headerlink" href="#submitting-changes" title="Permalink to this headline">¶</a></h3>
<ul class="simple">
<li><p>Push your changes to a topic branch in your fork of the repository.</p></li>
<li><p>Submit a pull request to the PROJ repository in the OSGeo
organization.</p></li>
<li><p>If your pull request fixes/references an issue, include that issue
number in the pull request. For example:</p></li>
</ul>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Wiz the bang
Fixes #123.
</pre></div>
</div>
<ul class="simple">
<li><p>PROJ developers will look at your patch and take an appropriate
action.</p></li>
</ul>
</section>
<section id="coding-conventions">
<h3>Coding conventions<a class="headerlink" href="#coding-conventions" title="Permalink to this headline">¶</a></h3>
<section id="programming-language">
<h4>Programming language<a class="headerlink" href="#programming-language" title="Permalink to this headline">¶</a></h4>
<p>PROJ was originally developed in ANSI C. Today PROJ is mostly developed in C++11,
with a few parts of the code base still being C. Most of the older parts of the
code base is effectively C with a few modifications so that it compiles better as
C++.</p>
</section>
<section id="coding-style">
<h4>Coding style<a class="headerlink" href="#coding-style" title="Permalink to this headline">¶</a></h4>
<p>The parts of the code base that has started its life as C++ is formatted with
<code class="docutils literal notranslate"><span class="pre">clang-format</span></code> using the script <code class="docutils literal notranslate"><span class="pre">scripts/reformat_cpp.sh</span></code>. This is mostly
contained to the code in <cite>src/iso19111/</cite> but a few other <cite>.cpp</cite>-files are
covered as well.</p>
<p>For the rest of the code base, which has its origin in C, we don’t enforce any
particular coding style, but please try to keep it as simple as possible. If
improving existing code, please try to conform with the style of the locally
surrounding code.</p>
</section>
<section id="whitespace">
<h4>Whitespace<a class="headerlink" href="#whitespace" title="Permalink to this headline">¶</a></h4>
<p>Throughout the PROJ code base you will see differing whitespace use.
The general rule is to keep whitespace in whatever form it is in the
file you are currently editing. If the file has a mix of tabs and space
please convert the tabs to space in a separate commit before making any
other changes. This makes it a lot easier to see the changes in diffs
when evaluating the changed code. New files should use spaces as
whitespace.</p>
</section>
</section>
</section>
<section id="tools">
<h2>Tools<a class="headerlink" href="#tools" title="Permalink to this headline">¶</a></h2>
<section id="reformatting-c-code">
<h3>Reformatting C++ code<a class="headerlink" href="#reformatting-c-code" title="Permalink to this headline">¶</a></h3>
<p>The script in <code class="docutils literal notranslate"><span class="pre">scripts/reformat_cpp.sh</span></code> will reformat C++ code in accordance
to the project preference.</p>
<p>If you are writing a new <code class="docutils literal notranslate"><span class="pre">.cpp</span></code>-file it should be added to the list in the
reformatting script.</p>
</section>
<section id="cppcheck-static-analyzer">
<h3>cppcheck static analyzer<a class="headerlink" href="#cppcheck-static-analyzer" title="Permalink to this headline">¶</a></h3>
<p>You can run locally <code class="docutils literal notranslate"><span class="pre">scripts/cppcheck.sh</span></code> that is a wrapper script around the
cppcheck utility. This tool is used as part of the quality control of the code.</p>
<p>cppcheck can have false positives. In general, it is preferable to rework the
code a bit to make it more ‘obvious’ and avoid those false positives. When not
possible, you can add a comment in the code like</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>/* cppcheck-suppress duplicateBreak */
</pre></div>
</div>
<p>in the preceding line. Replace
duplicateBreak with the actual name of the violated rule emitted by cppcheck.</p>
</section>
<section id="clang-static-analyzer-csa">
<h3>Clang Static Analyzer (CSA)<a class="headerlink" href="#clang-static-analyzer-csa" title="Permalink to this headline">¶</a></h3>
<p>CSA is run by a GitHub Actions workflow. You may also run it locally.</p>
<p>Preliminary step: install clang. For example:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>wget https://releases.llvm.org/9.0.0/clang+llvm-9.0.0-x86_64-linux-gnu-ubuntu-18.04.tar.xz
tar xJf clang+llvm-9.0.0-x86_64-linux-gnu-ubuntu-18.04.tar.xz
mv clang+llvm-9.0.0-x86_64-linux-gnu-ubuntu-18.04 clang+llvm-9
export PATH=$PWD/clang+llvm-9/bin:$PATH
</pre></div>
</div>
<p>Configure PROJ with the <strong class="program">scan-build</strong> utility of clang:</p>
<dl class="simple">
<dt>::</dt><dd><p>mkdir csa_build
cd csa_build
scan-build cmake ..</p>
</dd>
</dl>
<p>Build using <strong class="program">scan-build</strong>:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>scan-build make [-j8]
</pre></div>
</div>
<p>If CSA finds errors, they will be emitted during the build. And in which case,
at the end of the build process, <strong class="program">scan-build</strong> will emit a warning message
indicating errors have been found and how to display the error report. This
is with something like</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>scan-view /tmp/scan-build-2021-03-15-121416-17476-1
</pre></div>
</div>
<p>This will open a web browser with the interactive report.</p>
<p>CSA may also have false positives. In general, this happens when the code is
non-trivial / makes assumptions that hard to check at first sight. You will
need to add extra checks or rework it a bit to make it more “obvious” for CSA.
This will also help humans reading your code !</p>
</section>
<section id="typo-detection-and-fixes">
<h3>Typo detection and fixes<a class="headerlink" href="#typo-detection-and-fixes" title="Permalink to this headline">¶</a></h3>
<p>Run <code class="docutils literal notranslate"><span class="pre">scripts/fix_typos.sh</span></code></p>
</section>
<section id="include-what-you-use-iwyu">
<h3>Include What You Use (IWYU)<a class="headerlink" href="#include-what-you-use-iwyu" title="Permalink to this headline">¶</a></h3>
<p>Managing C includes is a pain. IWYU makes updating headers a bit
easier. IWYU scans the code for functions that are called and makes
sure that the headers for all those functions are present and in
sorted order. However, you cannot blindly apply IWYU to PROJ. It
does not understand ifdefs, other platforms, or the order requirements
of PROJ internal headers. So the way to use it is to run it on a copy
of the source and merge in only the changes that make sense.
Additions of standard headers should always be safe to merge. The
rest require careful evaluation. See the IWYU documentation for
motivation and details.</p>
<p><a class="reference external" href="https://github.com/include-what-you-use/include-what-you-use/tree/master/docs">IWYU docs</a></p>
</section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="contributing.html" class="btn btn-neutral float-left" title="Contributing" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="code_of_conduct.html" class="btn btn-neutral float-right" title="Code of Conduct" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 1983-2022.
<span class="lastupdated">Last updated on 22 Mar 2022.
</span></p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
|
