aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/md/dev/Versioning.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/md/dev/Versioning.md')
-rw-r--r--doc/md/dev/Versioning.md63
1 files changed, 63 insertions, 0 deletions
diff --git a/doc/md/dev/Versioning.md b/doc/md/dev/Versioning.md
new file mode 100644
index 00000000..32c80a5c
--- /dev/null
+++ b/doc/md/dev/Versioning.md
@@ -0,0 +1,63 @@
1# Versioning
2
3If you're maintaining a 3rd party tool for Shaarli (theme, plugin, etc.), It's important to understand how Shaarli branches work ensure your tool stays compatible.
4
5
6## `master` branch
7
8The `master` branch is the development branch. Any new change MUST go through this branch using Pull Requests.
9
10Remarks:
11
12- This branch shouldn't be used for production as it isn't necessary stable.
13- 3rd party aren't required to be compatible with the latest changes.
14- Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.
15
16
17## `v0.x` branch
18
19The `v0.x` branch points to the latest `v0.x.y` release.
20
21If a major bug affects the original `v0.x.0` release, we may [backport](https://en.wikipedia.org/wiki/Backporting) a fix for this bug from master, to the `v0.x` branch, and create a new bugfix release (eg. `v0.x.1`) from this branch.
22
23This allows users of the original release to upgrade to the fixed version, without having to upgrade to a completely new minor/major release.
24
25
26## `latest` branch
27
28This branch point the latest release. It recommended to use it to get the latest tested changes.
29
30
31## Releases
32
33For every release, we manually generate a .zip file which contains all Shaarli dependencies, making Shaarli's installation only one step.
34
35
36## Advices on 3rd party git repos workflow
37
38### Versioning
39
40Any 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 [changelog](https://github.com/shaarli/Shaarli/releases) (*Draft* means not released yet) and the commit log (like [`tpl` folder](https://github.com/shaarli/Shaarli/commits/master/tpl/default) for themes)). You can either:
41
42 - use the Shaarli version number, with your repo version. For example, if Shaarli `v0.8.3` is released, publish a `v0.8.3-1` release, where `v0.8.3` states Shaarli compatibility and `-1` is your own version digit for the current Shaarli version.
43 - use your own versioning scheme, and state Shaarli compatibility in the release description.
44
45Using this, any user will be able to pick the release matching his own Shaarli version.
46
47### Major bugfix backport releases
48
49To be able to support backported fixes, it recommended to use our workflow:
50
51```bash
52# In master, fix the major bug
53git commit -m "Katastrophe"
54git push origin master
55# Get your commit hash
56git log --format="%H" -n 1
57# Create a new branch from your latest release, let's say v0.8.2-1 (the tag name)
58git checkout -b katastrophe v0.8.2-1
59# Backport the fix commit to your brand new branch
60git cherry-pick <fix commit hash>
61git push origin katastrophe
62# Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`
63```