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/docker-101/">Docker 101</a>
  98                 </li>
  99                 <li class="">
 100
 101     <a class="" href="../docker/shaarli-images/">Shaarli images</a>
 102                 </li>
 103                 <li class="">
 104
 105     <a class="" href="../docker/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="../Various-hacks/">Various hacks</a>
 156                 </li>
 157     </ul>
 158             </li>
 159
 160             <li class="toctree-l1">
 161
 162     <a class="" href="../Troubleshooting/">Troubleshooting</a>
 163             </li>
 164
 165             <li class="toctree-l1">
 166
 167     <span class="caption-text">Development</span>
 168     <ul class="subnav">
 169                 <li class="">
 170
 171     <a class="" href="../Development-guidelines/">Development guidelines</a>
 172                 </li>
 173                 <li class="">
 174
 175     <a class="" href="../Continuous-integration-tools/">Continuous integration tools</a>
 176                 </li>
 177                 <li class="">
 178
 179     <a class="" href="../GnuPG-signature/">GnuPG signature</a>
 180                 </li>
 181                 <li class="">
 182
 183     <a class="" href="../Coding-guidelines/">Coding guidelines</a>
 184                 </li>
 185                 <li class="">
 186
 187     <a class="" href="../Directory-structure/">Directory structure</a>
 188                 </li>
 189                 <li class="">
 190
 191     <a class="" href="../3rd-party-libraries/">3rd party libraries</a>
 192                 </li>
 193                 <li class="">
 194
 195     <a class="" href="../Plugin-System/">Plugin System</a>
 196                 </li>
 197                 <li class=" current">
 198
 199     <a class="current" href="./">Release Shaarli</a>
 200     <ul class="subnav">
 201
 202     <li class="toctree-l3"><a href="#prerequisites">Prerequisites</a></li>
 203
 204
 205     <li class="toctree-l3"><a href="#github-release-draft-and-changelogmd">GitHub release draft and CHANGELOG.md</a></li>
 206
 207         <ul>
 208
 209             <li><a class="toctree-l4" href="#github-release-draft">GitHub release draft</a></li>
 210
 211             <li><a class="toctree-l4" href="#changelogmd">CHANGELOG.md</a></li>
 212
 213         </ul>
 214
 215
 216     <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>
 217
 218         <ul>
 219
 220             <li><a class="toctree-l4" href="#generate-documentation">Generate documentation</a></li>
 221
 222             <li><a class="toctree-l4" href="#create-and-merge-a-pull-request">Create and merge a Pull Request</a></li>
 223
 224             <li><a class="toctree-l4" href="#bump-shaarli-version-to-v0x-branch">Bump Shaarli version to v0.x branch</a></li>
 225
 226             <li><a class="toctree-l4" href="#create-and-push-a-signed-tag">Create and push a signed tag</a></li>
 227
 228             <li><a class="toctree-l4" href="#verify-a-signed-tag">Verify a signed tag</a></li>
 229
 230         </ul>
 231
 232
 233     <li class="toctree-l3"><a href="#publish-the-github-release">Publish the GitHub release</a></li>
 234
 235         <ul>
 236
 237             <li><a class="toctree-l4" href="#update-release-badges">Update release badges</a></li>
 238
 239             <li><a class="toctree-l4" href="#create-a-github-release-from-a-git-tag">Create a GitHub release from a Git tag</a></li>
 240
 241             <li><a class="toctree-l4" href="#generate-and-upload-all-in-one-release-archives">Generate and upload all-in-one release archives</a></li>
 242
 243             <li><a class="toctree-l4" href="#update-stable-and-latest-branches">Update stable and latest branches</a></li>
 244
 245         </ul>
 246
 247
 248     </ul>
 249                 </li>
 250                 <li class="">
 251
 252     <a class="" href="../Versioning-and-Branches/">Versioning and Branches</a>
 253                 </li>
 254                 <li class="">
 255
 256     <a class="" href="../Security/">Security</a>
 257                 </li>
 258                 <li class="">
 259
 260     <a class="" href="../Static-analysis/">Static analysis</a>
 261                 </li>
 262                 <li class="">
 263
 264     <a class="" href="../Theming/">Theming</a>
 265                 </li>
 266                 <li class="">
 267
 268     <a class="" href="../Unit-tests/">Unit tests</a>
 269                 </li>
 270     </ul>
 271             </li>
 272
 273             <li class="toctree-l1">
 274
 275     <span class="caption-text">About</span>
 276     <ul class="subnav">
 277                 <li class="">
 278
 279     <a class="" href="../FAQ/">FAQ</a>
 280                 </li>
 281                 <li class="">
 282
 283     <a class="" href="../Community-&-Related-software/">Community & Related software</a>
 284                 </li>
 285     </ul>
 286             </li>
 287
 288         </ul>
 289       </div>
 290       &nbsp;
 291     </nav>
 292
 293     <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
 294
 295
 296       <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
 297         <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
 298         <a href="..">Shaarli Documentation</a>
 299       </nav>
 300
 301
 302       <div class="wy-nav-content">
 303         <div class="rst-content">
 304           <div role="navigation" aria-label="breadcrumbs navigation">
 305   <ul class="wy-breadcrumbs">
 306     <li><a href="..">Docs</a> &raquo;</li>
 307
 308
 309
 310           <li>Development &raquo;</li>
 311
 312
 313
 314     <li>Release Shaarli</li>
 315     <li class="wy-breadcrumbs-aside">
 316
 317         <a href="https://github.com/shaarli/Shaarli/edit/master/docs/Release-Shaarli.md"
 318           class="icon icon-github"> Edit on GitHub</a>
 319
 320     </li>
 321   </ul>
 322   <hr/>
 323 </div>
 324           <div role="main">
 325             <div class="section">
 326
 327                 <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
 328 releases</a>.</p>
 329 <h2 id="prerequisites">Prerequisites</h2>
 330 <p>This guide assumes that you have:
 331 - a GPG key matching your GitHub authentication credentials
 332     - i.e., the email address identified by the GPG key is the same as the one in your <code>~/.gitconfig</code>
 333 - a GitHub fork of Shaarli
 334 - a local clone of your Shaarli fork, with the following remotes:
 335     - <code>origin</code> pointing to your GitHub fork
 336     - <code>upstream</code> pointing to the main Shaarli repository
 337 - maintainer permissions on the main Shaarli repository, to:
 338     - push the signed tag
 339     - create a new release
 340 - <a href="https://getcomposer.org/">Composer</a> needs to be installed
 341 - The <a href="https://docs.python.org/3/library/venv.html">venv</a> Python 3 module needs to be installed for HTML documentation generation.</p>
 342 <h2 id="github-release-draft-and-changelogmd">GitHub release draft and <code>CHANGELOG.md</code></h2>
 343 <p>See http://keepachangelog.com/en/0.3.0/ for changelog formatting.</p>
 344 <h3 id="github-release-draft">GitHub release draft</h3>
 345 <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>
 346 <h3 id="changelogmd"><code>CHANGELOG.md</code></h3>
 347 <p>This file should contain the same information as the release note draft for the upcoming version.</p>
 348 <p>Update it to:
 349 - add new entries (additions, fixes, etc.)
 350 - mark the current version as released by setting its date and link
 351 - add a new section for the future unreleased version</p>
 352 <pre><code class="bash">$ cd /path/to/shaarli
 353
 354 $ nano CHANGELOG.md
 355
 356 [...]
 357 ## vA.B.C - UNRELEASED
 358 TBA
 359
 360 ## [vX.Y.Z](https://github.com/shaarli/Shaarli/releases/tag/vX.Y.Z) - YYYY-MM-DD
 361 [...]
 362 </code></pre>
 363
 364 <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>
 365 <h3 id="generate-documentation">Generate documentation</h3>
 366 <pre><code class="bash">$ cd /path/to/shaarli
 367
 368 # create a new branch
 369 $ git fetch upstream
 370 $ git checkout upstream/master -b v0.5.0
 371
 372 # rebuild the HTML documentation from Markdown
 373 $ make htmlpages
 374
 375 # commit the changes
 376 $ git add doc
 377 $ git commit -s -m &quot;Generate documentation for v0.5.0&quot;
 378
 379 # push the commit on your GitHub fork
 380 $ git push origin v0.5.0
 381 </code></pre>
 382
 383 <h3 id="create-and-merge-a-pull-request">Create and merge a Pull Request</h3>
 384 <p>This one is pretty straightforward ;-)</p>
 385 <h3 id="bump-shaarli-version-to-v0x-branch">Bump Shaarli version to v0.x branch</h3>
 386 <pre><code>$ git checkout master
 387 $ git fetch upstream
 388 $ git pull upstream master
 389
 390 # IF the branch doesn't exists
 391 $ git checkout -b v0.5
 392 # OR if the branch already exists
 393 $ git checkout v0.5
 394 $ git rebase upstream/master
 395
 396 # Bump shaarli version from dev to 0.5.0, **without the `v`**
 397 $ vim shaarli_version.php
 398 $ git add shaarli_version
 399 $ git commit -s -m &quot;Bump Shaarli version to v0.5.0&quot;
 400 $ git push upstream v0.5
 401 </code></pre>
 402
 403 <h3 id="create-and-push-a-signed-tag">Create and push a signed tag</h3>
 404 <pre><code class="bash"># update your local copy
 405 $ git checkout v0.5
 406 $ git fetch upstream
 407 $ git pull upstream v0.5
 408
 409 # create a signed tag
 410 $ git tag -s -m &quot;Release v0.5.0&quot; v0.5.0
 411
 412 # push it to &quot;upstream&quot;
 413 $ git push --tags upstream
 414 </code></pre>
 415
 416 <h3 id="verify-a-signed-tag">Verify a signed tag</h3>
 417 <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>
 418 <p>Let's have a look at its signature!</p>
 419 <pre><code class="bash">$ cd /path/to/shaarli
 420 $ git fetch upstream
 421
 422 # get the SHA1 reference of the tag
 423 $ git show-ref tags/v0.5.0
 424 f7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0
 425
 426 # verify the tag signature information
 427 $ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1
 428 gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F
 429 gpg: Good signature from &quot;VirtualTam &lt;virtualtam@flibidi.net&gt;&quot; [ultimate]
 430 </code></pre>
 431
 432 <h2 id="publish-the-github-release">Publish the GitHub release</h2>
 433 <h3 id="update-release-badges">Update release badges</h3>
 434 <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>
 435 <h3 id="create-a-github-release-from-a-git-tag">Create a GitHub release from a Git tag</h3>
 436 <p>From the previously drafted release:
 437 - edit the release notes (if needed)
 438 - specify the appropriate Git tag
 439 - publish the release
 440 - profit!</p>
 441 <h3 id="generate-and-upload-all-in-one-release-archives">Generate and upload all-in-one release archives</h3>
 442 <p>Users with a shared hosting may have:
 443 - no SSH access
 444 - no possibility to install PHP packages or server extensions
 445 - no possibility to run scripts</p>
 446 <p>To ease Shaarli installations, it is possible to generate and upload additional release archives,
 447 that will contain Shaarli code plus all required third-party libraries.</p>
 448 <p><strong>From the <code>v0.5</code> branch:</strong></p>
 449 <pre><code class="bash">$ make release_archive
 450 </code></pre>
 451
 452 <p>This will create the following archives:
 453 - <code>shaarli-vX.Y.Z-full.tar</code>
 454 - <code>shaarli-vX.Y.Z-full.zip</code></p>
 455 <p>The archives need to be manually uploaded on the previously created GitHub release.</p>
 456 <h3 id="update-stable-and-latest-branches">Update <code>stable</code> and <code>latest</code> branches</h3>
 457 <pre><code>$ git checkout latest
 458 # latest release
 459 $ git merge v0.5.0
 460 # fix eventual conflicts
 461 $ make test
 462 $ git push upstream latest
 463 $ git checkout stable
 464 # latest previous major
 465 $ git merge v0.4.5
 466 # fix eventual conflicts
 467 $ make test
 468 $ git push upstream stable
 469 </code></pre>
 470
 471             </div>
 472           </div>
 473           <footer>
 474
 475     <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
 476
 477         <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>
 478
 479
 480         <a href="../Plugin-System/" class="btn btn-neutral" title="Plugin System"><span class="icon icon-circle-arrow-left"></span> Previous</a>
 481
 482     </div>
 483
 484
 485   <hr/>
 486
 487   <div role="contentinfo">
 488     <!-- Copyright etc -->
 489
 490   </div>
 491
 492   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>.
 493 </footer>
 494
 495         </div>
 496       </div>
 497
 498     </section>
 499
 500   </div>
 501
 502   <div class="rst-versions" role="note" style="cursor: pointer">
 503     <span class="rst-current-version" data-toggle="rst-current-version">
 504
 505           <a href="https://github.com/shaarli/Shaarli" class="fa fa-github" style="float: left; color: #fcfcfc"> GitHub</a>
 506
 507
 508         <span><a href="../Plugin-System/" style="color: #fcfcfc;">&laquo; Previous</a></span>
 509
 510
 511         <span style="margin-left: 15px"><a href="../Versioning-and-Branches/" style="color: #fcfcfc">Next &raquo;</a></span>
 512
 513     </span>
 514 </div>
 515     <script src="../js/theme.js"></script>
 516
 517 </body>
 518 </html>