-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathdev_practices.html
More file actions
302 lines (253 loc) · 16.8 KB
/
dev_practices.html
File metadata and controls
302 lines (253 loc) · 16.8 KB
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
<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Development practices — MapServer 8.6.1 documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=03e43079" />
<link rel="stylesheet" type="text/css" href="../_static/sphinx.css?v=48f05237" />
<link rel="stylesheet" type="text/css" href="../_static/copybutton.css?v=76b2166b" />
<link rel="stylesheet" type="text/css" href="../_static/custom.css?v=dd298242" />
<link rel="stylesheet" type="text/css" href="../_static/ribbon.css?v=ea091bf4" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=ad95d4c4"></script>
<script src="../_static/doctools.js?v=fd6eb6e6"></script>
<script src="../_static/sphinx_highlight.js?v=6ffebe34"></script>
<script src="../_static/clipboard.min.js?v=a7894cd8"></script>
<script src="../_static/copybutton.js?v=f281be69"></script>
<link rel="icon" href="../_static/mapserver.ico"/>
<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="copyright" title="Copyright" href="../copyright.html" />
<link rel="next" title="Testing" href="tests/index.html" />
<link rel="prev" title="How to Help Translate the Documentation" href="translation.html" />
</head><body>
<!-- for main branch only, do not backport this -->
<table width="100%" style="width: 100%; background-color: white;">
<tr>
<td rowspan="2" style="padding: 10px 0px 10px 10px;">
<a href="../index.html" title="Home"><img src="../_static/banner.png" alt="MapServer banner" border="0" /></a>
</td>
<td style="padding: 10px 10px 0px 0px; text-align: right; vertical-align: top;">
<a href="../index.html" title="Home">Home</a> |
<a href="../products.html" title="Products (MapServer core, MapCache, TinyOWS">Products</a> |
<a href="https://github.com/mapserver/mapserver/issues/" title="Issue Tracker (MapServer core)">Issue Tracker</a> |
<a href="../community/service_providers.html" title="Professional Service Providers">Service Providers</a> |
<a href="../faq.html" title="Frequently Asked Questions">FAQ</a> |
<a href="https://fosstodon.org/@mapserver" title="Mastodon" target="_blank">Mastodon</a> |
<a href="../download.html" title="Download Source or Binaries">Download </a> |
<a class="badge" href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=KRJ2X44N3HA6U&source=url" target="_blank">
<img src="https://img.shields.io/badge/donate-%E2%9D%A4%C2%A0-ff69b4.svg?style=flat" alt="Donate to MapServer">
</a>
</td>
</tr>
<tr>
<td style="padding: 0px 10px 0px 0px; text-align: right; vertical-align: bottom;">
<img src="../_static/flagicons/en.png" alt="en" title="en" border="0" width="18px" height="13px"/>
<a href="../ar/development/dev_practices.html"><img src="../_static/flagicons/ar.png" alt="ar" title="ar" border="0" /></a>
<a href="../de/development/dev_practices.html"><img src="../_static/flagicons/de.png" alt="de" title="de" border="0" /></a>
<a href="../el/development/dev_practices.html"><img src="../_static/flagicons/el.png" alt="el" title="el" border="0" /></a>
<a href="../es/development/dev_practices.html"><img src="../_static/flagicons/es.png" alt="es" title="es" border="0" /></a>
<a href="../fr/development/dev_practices.html"><img src="../_static/flagicons/fr.png" alt="fr" title="fr" border="0" /></a>
<a href="../id/development/dev_practices.html"><img src="../_static/flagicons/id.png" alt="id" title="id" border="0" /></a>
<a href="../it/development/dev_practices.html"><img src="../_static/flagicons/it.png" alt="it" title="it" border="0" /></a>
<a href="../ja/development/dev_practices.html"><img src="../_static/flagicons/ja.png" alt="ja" title="ja" border="0" /></a>
<a href="../nl_NL/development/dev_practices.html"><img src="../_static/flagicons/nl_NL.png" alt="nl_NL" title="nl_NL" border="0" /></a>
<a href="../pl/development/dev_practices.html"><img src="../_static/flagicons/pl.png" alt="pl" title="pl" border="0" /></a>
<a href="../ru/development/dev_practices.html"><img src="../_static/flagicons/ru.png" alt="ru" title="ru" border="0" /></a>
<a href="../sq/development/dev_practices.html"><img src="../_static/flagicons/sq.png" alt="sq" title="sq" border="0" /></a>
<a href="../tr/development/dev_practices.html"><img src="../_static/flagicons/tr.png" alt="tr" title="tr" border="0" /></a>
</td>
</tr>
</table>
<div class="related" role="navigation" aria-label="Related">
<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="tests/index.html" title="Testing"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="translation.html" title="How to Help Translate the Documentation"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Home</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" accesskey="U">Development</a> »</li>
<li class="nav-item nav-item-this"><a href="">Development practices</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="development-practices">
<span id="id1"></span><h1>Development practices<a class="headerlink" href="#development-practices" title="Link to this heading">¶</a></h1>
<section id="making-changes-to-mapserver">
<h2>Making changes to MapServer<a class="headerlink" href="#making-changes-to-mapserver" title="Link to this heading">¶</a></h2>
<p>Minor changes to MapServer, such as bug fixes, may be made by opening a GitHub pull request.</p>
<p>Major changes should be discussed on the mapserver-dev listserv and may require the drafting
of a RFC (request for comment) document.</p>
</section>
<section id="git-usage">
<h2>Git usage<a class="headerlink" href="#git-usage" title="Link to this heading">¶</a></h2>
<p>This section collects a few best practices for git usage for MapServer development.</p>
<section id="initiating-your-work-repository">
<h3>Initiating your work repository<a class="headerlink" href="#initiating-your-work-repository" title="Link to this heading">¶</a></h3>
<p>Fork mapserver/mapserver from the GitHub UI, and then run:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>clone<span class="w"> </span>https://github.com/MapServer/MapServer
<span class="nb">cd</span><span class="w"> </span>MapServer
git<span class="w"> </span>remote<span class="w"> </span>add<span class="w"> </span>my_user_name<span class="w"> </span>git@github.com:my_user_name/mapserver.git
</pre></div>
</div>
</section>
<section id="working-with-a-feature-branch">
<h3>Working with a feature branch<a class="headerlink" href="#working-with-a-feature-branch" title="Link to this heading">¶</a></h3>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>checkout<span class="w"> </span>main
<span class="c1"># potentially update your local main against upstream, as described above</span>
git<span class="w"> </span>checkout<span class="w"> </span>-b<span class="w"> </span>my_new_feature_branch
<span class="c1"># do work. For example:</span>
git<span class="w"> </span>add<span class="w"> </span>my_new_file
git<span class="w"> </span>add<span class="w"> </span>my_modifid_message
git<span class="w"> </span>rm<span class="w"> </span>old_file
git<span class="w"> </span>commit<span class="w"> </span>-a
<span class="c1"># you may need to resynchronize against main if you need some bugfix</span>
<span class="c1"># or new capability that has been added since you created your branch</span>
git<span class="w"> </span>fetch<span class="w"> </span>origin
git<span class="w"> </span>rebase<span class="w"> </span>origin/main
<span class="c1"># At end of your work, make sure history is reasonable by folding non</span>
<span class="c1"># significant commits into a consistent set</span>
git<span class="w"> </span>rebase<span class="w"> </span>-i<span class="w"> </span>main
<span class="c1"># use 'fixup' for example to merge several commits together,</span>
<span class="c1"># and 'reword' to modify commit messages</span>
<span class="c1"># or alternatively, in case there is a big number of commits and marking</span>
<span class="c1"># all them as 'fixup' is tedious</span>
git<span class="w"> </span>fetch<span class="w"> </span>origin
git<span class="w"> </span>rebase<span class="w"> </span>origin/main
git<span class="w"> </span>reset<span class="w"> </span>--soft<span class="w"> </span>origin/main
git<span class="w"> </span>commit<span class="w"> </span>-a<span class="w"> </span>-m<span class="w"> </span><span class="s2">"Put here the synthetic commit message"</span>
<span class="c1"># push your branch</span>
git<span class="w"> </span>push<span class="w"> </span>my_user_name<span class="w"> </span>my_new_feature_branch
</pre></div>
</div>
<p>From the GitHub UI, issue a pull request.</p>
<p>If the pull request discussion or automated checks require changes, commit
locally and push. To get a reasonable history, you may need to combine commits
using <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">rebase</span> <span class="pre">-i</span> <span class="pre">main</span></code>, in which case you will have to force-push your
branch with <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span> <span class="pre">-f</span> <span class="pre">my_user_name</span> <span class="pre">my_new_feature_branch</span></code>.</p>
</section>
<section id="updating-your-local-main-against-upstream-main">
<h3>Updating your local main against upstream main<a class="headerlink" href="#updating-your-local-main-against-upstream-main" title="Link to this heading">¶</a></h3>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>checkout<span class="w"> </span>main
git<span class="w"> </span>fetch<span class="w"> </span>origin
<span class="c1"># Be careful: this will lose all local changes you might have done now</span>
git<span class="w"> </span>reset<span class="w"> </span>--hard<span class="w"> </span>origin/main
</pre></div>
</div>
</section>
<section id="commit-messages">
<h3>Commit messages<a class="headerlink" href="#commit-messages" title="Link to this heading">¶</a></h3>
<p>Commit messages should indicate a component name (eg a driver name), a short
description, and when relevant, a reference to a issue (with ‘fixes #’ if it
actually fixes it)</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">COMPONENT_NAME</span><span class="p">:</span> <span class="n">fix</span> <span class="n">bla</span> <span class="n">bla</span> <span class="p">(</span><span class="n">fixes</span> <span class="c1">#1234)</span>
<span class="n">Details</span> <span class="n">here</span><span class="o">...</span>
</pre></div>
</div>
</section>
<section id="commit-hooks">
<h3>Commit hooks<a class="headerlink" href="#commit-hooks" title="Link to this heading">¶</a></h3>
<p>MapServer provides pre-commit hooks to run code linters before a commit is made. The
hooks are cloned with the repository and can be installed using
<a class="reference external" href="https://pre-commit.com">pre-commit</a>:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>python3<span class="w"> </span>-m<span class="w"> </span>pip<span class="w"> </span>install<span class="w"> </span>pre-commit
pre-commit<span class="w"> </span>install
</pre></div>
</div>
<p>Once installed, the hooks can be run manually via <code class="docutils literal notranslate"><span class="pre">pre-commit</span> <span class="pre">run</span> <span class="pre">--all-files</span></code>.</p>
</section>
<section id="blame-ignore-file">
<h3>Blame ignore file<a class="headerlink" href="#blame-ignore-file" title="Link to this heading">¶</a></h3>
<p>Due to whole-tree code reformatting done during MapServer 8.2 development,
<code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">blame</span></code> information might be misleading. To avoid that, you need
to modify your git configuration as following to ignore the revision of
the whole-tree reformatting:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>config<span class="w"> </span>blame.ignoreRevsFile<span class="w"> </span>.git-blame-ignore-revs
</pre></div>
</div>
</section>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<search 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>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3>
<p>
<a href="../about.html" title="About">About</a><br>
<a href="../products.html" title="Products">Products</a><br>
<a href="../community/index.html" title="Community">Community</a><br>
<a href="index.html" title="Development">Development</a><br>
<a href="../download.html" title="Downloads">Downloads</a><br>
<a href="../documentation.html" title="Documentation">Documentation</a><br>
<a href="../faq.html" title="FAQ">FAQ</a><br>
<a href="../psc.html" title="PSC">PSC</a><br>
<a href="https://fosstodon.org/@mapserver" title="Mastodon">Mastodon</a>
</p>
<h3>Current Table Of Contents</h3>
<ul>
<li><a class="reference internal" href="#">Development practices</a><ul>
<li><a class="reference internal" href="#making-changes-to-mapserver">Making changes to MapServer</a></li>
<li><a class="reference internal" href="#git-usage">Git usage</a><ul>
<li><a class="reference internal" href="#initiating-your-work-repository">Initiating your work repository</a></li>
<li><a class="reference internal" href="#working-with-a-feature-branch">Working with a feature branch</a></li>
<li><a class="reference internal" href="#updating-your-local-main-against-upstream-main">Updating your local main against upstream main</a></li>
<li><a class="reference internal" href="#commit-messages">Commit messages</a></li>
<li><a class="reference internal" href="#commit-hooks">Commit hooks</a></li>
<li><a class="reference internal" href="#blame-ignore-file">Blame ignore file</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="Related">
<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="tests/index.html" title="Testing"
>next</a> |</li>
<li class="right" >
<a href="translation.html" title="How to Help Translate the Documentation"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="../index.html">Home</a> »</li>
<li class="nav-item nav-item-1"><a href="index.html" >Development</a> »</li>
<li class="nav-item nav-item-this"><a href="">Development practices</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© <a href="../copyright.html">Copyright</a> 2026, Open Source Geospatial Foundation.
Last updated on 2026-03-30.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 9.1.0.
</div>
</body>
</html>