aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/Versioning-and-Branches.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/Versioning-and-Branches.md')
-rw-r--r--doc/Versioning-and-Branches.md76
1 files changed, 0 insertions, 76 deletions
diff --git a/doc/Versioning-and-Branches.md b/doc/Versioning-and-Branches.md
deleted file mode 100644
index bbc7719e..00000000
--- a/doc/Versioning-and-Branches.md
+++ /dev/null
@@ -1,76 +0,0 @@
1#Versioning and Branches
2[**WORK IN PROGRESS**][](.html)
3
4It'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.
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 * The version in this branch is always `dev`.
16
17## `v0.x` branch
18
19This `v0.x` branch, points to the latest `v0.x.y` release.
20
21Explanation:
22
23When 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.
24
25In this case, the issue is fixed in the `master` branch, and the fix is backported the to the `v0.x` branch. Then a new release is made from the `v0.x` branch.
26
27This workflow allow us to fix any major bug detected, without having to release bleeding edge feature too soon.
28
29## `latest` branch
30
31This branch point the latest release. It recommended to use it to get the latest tested changes.
32
33## `stable` branch
34
35The `stable` branch doesn't contain any major bug, and is one major digit version behind the latest release.
36
37For example, the current latest release is `v0.8.3`, the stable branch is an alias to the latest `v0.7.x` release. When the `v0.9.0` version will be released, the stable will move to the latest `v0.8.x` release.
38
39Remarks:
40
41 * Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.
42
43## Releases
44
45Releases are always made from the latest `v0.x` branch.
46
47Note that for every release, we manually generate a tarball which contains all Shaarli dependencies, making Shaarli's installation only one step.
48
49## Advices on 3rd party git repos workflow
50
51### Versioning
52
53Any 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:[](.html)
54
55 - 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.
56 - use your own versioning scheme, and state Shaarli compatibility in the release description.
57
58Using this, any user will be able to pick the release matching his own Shaarli version.
59
60### Major bugfix backport releases
61
62To be able to support backported fixes, it recommended to use our workflow:
63
64```bash
65# In master, fix the major bug
66git commit -m "Katastrophe"
67git push origin master
68# Get your commit hash
69git log --format="%H" -n 1
70# Create a new branch from your latest release, let's say v0.8.2-1 (the tag name)
71git checkout -b katastrophe v0.8.2-1
72# Backport the fix commit to your brand new branch
73git cherry-pick <fix commit hash>
74git push origin katastrophe
75# Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`
76```