]>
Commit | Line | Data |
---|---|---|
53ed6d7d | 1 | <!DOCTYPE html> |
2 | <!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]--> | |
3 | <!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]--> | |
4 | <head> | |
5 | <meta charset="utf-8"> | |
6 | <meta http-equiv="X-UA-Compatible" content="IE=edge"> | |
7 | <meta name="viewport" content="width=device-width, initial-scale=1.0"> | |
8 | ||
9 | ||
10 | <link rel="shortcut icon" href="../img/favicon.ico"> | |
11 | <title>Release Shaarli - Shaarli Documentation</title> | |
12 | <link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'> | |
13 | ||
14 | <link rel="stylesheet" href="../css/theme.css" type="text/css" /> | |
15 | <link rel="stylesheet" href="../css/theme_extra.css" type="text/css" /> | |
16 | <link rel="stylesheet" href="../css/highlight.css"> | |
17 | <link href="../github-markdown.css" rel="stylesheet"> | |
18 | ||
19 | <script> | |
20 | // Current page data | |
21 | var mkdocs_page_name = "Release Shaarli"; | |
22 | var mkdocs_page_input_path = "Release-Shaarli.md"; | |
23 | var mkdocs_page_url = "/Release-Shaarli/"; | |
24 | </script> | |
25 | ||
26 | <script src="../js/jquery-2.1.1.min.js"></script> | |
27 | <script src="../js/modernizr-2.8.3.min.js"></script> | |
28 | <script type="text/javascript" src="../js/highlight.pack.js"></script> | |
29 | ||
30 | </head> | |
31 | ||
32 | <body class="wy-body-for-nav" role="document"> | |
33 | ||
34 | <div class="wy-grid-for-nav"> | |
35 | ||
36 | ||
37 | <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav"> | |
38 | <div class="wy-side-nav-search"> | |
39 | <a href=".." class="icon icon-home"> Shaarli Documentation</a> | |
40 | <div role="search"> | |
41 | <form id ="rtd-search-form" class="wy-form" action="../search.html" method="get"> | |
42 | <input type="text" name="q" placeholder="Search docs" /> | |
43 | </form> | |
44 | </div> | |
45 | </div> | |
46 | ||
47 | <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation"> | |
48 | <ul class="current"> | |
49 | ||
50 | ||
51 | <li class="toctree-l1"> | |
52 | ||
53 | <a class="" href="..">Home</a> | |
54 | </li> | |
55 | ||
56 | <li class="toctree-l1"> | |
57 | ||
58 | <span class="caption-text">Setup</span> | |
59 | <ul class="subnav"> | |
60 | <li class=""> | |
61 | ||
62 | <a class="" href="../Download-and-Installation/">Download and Installation</a> | |
63 | </li> | |
64 | <li class=""> | |
65 | ||
66 | <a class="" href="../Upgrade-and-migration/">Upgrade and migration</a> | |
67 | </li> | |
68 | <li class=""> | |
69 | ||
70 | <a class="" href="../Server-requirements/">Server requirements</a> | |
71 | </li> | |
72 | <li class=""> | |
73 | ||
74 | <a class="" href="../Server-configuration/">Server configuration</a> | |
75 | </li> | |
76 | <li class=""> | |
77 | ||
78 | <a class="" href="../Server-security/">Server security</a> | |
79 | </li> | |
80 | <li class=""> | |
81 | ||
82 | <a class="" href="../Shaarli-configuration/">Shaarli configuration</a> | |
83 | </li> | |
84 | <li class=""> | |
85 | ||
86 | <a class="" href="../Plugins/">Plugins</a> | |
87 | </li> | |
88 | </ul> | |
89 | </li> | |
90 | ||
91 | <li class="toctree-l1"> | |
92 | ||
93 | <span class="caption-text">Docker</span> | |
94 | <ul class="subnav"> | |
95 | <li class=""> | |
96 | ||
97 | <a class="" href="../Docker-101/">Docker 101</a> | |
98 | </li> | |
99 | <li class=""> | |
100 | ||
101 | <a class="" href="../Shaarli-images/">Shaarli images</a> | |
102 | </li> | |
103 | <li class=""> | |
104 | ||
105 | <a class="" href="../Reverse-proxy-configuration/">Reverse proxy configuration</a> | |
106 | </li> | |
107 | <li class=""> | |
108 | ||
109 | <a class="" href="../Docker-resources/">Docker resources</a> | |
110 | </li> | |
111 | </ul> | |
112 | </li> | |
113 | ||
114 | <li class="toctree-l1"> | |
115 | ||
116 | <span class="caption-text">Usage</span> | |
117 | <ul class="subnav"> | |
118 | <li class=""> | |
119 | ||
120 | <a class="" href="../Features/">Features</a> | |
121 | </li> | |
122 | <li class=""> | |
123 | ||
124 | <a class="" href="../Bookmarklet/">Bookmarklet</a> | |
125 | </li> | |
126 | <li class=""> | |
127 | ||
128 | <a class="" href="../Browsing-and-searching/">Browsing and searching</a> | |
129 | </li> | |
130 | <li class=""> | |
131 | ||
132 | <a class="" href="../Firefox-share/">Firefox share</a> | |
133 | </li> | |
134 | <li class=""> | |
135 | ||
136 | <a class="" href="../RSS-feeds/">RSS feeds</a> | |
137 | </li> | |
138 | <li class=""> | |
139 | ||
140 | <a class="" href="../REST-API/">REST API</a> | |
141 | </li> | |
142 | </ul> | |
143 | </li> | |
144 | ||
145 | <li class="toctree-l1"> | |
146 | ||
147 | <span class="caption-text">How To</span> | |
148 | <ul class="subnav"> | |
149 | <li class=""> | |
150 | ||
151 | <a class="" href="../Backup,-restore,-import-and-export/">Backup, restore, import and export</a> | |
152 | </li> | |
153 | <li class=""> | |
154 | ||
155 | <a class="" href="../Copy-an-existing-installation-over-SSH-and-serve-it-locally/">Copy an existing installation over SSH and serve it locally</a> | |
156 | </li> | |
157 | <li class=""> | |
158 | ||
159 | <a class="" href="../Create-and-serve-multiple-Shaarlis-(farm)/">Create and serve multiple Shaarlis (farm)</a> | |
160 | </li> | |
161 | <li class=""> | |
162 | ||
163 | <a class="" href="../Download-CSS-styles-from-an-OPML-list/">Download CSS styles from an OPML list</a> | |
164 | </li> | |
165 | <li class=""> | |
166 | ||
167 | <a class="" href="../Datastore-hacks/">Datastore hacks</a> | |
168 | </li> | |
169 | </ul> | |
170 | </li> | |
171 | ||
172 | <li class="toctree-l1"> | |
173 | ||
174 | <a class="" href="../Troubleshooting/">Troubleshooting</a> | |
175 | </li> | |
176 | ||
177 | <li class="toctree-l1"> | |
178 | ||
179 | <span class="caption-text">Development</span> | |
180 | <ul class="subnav"> | |
181 | <li class=""> | |
182 | ||
183 | <a class="" href="../Development-guidelines/">Development guidelines</a> | |
184 | </li> | |
185 | <li class=""> | |
186 | ||
187 | <a class="" href="../Continuous-integration-tools/">Continuous integration tools</a> | |
188 | </li> | |
189 | <li class=""> | |
190 | ||
191 | <a class="" href="../GnuPG-signature/">GnuPG signature</a> | |
192 | </li> | |
193 | <li class=""> | |
194 | ||
195 | <a class="" href="../Coding-guidelines/">Coding guidelines</a> | |
196 | </li> | |
197 | <li class=""> | |
198 | ||
199 | <a class="" href="../Directory-structure/">Directory structure</a> | |
200 | </li> | |
201 | <li class=""> | |
202 | ||
203 | <a class="" href="../3rd-party-libraries/">3rd party libraries</a> | |
204 | </li> | |
205 | <li class=""> | |
206 | ||
207 | <a class="" href="../Plugin-System/">Plugin System</a> | |
208 | </li> | |
209 | <li class=" current"> | |
210 | ||
211 | <a class="current" href="./">Release Shaarli</a> | |
212 | <ul class="subnav"> | |
213 | ||
214 | <li class="toctree-l3"><a href="#prerequisites">Prerequisites</a></li> | |
215 | ||
216 | ||
217 | <li class="toctree-l3"><a href="#github-release-draft-and-changelogmd">GitHub release draft and CHANGELOG.md</a></li> | |
218 | ||
219 | <ul> | |
220 | ||
221 | <li><a class="toctree-l4" href="#github-release-draft">GitHub release draft</a></li> | |
222 | ||
223 | <li><a class="toctree-l4" href="#changelogmd">CHANGELOG.md</a></li> | |
224 | ||
225 | </ul> | |
226 | ||
227 | ||
228 | <li class="toctree-l3"><a href="#increment-the-version-code-updated-docs-create-and-push-a-signed-tag">Increment the version code, updated docs, create and push a signed tag</a></li> | |
229 | ||
230 | <ul> | |
231 | ||
232 | <li><a class="toctree-l4" href="#generate-documentation">Generate documentation</a></li> | |
233 | ||
234 | <li><a class="toctree-l4" href="#create-and-merge-a-pull-request">Create and merge a Pull Request</a></li> | |
235 | ||
236 | <li><a class="toctree-l4" href="#bump-shaarli-version-to-v0x-branch">Bump Shaarli version to v0.x branch</a></li> | |
237 | ||
238 | <li><a class="toctree-l4" href="#create-and-push-a-signed-tag">Create and push a signed tag</a></li> | |
239 | ||
240 | <li><a class="toctree-l4" href="#verify-a-signed-tag">Verify a signed tag</a></li> | |
241 | ||
242 | </ul> | |
243 | ||
244 | ||
245 | <li class="toctree-l3"><a href="#publish-the-github-release">Publish the GitHub release</a></li> | |
246 | ||
247 | <ul> | |
248 | ||
249 | <li><a class="toctree-l4" href="#update-release-badges">Update release badges</a></li> | |
250 | ||
251 | <li><a class="toctree-l4" href="#create-a-github-release-from-a-git-tag">Create a GitHub release from a Git tag</a></li> | |
252 | ||
253 | <li><a class="toctree-l4" href="#generate-and-upload-all-in-one-release-archives">Generate and upload all-in-one release archives</a></li> | |
254 | ||
255 | <li><a class="toctree-l4" href="#update-stable-and-latest-branches">Update stable and latest branches</a></li> | |
256 | ||
257 | </ul> | |
258 | ||
259 | ||
260 | </ul> | |
261 | </li> | |
262 | <li class=""> | |
263 | ||
264 | <a class="" href="../Versioning-and-Branches/">Versioning and Branches</a> | |
265 | </li> | |
266 | <li class=""> | |
267 | ||
268 | <a class="" href="../Security/">Security</a> | |
269 | </li> | |
270 | <li class=""> | |
271 | ||
272 | <a class="" href="../Static-analysis/">Static analysis</a> | |
273 | </li> | |
274 | <li class=""> | |
275 | ||
276 | <a class="" href="../Theming/">Theming</a> | |
277 | </li> | |
278 | <li class=""> | |
279 | ||
280 | <a class="" href="../Unit-tests/">Unit tests</a> | |
281 | </li> | |
282 | </ul> | |
283 | </li> | |
284 | ||
285 | <li class="toctree-l1"> | |
286 | ||
287 | <span class="caption-text">About</span> | |
288 | <ul class="subnav"> | |
289 | <li class=""> | |
290 | ||
291 | <a class="" href="../FAQ/">FAQ</a> | |
292 | </li> | |
293 | <li class=""> | |
294 | ||
295 | <a class="" href="../Community-&-Related-software/">Community & Related software</a> | |
296 | </li> | |
297 | </ul> | |
298 | </li> | |
299 | ||
300 | </ul> | |
301 | </div> | |
302 | | |
303 | </nav> | |
304 | ||
305 | <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"> | |
306 | ||
307 | ||
308 | <nav class="wy-nav-top" role="navigation" aria-label="top navigation"> | |
309 | <i data-toggle="wy-nav-top" class="fa fa-bars"></i> | |
310 | <a href="..">Shaarli Documentation</a> | |
311 | </nav> | |
312 | ||
313 | ||
314 | <div class="wy-nav-content"> | |
315 | <div class="rst-content"> | |
316 | <div role="navigation" aria-label="breadcrumbs navigation"> | |
317 | <ul class="wy-breadcrumbs"> | |
318 | <li><a href="..">Docs</a> »</li> | |
319 | ||
320 | ||
321 | ||
322 | <li>Development »</li> | |
323 | ||
324 | ||
325 | ||
326 | <li>Release Shaarli</li> | |
327 | <li class="wy-breadcrumbs-aside"> | |
328 | ||
329 | <a href="https://github.com/shaarli/Shaarli/edit/master/docs/Release-Shaarli.md" | |
330 | class="icon icon-github"> Edit on GitHub</a> | |
331 | ||
332 | </li> | |
333 | </ul> | |
334 | <hr/> | |
335 | </div> | |
336 | <div role="main"> | |
337 | <div class="section"> | |
338 | ||
339 | <p>See <a href="http://git-scm.com/book/en/v2/Distributed-Git-Maintaining-a-Project#Tagging-Your-Releases">Git - Maintaining a project - Tagging your | |
340 | releases</a>.</p> | |
341 | <h2 id="prerequisites">Prerequisites</h2> | |
342 | <p>This guide assumes that you have: | |
343 | - a GPG key matching your GitHub authentication credentials | |
344 | - i.e., the email address identified by the GPG key is the same as the one in your <code>~/.gitconfig</code> | |
345 | - a GitHub fork of Shaarli | |
346 | - a local clone of your Shaarli fork, with the following remotes: | |
347 | - <code>origin</code> pointing to your GitHub fork | |
348 | - <code>upstream</code> pointing to the main Shaarli repository | |
349 | - maintainer permissions on the main Shaarli repository, to: | |
350 | - push the signed tag | |
351 | - create a new release | |
352 | - <a href="https://getcomposer.org/">Composer</a> and <a href="http://pandoc.org/">Pandoc</a> need to be installed</p> | |
353 | <h2 id="github-release-draft-and-changelogmd">GitHub release draft and <code>CHANGELOG.md</code></h2> | |
354 | <p>See http://keepachangelog.com/en/0.3.0/ for changelog formatting.</p> | |
355 | <h3 id="github-release-draft">GitHub release draft</h3> | |
356 | <p>GitHub allows drafting the release note for the upcoming release, from the <a href="https://github.com/shaarli/Shaarli/releases">Releases</a> page. This way, the release note can be drafted while contributions are merged to <code>master</code>.</p> | |
357 | <h3 id="changelogmd"><code>CHANGELOG.md</code></h3> | |
358 | <p>This file should contain the same information as the release note draft for the upcoming version.</p> | |
359 | <p>Update it to: | |
360 | - add new entries (additions, fixes, etc.) | |
361 | - mark the current version as released by setting its date and link | |
362 | - add a new section for the future unreleased version</p> | |
363 | <pre><code class="bash">$ cd /path/to/shaarli | |
364 | ||
365 | $ nano CHANGELOG.md | |
366 | ||
367 | [...] | |
368 | ## vA.B.C - UNRELEASED | |
369 | TBA | |
370 | ||
371 | ## [vX.Y.Z](https://github.com/shaarli/Shaarli/releases/tag/vX.Y.Z) - YYYY-MM-DD | |
372 | [...] | |
373 | </code></pre> | |
374 | ||
375 | <h2 id="increment-the-version-code-updated-docs-create-and-push-a-signed-tag">Increment the version code, updated docs, create and push a signed tag</h2> | |
376 | <h3 id="generate-documentation">Generate documentation</h3> | |
377 | <pre><code class="bash">$ cd /path/to/shaarli | |
378 | ||
379 | # create a new branch | |
380 | $ git fetch upstream | |
381 | $ git checkout upstream/master -b v0.5.0 | |
382 | ||
383 | # rebuild the documentation from the wiki | |
384 | $ make htmldoc | |
385 | ||
386 | # commit the changes | |
387 | $ git add doc | |
388 | $ git commit -s -m "Generate documentation for v0.5.0" | |
389 | ||
390 | # push the commit on your GitHub fork | |
391 | $ git push origin v0.5.0 | |
392 | </code></pre> | |
393 | ||
394 | <h3 id="create-and-merge-a-pull-request">Create and merge a Pull Request</h3> | |
395 | <p>This one is pretty straightforward ;-)</p> | |
396 | <h3 id="bump-shaarli-version-to-v0x-branch">Bump Shaarli version to v0.x branch</h3> | |
397 | <pre><code>$ git checkout master | |
398 | $ git fetch upstream | |
399 | $ git pull upstream master | |
400 | ||
401 | # IF the branch doesn't exists | |
402 | $ git checkout -b v0.5 | |
403 | # OR if the branch already exists | |
404 | $ git checkout v0.5 | |
405 | $ git rebase upstream/master | |
406 | ||
407 | # Bump shaarli version from dev to 0.5.0, **without the `v`** | |
408 | $ vim shaarli_version.php | |
409 | $ git add shaarli_version | |
410 | $ git commit -s -m "Bump Shaarli version to v0.5.0" | |
411 | $ git push upstream v0.5 | |
412 | </code></pre> | |
413 | ||
414 | <h3 id="create-and-push-a-signed-tag">Create and push a signed tag</h3> | |
415 | <pre><code class="bash"># update your local copy | |
416 | $ git checkout v0.5 | |
417 | $ git fetch upstream | |
418 | $ git pull upstream v0.5 | |
419 | ||
420 | # create a signed tag | |
421 | $ git tag -s -m "Release v0.5.0" v0.5.0 | |
422 | ||
423 | # push it to "upstream" | |
424 | $ git push --tags upstream | |
425 | </code></pre> | |
426 | ||
427 | <h3 id="verify-a-signed-tag">Verify a signed tag</h3> | |
428 | <p><a href="https://github.com/shaarli/Shaarli/releases/tag/v0.5.0"><code>v0.5.0</code></a> is the first GPG-signed tag pushed on the Community Shaarli.</p> | |
429 | <p>Let's have a look at its signature!</p> | |
430 | <pre><code class="bash">$ cd /path/to/shaarli | |
431 | $ git fetch upstream | |
432 | ||
433 | # get the SHA1 reference of the tag | |
434 | $ git show-ref tags/v0.5.0 | |
435 | f7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0 | |
436 | ||
437 | # verify the tag signature information | |
438 | $ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1 | |
439 | gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F | |
440 | gpg: Good signature from "VirtualTam <virtualtam@flibidi.net>" [ultimate] | |
441 | </code></pre> | |
442 | ||
443 | <h2 id="publish-the-github-release">Publish the GitHub release</h2> | |
444 | <h3 id="update-release-badges">Update release badges</h3> | |
445 | <p>Update <code>README.md</code> so version badges display and point to the newly released Shaarli version(s), in the <code>master</code> branch.</p> | |
446 | <h3 id="create-a-github-release-from-a-git-tag">Create a GitHub release from a Git tag</h3> | |
447 | <p>From the previously drafted release: | |
448 | - edit the release notes (if needed) | |
449 | - specify the appropriate Git tag | |
450 | - publish the release | |
451 | - profit!</p> | |
452 | <h3 id="generate-and-upload-all-in-one-release-archives">Generate and upload all-in-one release archives</h3> | |
453 | <p>Users with a shared hosting may have: | |
454 | - no SSH access | |
455 | - no possibility to install PHP packages or server extensions | |
456 | - no possibility to run scripts</p> | |
457 | <p>To ease Shaarli installations, it is possible to generate and upload additional release archives, | |
458 | that will contain Shaarli code plus all required third-party libraries.</p> | |
459 | <p><strong>From the <code>v0.5</code> branch:</strong></p> | |
460 | <pre><code class="bash">$ make release_archive | |
461 | </code></pre> | |
462 | ||
463 | <p>This will create the following archives: | |
464 | - <code>shaarli-vX.Y.Z-full.tar</code> | |
465 | - <code>shaarli-vX.Y.Z-full.zip</code></p> | |
466 | <p>The archives need to be manually uploaded on the previously created GitHub release.</p> | |
467 | <h3 id="update-stable-and-latest-branches">Update <code>stable</code> and <code>latest</code> branches</h3> | |
468 | <pre><code>$ git checkout latest | |
469 | # latest release | |
470 | $ git merge v0.5.0 | |
471 | # fix eventual conflicts | |
472 | $ make test | |
473 | $ git push upstream latest | |
474 | $ git checkout stable | |
475 | # latest previous major | |
476 | $ git merge v0.4.5 | |
477 | # fix eventual conflicts | |
478 | $ make test | |
479 | $ git push upstream stable | |
480 | </code></pre> | |
481 | ||
482 | </div> | |
483 | </div> | |
484 | <footer> | |
485 | ||
486 | <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation"> | |
487 | ||
488 | <a href="../Versioning-and-Branches/" class="btn btn-neutral float-right" title="Versioning and Branches">Next <span class="icon icon-circle-arrow-right"></span></a> | |
489 | ||
490 | ||
491 | <a href="../Plugin-System/" class="btn btn-neutral" title="Plugin System"><span class="icon icon-circle-arrow-left"></span> Previous</a> | |
492 | ||
493 | </div> | |
494 | ||
495 | ||
496 | <hr/> | |
497 | ||
498 | <div role="contentinfo"> | |
499 | <!-- Copyright etc --> | |
500 | ||
501 | </div> | |
502 | ||
503 | Built with <a href="http://www.mkdocs.org">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>. | |
504 | </footer> | |
505 | ||
506 | </div> | |
507 | </div> | |
508 | ||
509 | </section> | |
510 | ||
511 | </div> | |
512 | ||
513 | <div class="rst-versions" role="note" style="cursor: pointer"> | |
514 | <span class="rst-current-version" data-toggle="rst-current-version"> | |
515 | ||
516 | <a href="https://github.com/shaarli/Shaarli" class="fa fa-github" style="float: left; color: #fcfcfc"> GitHub</a> | |
517 | ||
518 | ||
519 | <span><a href="../Plugin-System/" style="color: #fcfcfc;">« Previous</a></span> | |
520 | ||
521 | ||
522 | <span style="margin-left: 15px"><a href="../Versioning-and-Branches/" style="color: #fcfcfc">Next »</a></span> | |
523 | ||
524 | </span> | |
525 | </div> | |
526 | <script src="../js/theme.js"></script> | |
527 | ||
528 | </body> | |
529 | </html> |