From 53ed6d7d1e678d7486337ce67a2f17b30bac21ac Mon Sep 17 00:00:00 2001 From: nodiscc Date: Thu, 26 Jan 2017 18:52:54 +0100 Subject: 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 --- doc/Versioning-and-Branches.html | 156 --------------------------------------- 1 file changed, 156 deletions(-) delete mode 100644 doc/Versioning-and-Branches.html (limited to 'doc/Versioning-and-Branches.html') 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 @@ - - - - - - - Shaarli – Versioning and Branches - - - - - - -
- -
-

Versioning and Branches

-

[WORK IN PROGRESS][](.html)

-

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.

-

master branch

-

The master branch is the development branch. Any new change MUST go through this branch using Pull Requests.

-

Remarks:

- -

v0.x branch

-

This v0.x branch, points to the latest v0.x.y release.

-

Explanation:

-

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.

-

In 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.

-

This workflow allow us to fix any major bug detected, without having to release bleeding edge feature too soon.

-

latest branch

-

This branch point the latest release. It recommended to use it to get the latest tested changes.

-

stable branch

-

The stable branch doesn't contain any major bug, and is one major digit version behind the latest release.

-

For 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.

-

Remarks:

- -

Releases

-

Releases are always made from the latest v0.x branch.

-

Note that for every release, we manually generate a tarball which contains all Shaarli dependencies, making Shaarli's installation only one step.

-

Advices on 3rd party git repos workflow

-

Versioning

-

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 changelog (Draft means not released yet) and the commit log (like tpl folder for themes)). You can either:

- -

Using this, any user will be able to pick the release matching his own Shaarli version.

-

Major bugfix backport releases

-

To be able to support backported fixes, it recommended to use our workflow:

-
# In master, fix the major bug
-git commit -m "Katastrophe"
-git push origin master
-# Get your commit hash
-git log --format="%H" -n 1
-# Create a new branch from your latest release, let's say v0.8.2-1 (the tag name)
-git checkout -b katastrophe v0.8.2-1
-# Backport the fix commit to your brand new branch
-git cherry-pick <fix commit hash>
-git push origin katastrophe
-# Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`
- - -- cgit v1.2.3