aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/Versioning-and-Branches.html
diff options
context:
space:
mode:
authornodiscc <nodiscc@gmail.com>2017-01-26 18:52:54 +0100
committernodiscc <nodiscc@gmail.com>2017-06-18 00:19:49 +0200
commit53ed6d7d1e678d7486337ce67a2f17b30bac21ac (patch)
treef8bef0164a70bd03d2b9781951c01bdd018f1842 /doc/Versioning-and-Branches.html
parentd5d22a6d07917865c44148ad76f43c65a929a890 (diff)
downloadShaarli-53ed6d7d1e678d7486337ce67a2f17b30bac21ac.tar.gz
Shaarli-53ed6d7d1e678d7486337ce67a2f17b30bac21ac.tar.zst
Shaarli-53ed6d7d1e678d7486337ce67a2f17b30bac21ac.zip
Generate HTML documentation using MkDocs (WIP)
MkDocs is a static site generator geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML file. * http://www.mkdocs.org/ * http://www.mkdocs.org/user-guide/configuration/ Ref. #312 * remove pandoc-generated HTML documentation * move markdown doc to doc/md/, * mkdocs.yml: * generate HTML doc in doc/html * add pages TOC/ordering * use index.md as index page * Makefile: remove execute permissions from generated files * Makefile: rewrite htmlpages GFM to markdown conversion using sed: awk expression aslo matched '][' which causes invalid output on complex links with images or code blocks * Add mkdocs.yml to .gitattributes, exclude this file from release archives * Makefile: rename: htmldoc -> doc_html target * run make doc: pull latest markdown documentation from wiki * run make htmlpages: update html documentation
Diffstat (limited to 'doc/Versioning-and-Branches.html')
-rw-r--r--doc/Versioning-and-Branches.html156
1 files changed, 0 insertions, 156 deletions
diff --git a/doc/Versioning-and-Branches.html b/doc/Versioning-and-Branches.html
deleted file mode 100644
index 4dfe4a91..00000000
--- a/doc/Versioning-and-Branches.html
+++ /dev/null
@@ -1,156 +0,0 @@
1<!DOCTYPE html>
2<html>
3<head>
4 <meta charset="utf-8">
5 <meta name="generator" content="pandoc">
6 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
7 <title>Shaarli – Versioning and Branches</title>
8 <style type="text/css">code{white-space: pre;}</style>
9 <style type="text/css">
10div.sourceCode { overflow-x: auto; }
11table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
12 margin: 0; padding: 0; vertical-align: baseline; border: none; }
13table.sourceCode { width: 100%; line-height: 100%; }
14td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
15td.sourceCode { padding-left: 5px; }
16code > span.kw { color: #007020; font-weight: bold; } /* Keyword */
17code > span.dt { color: #902000; } /* DataType */
18code > span.dv { color: #40a070; } /* DecVal */
19code > span.bn { color: #40a070; } /* BaseN */
20code > span.fl { color: #40a070; } /* Float */
21code > span.ch { color: #4070a0; } /* Char */
22code > span.st { color: #4070a0; } /* String */
23code > span.co { color: #60a0b0; font-style: italic; } /* Comment */
24code > span.ot { color: #007020; } /* Other */
25code > span.al { color: #ff0000; font-weight: bold; } /* Alert */
26code > span.fu { color: #06287e; } /* Function */
27code > span.er { color: #ff0000; font-weight: bold; } /* Error */
28code > span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
29code > span.cn { color: #880000; } /* Constant */
30code > span.sc { color: #4070a0; } /* SpecialChar */
31code > span.vs { color: #4070a0; } /* VerbatimString */
32code > span.ss { color: #bb6688; } /* SpecialString */
33code > span.im { } /* Import */
34code > span.va { color: #19177c; } /* Variable */
35code > span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
36code > span.op { color: #666666; } /* Operator */
37code > span.bu { } /* BuiltIn */
38code > span.ex { } /* Extension */
39code > span.pp { color: #bc7a00; } /* Preprocessor */
40code > span.at { color: #7d9029; } /* Attribute */
41code > span.do { color: #ba2121; font-style: italic; } /* Documentation */
42code > span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
43code > span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
44code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
45 </style>
46 <link rel="stylesheet" href="github-markdown.css">
47 <!--[if lt IE 9]>
48 <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
49 <![endif]-->
50</head>
51<body>
52<div id="local-sidebar">
53<ul>
54<li><a href="Home.html">Home</a></li>
55<li>Setup
56<ul>
57<li><a href="Download-and-Installation.html">Download and Installation</a></li>
58<li><a href="Upgrade-and-migration.html">Upgrade and migration</a></li>
59<li><a href="Server-requirements.html">Server requirements</a></li>
60<li><a href="Server-configuration.html">Server configuration</a></li>
61<li><a href="Server-security.html">Server security</a></li>
62<li><a href="Shaarli-configuration.html">Shaarli configuration</a></li>
63<li><a href="Plugins.html">Plugins</a></li>
64</ul></li>
65<li><a href="Docker.html">Docker</a></li>
66<li><a href="Usage.html">Usage</a>
67<ul>
68<li><a href="Sharing-button.html">Sharing button</a> (bookmarklet)</li>
69<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
70<li><a href="Firefox-share.html">Firefox share</a></li>
71<li><a href="RSS-feeds.html">RSS feeds</a></li>
72<li><a href="REST-API.html">REST API</a></li>
73</ul></li>
74<li>How To
75<ul>
76<li><a href="Backup,-restore,-import-and-export.html">Backup, restore, import and export</a></li>
77<li><a href="Copy-an-existing-installation-over-SSH-and-serve-it-locally.html">Copy an existing installation over SSH and serve it locally</a></li>
78<li><a href="Create-and-serve-multiple-Shaarlis-(farm).html">Create and serve multiple Shaarlis (farm)</a></li>
79<li><a href="Download-CSS-styles-from-an-OPML-list.html">Download CSS styles from an OPML list</a></li>
80<li><a href="Datastore-hacks.html">Datastore hacks</a></li>
81</ul></li>
82<li><a href="Troubleshooting.html">Troubleshooting</a></li>
83<li><a href="Development.html">Development</a>
84<ul>
85<li><a href="GnuPG-signature.html">GnuPG signature</a></li>
86<li><a href="Coding-guidelines.html">Coding guidelines</a></li>
87<li><a href="Directory-structure.html">Directory structure</a></li>
88<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
89<li><a href="Plugin-System.html">Plugin System</a></li>
90<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
91<li><a href="Versioning-and-Branches.html">Versioning and Branches</a></li>
92<li><a href="Security.html">Security</a></li>
93<li><a href="Static-analysis.html">Static analysis</a></li>
94<li><a href="Theming.html">Theming</a></li>
95<li><a href="Unit-tests.html">Unit tests</a></li>
96</ul></li>
97<li>About
98<ul>
99<li><a href="FAQ.html">FAQ</a></li>
100<li><a href="Community-&amp;-Related-software.html">Community &amp; Related software</a></li>
101</ul></li>
102</ul>
103</div>
104<h1 id="versioning-and-branches">Versioning and Branches</h1>
105<p>[<strong>WORK IN PROGRESS</strong>][](.html)</p>
106<p>It's important to understand how Shaarli branches work, especially if you're maintaining a 3rd party tools for Shaarli (theme, plugin, etc.), to be sure stay compatible.</p>
107<h2 id="master-branch"><code>master</code> branch</h2>
108<p>The <code>master</code> branch is the development branch. Any new change MUST go through this branch using Pull Requests.</p>
109<p>Remarks:</p>
110<ul>
111<li>This branch shouldn't be used for production as it isn't necessary stable.</li>
112<li>3rd party aren't required to be compatible with the latest changes.</li>
113<li>Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.</li>
114<li>The version in this branch is always <code>dev</code>.</li>
115</ul>
116<h2 id="v0.x-branch"><code>v0.x</code> branch</h2>
117<p>This <code>v0.x</code> branch, points to the latest <code>v0.x.y</code> release.</p>
118<p>Explanation:</p>
119<p>When a new version is released, it might contains a major bug which isn't detected right away. For example, a new PHP version is released, containing backward compatibility issue which doesn't work with Shaarli.</p>
120<p>In this case, the issue is fixed in the <code>master</code> branch, and the fix is backported the to the <code>v0.x</code> branch. Then a new release is made from the <code>v0.x</code> branch.</p>
121<p>This workflow allow us to fix any major bug detected, without having to release bleeding edge feature too soon.</p>
122<h2 id="latest-branch"><code>latest</code> branch</h2>
123<p>This branch point the latest release. It recommended to use it to get the latest tested changes.</p>
124<h2 id="stable-branch"><code>stable</code> branch</h2>
125<p>The <code>stable</code> branch doesn't contain any major bug, and is one major digit version behind the latest release.</p>
126<p>For example, the current latest release is <code>v0.8.3</code>, the stable branch is an alias to the latest <code>v0.7.x</code> release. When the <code>v0.9.0</code> version will be released, the stable will move to the latest <code>v0.8.x</code> release.</p>
127<p>Remarks:</p>
128<ul>
129<li>Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.</li>
130</ul>
131<h2 id="releases">Releases</h2>
132<p>Releases are always made from the latest <code>v0.x</code> branch.</p>
133<p>Note that for every release, we manually generate a tarball which contains all Shaarli dependencies, making Shaarli's installation only one step.</p>
134<h2 id="advices-on-3rd-party-git-repos-workflow">Advices on 3rd party git repos workflow</h2>
135<h3 id="versioning">Versioning</h3>
136<p>Any time a new Shaarli release is published, you should publish a new release of your repo if the changes affected you since the latest release (take a look at the <a href="https://github.com/shaarli/Shaarli/releases">changelog</a> (<em>Draft</em> means not released yet) and the commit log (like <a href="https://github.com/shaarli/Shaarli/commits/master/tpl/default"><code>tpl</code> folder</a> for themes)). You can either:<a href=".html"></a></p>
137<ul>
138<li>use the Shaarli version number, with your repo version. For example, if Shaarli <code>v0.8.3</code> is released, publish a <code>v0.8.3-1</code> release, where <code>v0.8.3</code> states Shaarli compatibility and <code>-1</code> is your own version digit for the current Shaarli version.</li>
139<li>use your own versioning scheme, and state Shaarli compatibility in the release description.</li>
140</ul>
141<p>Using this, any user will be able to pick the release matching his own Shaarli version.</p>
142<h3 id="major-bugfix-backport-releases">Major bugfix backport releases</h3>
143<p>To be able to support backported fixes, it recommended to use our workflow:</p>
144<div class="sourceCode"><pre class="sourceCode bash"><code class="sourceCode bash"><span class="co"># In master, fix the major bug</span>
145<span class="fu">git</span> commit -m <span class="st">&quot;Katastrophe&quot;</span>
146<span class="fu">git</span> push origin master
147<span class="co"># Get your commit hash</span>
148<span class="fu">git</span> log --format=<span class="st">&quot;%H&quot;</span> -n 1
149<span class="co"># Create a new branch from your latest release, let&#39;s say v0.8.2-1 (the tag name)</span>
150<span class="fu">git</span> checkout -b katastrophe v0.8.2-1
151<span class="co"># Backport the fix commit to your brand new branch</span>
152<span class="fu">git</span> cherry-pick <span class="op">&lt;</span>fix commit hash<span class="op">&gt;</span>
153<span class="fu">git</span> push origin katastrophe
154<span class="co"># Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`</span></code></pre></div>
155</body>
156</html>
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-11 07:40:10 +0000