doc/html/Release-Shaarli/index.html

   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       &nbsp;
 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> &raquo;</li>
 319
 320
 321
 322           <li>Development &raquo;</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 &quot;Generate documentation for v0.5.0&quot;
 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 &quot;Bump Shaarli version to v0.5.0&quot;
 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 &quot;Release v0.5.0&quot; v0.5.0
 422
 423 # push it to &quot;upstream&quot;
 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 &quot;VirtualTam &lt;virtualtam@flibidi.net&gt;&quot; [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;">&laquo; Previous</a></span>
 520
 521
 522         <span style="margin-left: 15px"><a href="../Versioning-and-Branches/" style="color: #fcfcfc">Next &raquo;</a></span>
 523
 524     </span>
 525 </div>
 526     <script src="../js/theme.js"></script>
 527
 528 </body>
 529 </html>