From b230bf207df576fa2ad165702184edf21f674ce7 Mon Sep 17 00:00:00 2001 From: ArthurHoaro Date: Sun, 7 May 2017 18:44:05 +0200 Subject: Bump version to v0.9.0 Signed-off-by: ArthurHoaro --- doc/3rd-party-libraries.html | 2 + doc/Backup,-restore,-import-and-export.html | 2 + doc/Browsing-and-searching.html | 4 +- doc/Browsing-and-searching.md | 4 +- doc/Coding-guidelines.html | 2 + doc/Community-&-Related-software.html | 10 ++ doc/Community-&-Related-software.md | 6 + ...installation-over-SSH-and-serve-it-locally.html | 2 + doc/Create-and-serve-multiple-Shaarlis-(farm).html | 2 + doc/Datastore-hacks.html | 2 + doc/Development.html | 2 + doc/Directory-structure.html | 42 ++--- doc/Docker.html | 13 +- doc/Docker.md | 1 + doc/Download-CSS-styles-from-an-OPML-list.html | 4 +- doc/Download-and-Installation.html | 18 ++- doc/Download-and-Installation.md | 16 +- ...xample-patch---add-new-via-field-for-links.html | 2 + doc/FAQ.html | 2 + doc/Firefox-share.html | 2 + doc/GnuPG-signature.html | 2 + doc/Home.html | 2 + doc/Plugin-System.html | 117 ++++++++++++-- doc/Plugin-System.md | 130 +++++++++++++++- doc/Plugins.html | 3 +- doc/Plugins.md | 1 - doc/REST-API.html | 169 +++++++++++++++++++++ doc/REST-API.md | 105 +++++++++++++ doc/RSS-feeds.html | 2 + doc/Release-Shaarli.html | 4 + doc/Release-Shaarli.md | 3 + doc/Security.html | 2 + doc/Server-configuration.html | 16 ++ doc/Server-configuration.md | 15 ++ doc/Server-requirements.html | 25 ++- doc/Server-requirements.md | 3 + doc/Server-security.html | 2 + doc/Shaarli-configuration.html | 3 + doc/Shaarli-configuration.md | 1 + doc/Sharing-button.html | 2 + doc/Static-analysis.html | 2 + doc/Theming.html | 58 ++++--- doc/Theming.md | 54 ++++--- doc/Troubleshooting.html | 4 +- doc/Unit-tests.html | 14 ++ doc/Unit-tests.md | 19 +++ doc/Upgrade-and-migration.html | 37 +++-- doc/Upgrade-and-migration.md | 41 ++++- doc/Usage.html | 2 + doc/Versioning-and-Branches.html | 156 +++++++++++++++++++ doc/Versioning-and-Branches.md | 76 +++++++++ doc/_Footer.html | 2 + doc/_Sidebar.html | 4 + doc/_Sidebar.md | 2 + doc/sidebar.html | 2 + 55 files changed, 1086 insertions(+), 132 deletions(-) create mode 100644 doc/REST-API.html create mode 100644 doc/REST-API.md create mode 100644 doc/Versioning-and-Branches.html create mode 100644 doc/Versioning-and-Branches.md (limited to 'doc') diff --git a/doc/3rd-party-libraries.html b/doc/3rd-party-libraries.html index 946ca037..50aba6c0 100644 --- a/doc/3rd-party-libraries.html +++ b/doc/3rd-party-libraries.html @@ -32,6 +32,7 @@
  • Browsing and Searching
  • Firefox share
  • RSS feeds
    • +
  • REST API
  • How To
  • How To
  • How To
      @@ -50,6 +51,7 @@
    • 3rd party libraries
    • Plugin System
    • Release Shaarli
      • +
    • Versioning and Branches
    • Security
    • Static analysis
    • Theming
      • @@ -64,7 +66,6 @@

      Browsing and searching

      Browsing and Searching

      -

      Status: DRAFT

      Plain text search

      Use the Search text field to search in any of the fields of all links (Title, URL, Description...)

      @@ -75,6 +76,7 @@

      Use the Filter by tags field to restrict displayed links to entries tagged with one or multiple tags (use space to separate tags).

      Hidden tags: Tags starting with a dot . (example .secret) are private. They can only be seen and searched when logged in.

      Alternatively you can use the Tag cloud to discover all tags and click on any of them to display related links.

      +

      To search for links that are not tagged, enter "" in the tag search field.

      Filtering RSS feeds/Picture wall

      RSS feeds can also be restricted to only return items matching a text/tag search: see RSS feeds.

      diff --git a/doc/Browsing-and-searching.md b/doc/Browsing-and-searching.md index 187fe447..854b6b60 100644 --- a/doc/Browsing-and-searching.md +++ b/doc/Browsing-and-searching.md @@ -1,8 +1,6 @@ #Browsing and searching # Browsing and Searching -Status: DRAFT - ![(http://pix.toile-libre.org/upload/original/1455571378.png)]((http://pix.toile-libre.org/upload/original/1455571378.png).html) ## Plain text search @@ -23,6 +21,8 @@ Use the `Filter by tags` field to restrict displayed links to entries tagged wit Alternatively you can use the `Tag cloud` to discover all tags and click on any of them to display related links. +To search for links that are not tagged, enter `""` in the tag search field. + ## Filtering RSS feeds/Picture wall RSS feeds can also be restricted to only return items matching a text/tag search: see [RSS feeds](RSS-feeds.html). diff --git a/doc/Coding-guidelines.html b/doc/Coding-guidelines.html index 1a2a9351..8df12182 100644 --- a/doc/Coding-guidelines.html +++ b/doc/Coding-guidelines.html @@ -32,6 +32,7 @@
    • Browsing and Searching
    • Firefox share
    • RSS feeds
      • +
    • REST API
  • How To
  • How To +

    Articles and social media discussions

    +

    Third party plugins

    • autosave by @kalvn: Automatically saves data when editing a link to avoid any loss in case of crash or unexpected shutdown.
    • Code Coloration by @ArthurHoaro: client side code syntax highlighter.
    • Disqus by @kalvn: Adds Disqus comment system to your Shaarli.
    • emojione by @NerosTie: Add colorful emojis to your Shaarli.
      • +
    • google analytics by @ericjuden: Adds Google Analytics tracking support
    • launch - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.
    • social by @alexisju: share links to social networks.
    • shaarli2twitter by @ArthurHoaro - Automatically tweet your shared links from Shaarli
      • diff --git a/doc/Community-&-Related-software.md b/doc/Community-&-Related-software.md index 291bf643..52123a1e 100644 --- a/doc/Community-&-Related-software.md +++ b/doc/Community-&-Related-software.md @@ -14,6 +14,11 @@ _TODO: contact repos owners to see if they'd like to standardize their work with - [Original revisions history](http://sebsauvage.net/wiki/doku.php?id=php:shaarli:history)[](.html) - [Shaarli.fr/my](https://www.shaarli.fr/my.php) - Unofficial, unsupported (old fork) hosted Shaarlis provider, courtesy of [DMeloni](https://github.com/DMeloni)[](.html) +### Articles and social media discussions +- 2016-09-22 - Hacker News - https://news.ycombinator.com/item?id=12552176 +- 2015-08-15 - Reddit - [Question about migrating from WordPress to Shaarli.](https://www.reddit.com/r/selfhosted/comments/3h3zwh/question_about_migrating_from_wordpress_to_shaarli/)[](.html) +- 2015-06-22 - Hacker News - https://news.ycombinator.com/item?id=9755366 +- 2015-05-12 - Reddit - [shaarli - Self hosted Bookmarking / Delicious (PHP, MySQL)](https://www.reddit.com/r/selfhosted/comments/35pkkc/shaarli_self_hosted_bookmarking_delicious_php/)[](.html) ### Third party plugins @@ -22,6 +27,7 @@ _TODO: contact repos owners to see if they'd like to standardize their work with * [Code Coloration](https://github.com/ArthurHoaro/code-coloration) by [@ArthurHoaro](https://github.com/ArthurHoaro): client side code syntax highlighter.[](.html) * [Disqus](https://github.com/kalvn/shaarli-plugin-disqus) by [@kalvn](https://github.com/kalvn): Adds Disqus comment system to your Shaarli.[](.html) * [emojione](https://github.com/NerosTie/emojione) by [@NerosTie](https://github.com/NerosTie): Add colorful emojis to your Shaarli.[](.html) + * [google analytics](https://github.com/ericjuden/Shaarli-Google-Analytics-Plugin) by [@ericjuden](http://github.com/ericjuden): Adds Google Analytics tracking support[](.html) * [launch](https://github.com/ArthurHoaro/launch-plugin) - Launch Plugin is a plugin designed to enhance and customize Launch Theme for Shaarli.[](.html) * [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks.[](.html) * [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli[](.html) diff --git a/doc/Copy-an-existing-installation-over-SSH-and-serve-it-locally.html b/doc/Copy-an-existing-installation-over-SSH-and-serve-it-locally.html index 9efb1ad6..d6b76add 100644 --- a/doc/Copy-an-existing-installation-over-SSH-and-serve-it-locally.html +++ b/doc/Copy-an-existing-installation-over-SSH-and-serve-it-locally.html @@ -69,6 +69,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
    • Browsing and Searching
    • Firefox share
    • RSS feeds
      • +
    • REST API
  • How To
  • How To
  • How To
  • How To
  • How To
      @@ -87,6 +88,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
    • 3rd party libraries
    • Plugin System
    • Release Shaarli
      • +
    • Versioning and Branches
    • Security
    • Static analysis
    • Theming
      • @@ -101,33 +103,33 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf

      Directory structure

      Here is the directory structure of Shaarli and the purpose of the different files:

      -
          index.php        # Main program
-    application/     # Shaarli classes
+
          index.php        # Main program
+    application/     # Shaarli classes
         ├── LinkDB.php
         └── Utils.php
-    tests/       # Shaarli unitary & functional tests
+    tests/       # Shaarli unitary & functional tests
         ├── LinkDBTest.php
-        ├── utils  # utilities to ease testing
+        ├── utils  # utilities to ease testing
         │   └── ReferenceLinkDB.php
         └── UtilsTest.php
-    COPYING          # Shaarli license
-    inc/             # static assets and 3rd party libraries
-        ├── awesomplete.*          # tags autocompletion library
-        ├── blazy.*                # picture wall lazy image loading library
+    COPYING          # Shaarli license
+    inc/             # static assets and 3rd party libraries
+        ├── awesomplete.*          # tags autocompletion library
+        ├── blazy.*                # picture wall lazy image loading library
         ├── shaarli.css, reset.css # Shaarli stylesheet.
-        ├── qr.*                   # qr code generation library
-        └──rain.tpl.class.php      # RainTPL templating library
-    tpl/             # RainTPL templates for Shaarli. They are used to build the pages.
-    images/          # Images and icons used in Shaarli
-    data/            # data storage: bookmark database, configuration, logs, banlist…
-        ├── config.php             # Shaarli configuration (login, password, timezone, title…)
-        ├── datastore.php          # Your link database (compressed).
-        ├── ipban.php              # IP address ban system data
-        ├── lastupdatecheck.txt    # Update check timestamp file
-        └──log.txt                 # login/IPban log.
-    cache/           # thumbnails cache
+        ├── qr.*                   # qr code generation library
+        └──rain.tpl.class.php      # RainTPL templating library
+    tpl/             # RainTPL templates for Shaarli. They are used to build the pages.
+    images/          # Images and icons used in Shaarli
+    data/            # data storage: bookmark database, configuration, logs, banlist…
+        ├── config.php             # Shaarli configuration (login, password, timezone, title…)
+        ├── datastore.php          # Your link database (compressed).
+        ├── ipban.php              # IP address ban system data
+        ├── lastupdatecheck.txt    # Update check timestamp file
+        └──log.txt                 # login/IPban log.
+    cache/           # thumbnails cache
                      # This directory is automatically created. You can erase it anytime you want.
-    tmp/             # Temporary directory for compiled RainTPL templates.
+    tmp/             # Temporary directory for compiled RainTPL templates.
                      # This directory is automatically created. You can erase it anytime you want.
      
 
 
diff --git a/doc/Docker.html b/doc/Docker.html
index e89c90fb..fd0dec4b 100644
--- a/doc/Docker.html
+++ b/doc/Docker.html
@@ -69,6 +69,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
 
    • Browsing and Searching
      • 
 
    • Firefox share
      • 
 
    • RSS feeds
      • 
+
    • REST API
      •
  • How To
      @@ -87,6 +88,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
    • 3rd party libraries
    • Plugin System
    • Release Shaarli
      • +
    • Versioning and Branches
    • Security
    • Static analysis
    • Theming
      • @@ -200,7 +202,7 @@ $ docker ps CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 15 seconds ago Up 4 seconds 0.0.0.0:8000->80/tcp backstabbing_galileo

      Stop and destroy a container

      -
      $ docker stop backstabbing_galileo  # those docker guys are really rude to physicists!
+
      $ docker stop backstabbing_galileo  # those docker guys are really rude to physicists!
 backstabbing_galileo
 
 # check the container is stopped
@@ -213,14 +215,15 @@ $ docker ps -a
 d40b7af693d6        shaarli/shaarli     /usr/bin/supervisor   5 minutes ago       Exited (0) 48 seconds ago                       backstabbing_galileo
 
 # destroy the container
-$ docker rm backstabbing_galileo  # let's put an end to these barbarian practices
-backstabbing_galileo
+$ docker rm backstabbing_galileo  # let's put an end to these barbarian practices
+backstabbing_galileo
 
-$ docker ps -a
-CONTAINER ID  IMAGE            COMMAND               CREATED         STATUS        PORTS                 NAMES
      
+$ docker ps -a
+CONTAINER ID  IMAGE            COMMAND               CREATED         STATUS        PORTS                 NAMES

      Resources

      Docker

        +
      • Interactive Docker training portal on Katakoda
      • Where are Docker images stored?
      • Dockerfile reference
      • Dockerfile best practices
        • diff --git a/doc/Docker.md b/doc/Docker.md index 1faa7904..a7d2efb5 100644 --- a/doc/Docker.md +++ b/doc/Docker.md @@ -141,6 +141,7 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS ## Resources ### Docker +- [Interactive Docker training portal](https://www.katacoda.com/courses/docker/) on [Katakoda](https://www.katacoda.com/)[](.html) - [Where are Docker images stored?](http://blog.thoward37.me/articles/where-are-docker-images-stored/)[](.html) - [Dockerfile reference](https://docs.docker.com/reference/builder/)[](.html) - [Dockerfile best practices](https://docs.docker.com/articles/dockerfile_best-practices/)[](.html) diff --git a/doc/Download-CSS-styles-from-an-OPML-list.html b/doc/Download-CSS-styles-from-an-OPML-list.html index a4f68ac6..18cc5d9a 100644 --- a/doc/Download-CSS-styles-from-an-OPML-list.html +++ b/doc/Download-CSS-styles-from-an-OPML-list.html @@ -69,6 +69,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
      • Browsing and Searching
      • Firefox share
      • RSS feeds
        • +
      • REST API
    • How To
        @@ -87,6 +88,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
      • 3rd party libraries
      • Plugin System
      • Release Shaarli
        • +
      • Versioning and Branches
      • Security
      • Static analysis
      • Theming
        • @@ -155,7 +157,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf function copyUserStyleFrom($url, $name, $knownStyles) { $userStyle = $url."inc/user.css"; if(in_array($url, $knownStyles)) { - // TODO add log message + // TODO add log message } else { $statusCode = get_http_response_code($userStyle); if(intval($statusCode)<300) { diff --git a/doc/Download-and-Installation.html b/doc/Download-and-Installation.html index b9cac360..2c5b3be2 100644 --- a/doc/Download-and-Installation.html +++ b/doc/Download-and-Installation.html @@ -69,6 +69,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
      • Browsing and Searching
      • Firefox share
      • RSS feeds
        • +
      • REST API
    • How To
        @@ -87,6 +88,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
      • 3rd party libraries
      • Plugin System
      • Release Shaarli
        • +
      • Versioning and Branches
      • Security
      • Static analysis
      • Theming
        • @@ -108,10 +110,10 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf

        Download as an archive

        Get the latest released version from the releases page.

        Download our shaarli-full archive to include dependencies.

        -

        The current latest released version is v0.8.0

        +

        The current latest released version is v0.8.4

        Or in command lines:

        -
        $ wget https://github.com/shaarli/Shaarli/releases/download/v0.8.0/shaarli-v0.8.0-full.zip
-$ unzip shaarli-v0.8.0-full.zip
+
        $ wget https://github.com/shaarli/Shaarli/releases/download/v0.8.4/shaarli-v0.8.4-full.zip
+$ unzip shaarli-v0.8.4-full.zip
 $ mv Shaarli /path/to/shaarli/
        
 @@ -129,8 +131,8 @@ $ mv Shaarli /path/to/shaarli/
        
 

 
        
 
        Using git
        
 
        mkdir -p /path/to/shaarli && cd /path/to/shaarli/
-git clone -b v0.8.0 https://github.com/shaarli/Shaarli.git .
-composer update --no-dev
        
+git clone -b v0.8 https://github.com/shaarli/Shaarli.git .
+composer install --no-dev

        Stable version

        The stable version has been experienced by Shaarli users, and will receive security updates.

        @@ -148,16 +150,16 @@ $ mv Shaarli-stable /path/to/shaarli/
        $ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/
 # install/update third-party dependencies
 $ cd /path/to/shaarli/
-$ composer update --no-dev
        +$ composer install --no-dev

        Development version (mainline)

        Use at your own risk!

        To get the latest changes from the master branch:

        # clone the repository  
-$ git clone https://github.com/shaarli/Shaarli.git master /path/to/shaarli/
+$ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
 # install/update third-party dependencies
 $ cd /path/to/shaarli
-$ composer update --no-dev
        +$ composer install --no-dev

        Finish Installation

        Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.

        diff --git a/doc/Download-and-Installation.md b/doc/Download-and-Installation.md index 32df8984..970144a5 100644 --- a/doc/Download-and-Installation.md +++ b/doc/Download-and-Installation.md @@ -13,13 +13,13 @@ Get the latest released version from the [releases](https://github.com/shaarli/S **Download our *shaarli-full* archive** to include dependencies. -The current latest released version is `v0.8.0` +The current latest released version is `v0.8.4` Or in command lines: ```bash -$ wget https://github.com/shaarli/Shaarli/releases/download/v0.8.0/shaarli-v0.8.0-full.zip -$ unzip shaarli-v0.8.0-full.zip +$ wget https://github.com/shaarli/Shaarli/releases/download/v0.8.4/shaarli-v0.8.4-full.zip +$ unzip shaarli-v0.8.4-full.zip $ mv Shaarli /path/to/shaarli/ ``` @@ -30,8 +30,8 @@ $ mv Shaarli /path/to/shaarli/ ``` mkdir -p /path/to/shaarli && cd /path/to/shaarli/ -git clone -b v0.8.0 https://github.com/shaarli/Shaarli.git . -composer update --no-dev +git clone -b v0.8 https://github.com/shaarli/Shaarli.git . +composer install --no-dev ``` -------------------------------------------------------- @@ -66,7 +66,7 @@ $ mv Shaarli-stable /path/to/shaarli/ $ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/ # install/update third-party dependencies $ cd /path/to/shaarli/ -$ composer update --no-dev +$ composer install --no-dev ``` -------------------------------------------------------- @@ -79,10 +79,10 @@ To get the latest changes from the `master` branch: ```bash # clone the repository -$ git clone https://github.com/shaarli/Shaarli.git master /path/to/shaarli/ +$ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/ # install/update third-party dependencies $ cd /path/to/shaarli -$ composer update --no-dev +$ composer install --no-dev ``` -------------------------------------------------------- diff --git a/doc/Example-patch---add-new-via-field-for-links.html b/doc/Example-patch---add-new-via-field-for-links.html index 133224e2..49036a74 100644 --- a/doc/Example-patch---add-new-via-field-for-links.html +++ b/doc/Example-patch---add-new-via-field-for-links.html @@ -32,6 +32,7 @@
      • Browsing and Searching
      • Firefox share
      • RSS feeds
        • +
      • REST API
    • How To
    • How To
    • How To
    • How To
    • How To
    • How To

      Plugin System

      -
      -

      Note: Plugin current status - in development (not merged into master).

      -

      I am a developer. Developer API.

      I am a template designer. Guide for template designer.

      Developer API

      @@ -121,12 +120,21 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf | plugins/ |---| demo_plugin/ | |---| demo_plugin.php +

      Plugin initialization

      +

      At the beginning of Shaarli execution, all enabled plugins are loaded. At this point, the plugin system looks for an init() function to execute and run it if it exists. This function must be named this way, and takes the ConfigManager as parameter.

      +
      <plugin_name>_init($conf)
      +

      This function can be used to create initial data, load default settings, etc. But also to set plugin errors. If the initialization function returns an array of strings, they will be understand as errors, and displayed in the header to logged in users.

      Understanding hooks

      A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.

      These functions need to be named with this pattern:

      -
      hook_<plugin_name>_<hook_name>
      +
      hook_<plugin_name>_<hook_name>($data, $conf)
      +

      Parameters:

      +

      For exemple, if my plugin want to add data to the header, this function is needed:

      -
      hook_demo_plugin_render_header()
      +
      hook_demo_plugin_render_header

      If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.

      Plugin's data

      Parameters

      @@ -159,6 +167,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
      • description: plugin description
      • parameters: user parameter names, separated by a ;.
        • +
      • parameter.<PARAMETER_NAME>: add a text description the specified parameter.

      Note: In PHP, parse_ini_file() seems to want strings to be between by quotes " in the ini file.

      @@ -209,16 +218,28 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf render_tagcloud -Allow to add content at the top and bottom of the page. +Allow to add content at the top and bottom of the page, and after all tags. +render_taglist +Allow to add content at the top and bottom of the page, and after all tags. + + render_daily Allow to add content at the top and bottom of the page, the bottom of each link and to alter data. + +render_feed +Allow to do add tags in RSS and ATOM feeds. + -savelink +save_link Allow to alter the link being saved in the datastore. + +delete_link +Allow to do an action before a link is deleted from the datastore. +

      render_header

      @@ -376,17 +397,41 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf

    • plugin_start_zone: before displaying the template content.

    • plugin_end_zone: after displaying the template content.

    +

    For each tag, the following placeholder can be used:

    +
      +
    • tag_plugin: after each tag
      • +

    plugin_start_end_zone_example

    +

    render_taglist

    +

    Triggered when taglist is displayed.

    +

    Allow to add content at the top and bottom of the page.

    +
    Data
    +

    $data is an array containing:

    +
      +
    • _LOGGEDIN_: true if user is logged in, false otherwise.
      • +
    • All templates data.
      • +
    +
    Template placeholders
    +

    Items can be displayed in templates by adding an entry in $data['<placeholder>'] array.

    +

    List of placeholders:

    +
      +

    • plugin_start_zone: before displaying the template content.

      • +

    • plugin_end_zone: after displaying the template content.

      • +
    +

    For each tag, the following placeholder can be used:

    +
      +
    • tag_plugin: after each tag
      • +

    render_daily

    Triggered when tagcloud is displayed.

    Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.

    -
    Data
    +
    Data

    $data is an array containing:

    • _LOGGEDIN_: true if user is logged in, false otherwise.
    • All templates data, including links.
    -
    Template placeholders
    +
    Template placeholders

    Items can be displayed in templates by adding an entry in $data['<placeholder>'] array.

    List of placeholders:

      @@ -397,18 +442,57 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf

    • plugin_start_zone: before displaying the template content.

    • plugin_end_zone: after displaying the template content.

    - +

    render_feed

    +

    Triggered when the ATOM or RSS feed is displayed.

    +

    Allow to add tags in the feed, either in the header or for each items. Items (links) can also be altered before being rendered.

    +
    Data
    +

    $data is an array containing:

    +
      +
    • _LOGGEDIN_: true if user is logged in, false otherwise.
      • +
    • _PAGE_: containing either rss or atom.
      • +
    • All templates data, including links.
      • +
    +
    Template placeholders
    +

    Tags can be added in feeds by adding an entry in $data['<placeholder>'] array.

    +

    List of placeholders:

    +
      +
    • feed_plugins_header: used as a header tag in the feed.
      • +
    +

    For each links:

    +
      +
    • feed_plugins: additional tag for every link entry.
      • +
    +

    Triggered when a link is save (new link or edit).

    Allow to alter the link being saved in the datastore.

    -
    Data
    +
    Data

    $data is an array containing the link being saved:

      +
    • id
    • title
    • url
      • +
    • shorturl
    • description
      • -
    • linkdate
    • private
    • tags
      • +
    • created
      • +
    • updated
      • +
    + +

    Triggered when a link is deleted.

    +

    Allow to execute any action before the link is actually removed from the datastore

    +
    Data
    +

    $data is an array containing the link being saved:

    +
      +
    • id
      • +
    • title
      • +
    • url
      • +
    • shorturl
      • +
    • description
      • +
    • private
      • +
    • tags
      • +
    • created
      • +
    • updated

    Guide for template designer

    Plugin administration

    @@ -537,5 +621,14 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf {$value} {/loop} </div> +

    feed.atom.xml and feed.rss.xml:

    +

    In headers tags section:

    +
    {loop="$feed_plugins_header"}
+  {$value}
+{/loop}
    +

    After each entry:

    +
    {loop="$value.feed_plugins"}
+  {$value}
+{/loop}
    diff --git a/doc/Plugin-System.md b/doc/Plugin-System.md index 623627dd..addd792d 100644 --- a/doc/Plugin-System.md +++ b/doc/Plugin-System.md @@ -1,6 +1,4 @@ #Plugin System -> Note: Plugin current status - in development (not merged into master). - [**I am a developer.** Developer API.](#developer-api)[](.html) [**I am a template designer.** Guide for template designer.](#guide-for-template-designer)[](.html) @@ -30,6 +28,14 @@ You should have the following tree view: | |---| demo_plugin.php ``` +### Plugin initialization + +At the beginning of Shaarli execution, all enabled plugins are loaded. At this point, the plugin system looks for an `init()` function to execute and run it if it exists. This function must be named this way, and takes the `ConfigManager` as parameter. + + _init($conf) + +This function can be used to create initial data, load default settings, etc. But also to set *plugin errors*. If the initialization function returns an array of strings, they will be understand as errors, and displayed in the header to logged in users. + ### Understanding hooks A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution. @@ -37,12 +43,17 @@ A plugin is a set of functions. Each function will be triggered by the plugin sy These functions need to be named with this pattern: ``` -hook__ +hook__($data, $conf) ``` +Parameters: + + - data: see [$data section](https://github.com/shaarli/Shaarli/wiki/Plugin-System#plugins-data)[](.html) + - conf: the `ConfigManager` instance. + For exemple, if my plugin want to add data to the header, this function is needed: - hook_demo_plugin_render_header() + hook_demo_plugin_render_header If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header. @@ -98,6 +109,7 @@ Each file contain two keys: * `description`: plugin description * `parameters`: user parameter names, separated by a `;`. + * `parameter.`: add a text description the specified parameter. > Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file. @@ -118,9 +130,13 @@ If it's still not working, please [open an issue](https://github.com/shaarli/Sha | [render_editlink](#render_editlink) | Allow to add fields in the form, or display elements. |[](.html) | [render_tools](#render_tools) | Allow to add content at the end of the page. |[](.html) | [render_picwall](#render_picwall) | Allow to add content at the top and bottom of the page. |[](.html) -| [render_tagcloud](#render_tagcloud) | Allow to add content at the top and bottom of the page. |[](.html) +| [render_tagcloud](#render_tagcloud) | Allow to add content at the top and bottom of the page, and after all tags. |[](.html) +| [render_taglist](#render_taglist) | Allow to add content at the top and bottom of the page, and after all tags. |[](.html) | [render_daily](#render_daily) | Allow to add content at the top and bottom of the page, the bottom of each link and to alter data. |[](.html) -| [savelink](#savelink) | Allow to alter the link being saved in the datastore. |[](.html) +| [render_feed](#render_feed) | Allow to do add tags in RSS and ATOM feeds. |[](.html) +| [save_link](#save_link) | Allow to alter the link being saved in the datastore. |[](.html) +| [delete_link](#delete_link) | Allow to do an action before a link is deleted from the datastore. |[](.html) + #### render_header @@ -330,8 +346,40 @@ List of placeholders: * `plugin_end_zone`: after displaying the template content. +For each tag, the following placeholder can be used: + + * `tag_plugin`: after each tag + ![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png)[](.html) + +#### render_taglist + +Triggered when taglist is displayed. + +Allow to add content at the top and bottom of the page. + +##### Data + +`$data` is an array containing: + + * `_LOGGEDIN_`: true if user is logged in, false otherwise. + * All templates data. + +##### Template placeholders + +Items can be displayed in templates by adding an entry in `$data['']` array.[](.html) + +List of placeholders: + + * `plugin_start_zone`: before displaying the template content. + + * `plugin_end_zone`: after displaying the template content. + +For each tag, the following placeholder can be used: + + * `tag_plugin`: after each tag + #### render_daily Triggered when tagcloud is displayed. @@ -359,7 +407,33 @@ List of placeholders: * `plugin_end_zone`: after displaying the template content. -#### savelink +#### render_feed + +Triggered when the ATOM or RSS feed is displayed. + +Allow to add tags in the feed, either in the header or for each items. Items (links) can also be altered before being rendered. + +##### Data + +`$data` is an array containing: + + * `_LOGGEDIN_`: true if user is logged in, false otherwise. + * `_PAGE_`: containing either `rss` or `atom`. + * All templates data, including links. + +##### Template placeholders + +Tags can be added in feeds by adding an entry in `$data['']` array.[](.html) + +List of placeholders: + + * `feed_plugins_header`: used as a header tag in the feed. + +For each links: + + * `feed_plugins`: additional tag for every link entry. + +#### save_link Triggered when a link is save (new link or edit). @@ -369,12 +443,36 @@ Allow to alter the link being saved in the datastore. `$data` is an array containing the link being saved: + * id + * title + * url + * shorturl + * description + * private + * tags + * created + * updated + + +#### delete_link + +Triggered when a link is deleted. + +Allow to execute any action before the link is actually removed from the datastore + +##### Data + +`$data` is an array containing the link being saved: + + * id * title * url + * shorturl * description - * linkdate * private * tags + * created + * updated ## Guide for template designer @@ -595,3 +693,19 @@ Bottom: {/loop} ``` + +**feed.atom.xml** and **feed.rss.xml**: + +In headers tags section: +```xml +{loop="$feed_plugins_header"} + {$value} +{/loop} +``` + +After each entry: +```xml +{loop="$value.feed_plugins"} + {$value} +{/loop} +``` diff --git a/doc/Plugins.html b/doc/Plugins.html index 435a836f..08ce8a86 100644 --- a/doc/Plugins.html +++ b/doc/Plugins.html @@ -69,6 +69,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
  • Browsing and Searching
  • Firefox share
  • RSS feeds
    • +
  • REST API
  • How To

    Third party plugins

    diff --git a/doc/Plugins.md b/doc/Plugins.md index 81167fcf..e3192a60 100644 --- a/doc/Plugins.md +++ b/doc/Plugins.md @@ -67,7 +67,6 @@ Usage of each plugin is documented in it's README file: * [`markdown`](https://github.com/shaarli/Shaarli/blob/master/plugins/markdown/README.md): Render shaare description with Markdown syntax.[](.html) * [`playvideos`](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md): Add a button in the toolbar allowing to watch all videos.[](.html) * `qrcode`: For each link, add a QRCode icon. - * `readityourself`: For each link, add a ReadItYourself icon to save the shaared URL * [`wallabag`](https://github.com/shaarli/Shaarli/blob/master/plugins/wallabag/README.md): For each link, add a Wallabag icon to save it in your instance.[](.html) diff --git a/doc/REST-API.html b/doc/REST-API.html new file mode 100644 index 00000000..d14c98c9 --- /dev/null +++ b/doc/REST-API.html @@ -0,0 +1,169 @@ + + + + + + + Shaarli – REST API + + + + + + + +

    REST API

    +

    Usage

    +

    See the REST API documentation.

    +

    Authentication

    +

    All requests to Shaarli's API must include a JWT token to verify their authenticity.

    +

    This token has to be included as an HTTP header called Authentication: Bearer <jwt token>.

    +

    JWT resources :

    + +

    Shaarli JWT Token

    +

    JWT tokens are composed by three parts, separated by a dot . and encoded in base64:

    +
    [header].[payload].[signature][](.html)
    + +

    Shaarli only allow one hash algorithm, so the header will always be the same:

    +
    {
+    "typ": "JWT",
+    "alg": "HS512"
+}
    +

    Encoded in base64, it gives:

    +
    ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==
    +

    Payload

    +

    Validity duration

    +

    To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independant - UTC) under the key iat (issued at). This token will be accepted during 9 minutes.

    +
    {
+    "iat": 1468663519
+}
    +

    See RFC reference.

    +

    Signature

    +

    The signature authenticate the token validity. It contains the base64 of the header and the body, separated by a dot ., hashed in SHA512 with the API secret available in Shaarli administration page.

    +

    Signature example with PHP:

    +
    $content = base64_encode($header) . '.' . base64_encode($payload);
+$signature = hash_hmac('sha512', $content, $secret);
    +

    Complete example

    +

    PHP

    +
    function generateToken($secret) {
+    $header = base64_encode('{
+        "typ": "JWT",
+        "alg": "HS512"
+    }');
+    $payload = base64_encode('{
+        "iat": '. time() .'
+    }');
+    $signature = hash_hmac('sha512', $header .'.'. $payload , $secret);
+    return $header .'.'. $payload .'.'. $signature;
+}
+
+$secret = 'mysecret';
+$token = generateToken($secret);
+echo $token;
    +
    +

    ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==.ewogICAgICAgICJpYXQiOiAxNDY4NjY3MDQ3CiAgICB9.1d2c54fa947daf594fdbf7591796195652c8bc63bffad7f6a6db2a41c313f495a542cbfb595acade79e83f3810d709b4251d7b940bbc10b531a6e6134af63a68

    +
    +
    $options = [[](.html)
+    'http' => [[](.html)
+        'method' => 'GET',
+        'jwt' => $token,
+    ],
+];
+$context = stream_context_create($options);
+file_get_contents($apiEndpoint, false, $context);
    + + diff --git a/doc/REST-API.md b/doc/REST-API.md new file mode 100644 index 00000000..d7909978 --- /dev/null +++ b/doc/REST-API.md @@ -0,0 +1,105 @@ +#REST API +## Usage + +See the [REST API documentation](http://shaarli.github.io/api-documentation/).[](.html) + +## Authentication + +All requests to Shaarli's API must include a JWT token to verify their authenticity. + +This token has to be included as an HTTP header called `Authentication: Bearer `. + +JWT resources : + + * [jwt.io](https://jwt.io) (including a list of client per language).[](.html) + * RFC : https://tools.ietf.org/html/rfc7519 + * https://float-middle.com/json-web-tokens-jwt-vs-sessions/ + * HackerNews thread: https://news.ycombinator.com/item?id=11929267 + + +### Shaarli JWT Token + +JWT tokens are composed by three parts, separated by a dot `.` and encoded in base64: + +``` +[header].[payload].[signature][](.html) +``` + +#### Header + +Shaarli only allow one hash algorithm, so the header will always be the same: + +```json +{ + "typ": "JWT", + "alg": "HS512" +} +``` + +Encoded in base64, it gives: + +``` +ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ== +``` + +#### Payload + +**Validity duration** + +To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independant - UTC) under the key `iat` (issued at). This token will be accepted during 9 minutes. + +```json +{ + "iat": 1468663519 +} +``` + +See [RFC reference](https://tools.ietf.org/html/rfc7519#section-4.1.6).[](.html) + + +#### Signature + +The signature authenticate the token validity. It contains the base64 of the header and the body, separated by a dot `.`, hashed in SHA512 with the API secret available in Shaarli administration page. + +Signature example with PHP: + +```php +$content = base64_encode($header) . '.' . base64_encode($payload); +$signature = hash_hmac('sha512', $content, $secret); +``` + + +### Complete example + +#### PHP + +```php +function generateToken($secret) { + $header = base64_encode('{ + "typ": "JWT", + "alg": "HS512" + }'); + $payload = base64_encode('{ + "iat": '. time() .' + }'); + $signature = hash_hmac('sha512', $header .'.'. $payload , $secret); + return $header .'.'. $payload .'.'. $signature; +} + +$secret = 'mysecret'; +$token = generateToken($secret); +echo $token; +``` + +> `ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==.ewogICAgICAgICJpYXQiOiAxNDY4NjY3MDQ3CiAgICB9.1d2c54fa947daf594fdbf7591796195652c8bc63bffad7f6a6db2a41c313f495a542cbfb595acade79e83f3810d709b4251d7b940bbc10b531a6e6134af63a68` + +```php +$options = [[](.html) + 'http' => [[](.html) + 'method' => 'GET', + 'jwt' => $token, + ], +]; +$context = stream_context_create($options); +file_get_contents($apiEndpoint, false, $context); +``` diff --git a/doc/RSS-feeds.html b/doc/RSS-feeds.html index 0f332b3d..0ebfecc6 100644 --- a/doc/RSS-feeds.html +++ b/doc/RSS-feeds.html @@ -32,6 +32,7 @@
  • Browsing and Searching
  • Firefox share
  • RSS feeds
    • +
  • REST API
  • How To
  • How To
      @@ -87,6 +88,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
    • 3rd party libraries
    • Plugin System
    • Release Shaarli
      • +
    • Versioning and Branches
    • Security
    • Static analysis
    • Theming
      • @@ -192,6 +194,8 @@ $ git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F gpg: Good signature from "VirtualTam <virtualtam@flibidi.net>" [ultimate][](.html)

      Publish the GitHub release

      +

      Update release badges

      +

      Update README.md so version badges display and point to the newly released Shaarli version(s).

      Create a GitHub release from a Git tag

      From the previously drafted release:

        diff --git a/doc/Release-Shaarli.md b/doc/Release-Shaarli.md index 556a96ee..ced58853 100644 --- a/doc/Release-Shaarli.md +++ b/doc/Release-Shaarli.md @@ -103,6 +103,9 @@ gpg: Good signature from "VirtualTam " [ultimate][](.htm ``` ## Publish the GitHub release +### Update release badges +Update `README.md` so version badges display and point to the newly released Shaarli version(s). + ### Create a GitHub release from a Git tag From the previously drafted release: - edit the release notes (if needed) diff --git a/doc/Security.html b/doc/Security.html index cec20590..12b46fa9 100644 --- a/doc/Security.html +++ b/doc/Security.html @@ -69,6 +69,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
      • Browsing and Searching
      • Firefox share
      • RSS feeds
        • +
      • REST API
    • How To
    • How To
        @@ -87,6 +88,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
      • 3rd party libraries
      • Plugin System
      • Release Shaarli
        • +
      • Versioning and Branches
      • Security
      • Static analysis
      • Theming
        • @@ -196,6 +198,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf

        .htaccess

        Shaarli use .htaccess Apache files to deny access to files that shouldn't be directly accessed (datastore, config, etc.). You need the directive AllowOverride All in your virtual host configuration for them to work.

        Warning: If you use Apache 2.2 or lower, you need mod_version to be installed and enabled.

        +

        Apache module mod_rewrite must be enabled to use the REST API. URL rewriting rules for the Slim microframework are stated in the root .htaccess file.

        LightHttpd

        Nginx

        Foreword

        @@ -296,11 +299,14 @@ http { error_log /var/log/nginx/error.log; location /shaarli/ { + try_files $uri /shaarli/index.php$is_args$args; access_log /var/log/nginx/shaarli.access.log; error_log /var/log/nginx/shaarli.error.log; } location ~ (index)\.php$ { + try_files $uri =404; + fastcgi_split_path_info ^(.+\.php)(/.+)$; fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock; fastcgi_index index.php; include fastcgi.conf; @@ -335,6 +341,10 @@ location ~ ~$ { } 
        # /etc/nginx/php.conf
 location ~ (index)\.php$ {
+    # Slim - split URL path into (script_filename, path_info)
+    try_files $uri =404;
+    fastcgi_split_path_info ^(.+\.php)(/.+)$;
+
     # filter and proxy PHP requests to PHP-FPM
     fastcgi_pass   unix:/var/run/php-fpm/php-fpm.sock;
     fastcgi_index  index.php;
@@ -367,6 +377,9 @@ http {
         server_name  my.first.domain.org;
 
         location /shaarli/ {
+            # Slim - rewrite URLs
+            try_files $uri /shaarli/index.php$is_args$args;
+
             access_log  /var/log/nginx/shaarli.access.log;
             error_log   /var/log/nginx/shaarli.error.log;
         }
@@ -425,6 +438,9 @@ http {
         ssl_certificate_key  /home/john/ssl/localhost.key;
 
         location /shaarli/ {
+            # Slim - rewrite URLs
+            try_files $uri /index.php$is_args$args;
+
             access_log  /var/log/nginx/shaarli.access.log;
             error_log   /var/log/nginx/shaarli.error.log;
         }
diff --git a/doc/Server-configuration.md b/doc/Server-configuration.md
index df10feb2..81cc1a72 100644
--- a/doc/Server-configuration.md
+++ b/doc/Server-configuration.md
@@ -107,6 +107,8 @@ See [Server-side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache)
 Shaarli use `.htaccess` Apache files to deny access to files that shouldn't be directly accessed (datastore, config, etc.). You need the directive `AllowOverride All` in your virtual host configuration for them to work.
 
 **Warning**: If you use Apache 2.2 or lower, you need [mod_version](https://httpd.apache.org/docs/current/mod/mod_version.html) to be installed and enabled.[](.html)
+ 
+Apache module `mod_rewrite` **must** be enabled to use the REST API. URL rewriting rules for the Slim microframework are stated in the root `.htaccess` file.
 
 ## LightHttpd
 
@@ -218,11 +220,14 @@ http {
         error_log   /var/log/nginx/error.log;
 
         location /shaarli/ {
+            try_files $uri /shaarli/index.php$is_args$args;
             access_log  /var/log/nginx/shaarli.access.log;
             error_log   /var/log/nginx/shaarli.error.log;
         }
 
         location ~ (index)\.php$ {
+            try_files $uri =404;
+            fastcgi_split_path_info ^(.+\.php)(/.+)$;
             fastcgi_pass   unix:/var/run/php-fpm/php-fpm.sock;
             fastcgi_index  index.php;
             include        fastcgi.conf;
@@ -261,6 +266,10 @@ location ~ ~$ {
 ```nginx
 # /etc/nginx/php.conf
 location ~ (index)\.php$ {
+    # Slim - split URL path into (script_filename, path_info)
+    try_files $uri =404;
+    fastcgi_split_path_info ^(.+\.php)(/.+)$;
+
     # filter and proxy PHP requests to PHP-FPM
     fastcgi_pass   unix:/var/run/php-fpm/php-fpm.sock;
     fastcgi_index  index.php;
@@ -299,6 +308,9 @@ http {
         server_name  my.first.domain.org;
 
         location /shaarli/ {
+            # Slim - rewrite URLs
+            try_files $uri /shaarli/index.php$is_args$args;
+
             access_log  /var/log/nginx/shaarli.access.log;
             error_log   /var/log/nginx/shaarli.error.log;
         }
@@ -361,6 +373,9 @@ http {
         ssl_certificate_key  /home/john/ssl/localhost.key;
 
         location /shaarli/ {
+            # Slim - rewrite URLs
+            try_files $uri /index.php$is_args$args;
+
             access_log  /var/log/nginx/shaarli.access.log;
             error_log   /var/log/nginx/shaarli.error.log;
         }
diff --git a/doc/Server-requirements.html b/doc/Server-requirements.html
index 2c2545bb..79d74118 100644
--- a/doc/Server-requirements.html
+++ b/doc/Server-requirements.html
@@ -32,6 +32,7 @@
 
      • Browsing and Searching
        • 
 
      • Firefox share
        • 
 
      • RSS feeds
        • 
+
      • REST API
        •
    • How To
        @@ -50,6 +51,7 @@
      • 3rd party libraries
      • Plugin System
      • Release Shaarli
        • +
      • Versioning and Branches
      • Security
      • Static analysis
      • Theming
        • @@ -83,26 +85,31 @@ +7.1 +Supported (v0.9.x) +✅ + + 7.0 Supported ✅ - + 5.6 Supported ✅ - + 5.5 EOL: 2016-07-10 ✅ - + 5.4 EOL: 2015-09-14 ✅ (up to Shaarli 0.8.x) - + 5.3 EOL: 2014-08-14 ✅ (up to Shaarli 0.8.x) @@ -130,6 +137,16 @@ download and install third-party PHP dependencies.

        All Import bookmarks from Netscape files + +erusev/parsedown +All +Parse MarkDown syntax for the MarkDown plugin + + +slim/slim +All +Handle routes and middleware for the REST API +

        Extensions

        diff --git a/doc/Server-requirements.md b/doc/Server-requirements.md index 4962193e..07e70ab3 100644 --- a/doc/Server-requirements.md +++ b/doc/Server-requirements.md @@ -10,6 +10,7 @@ ### Supported versions Version | Status | Shaarli compatibility :---:|:---:|:---: +7.1 | Supported (v0.9.x) | :white_check_mark: 7.0 | Supported | :white_check_mark: 5.6 | Supported | :white_check_mark: 5.5 | EOL: 2016-07-10 | :white_check_mark: @@ -26,6 +27,8 @@ download and install third-party PHP dependencies. Library | Required? | Usage ---|:---:|--- [`shaarli/netscape-bookmark-parser`](https://packagist.org/packages/shaarli/netscape-bookmark-parser) | All | Import bookmarks from Netscape files[](.html) +[`erusev/parsedown`](https://packagist.org/packages/erusev/parsedown) | All | Parse MarkDown syntax for the MarkDown plugin[](.html) +[`slim/slim`](https://packagist.org/packages/slim/slim) | All | Handle routes and middleware for the REST API[](.html) ### Extensions Extension | Required? | Usage diff --git a/doc/Server-security.html b/doc/Server-security.html index 3551deff..4f7ff468 100644 --- a/doc/Server-security.html +++ b/doc/Server-security.html @@ -69,6 +69,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
      • Browsing and Searching
      • Firefox share
      • RSS feeds
        • +
      • REST API
    • How To
    • How To
        @@ -87,6 +88,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
      • 3rd party libraries
      • Plugin System
      • Release Shaarli
        • +
      • Versioning and Branches
      • Security
      • Static analysis
      • Theming
        • @@ -169,6 +171,7 @@ It might be useful if your IP adress often changes.

        Resources

        data_dir: Data directory.
        datastore: Shaarli's links database file path.
        +history: Shaarli's operation history file path.
        updates: File path for the ran updates file.
        log: Log file path.
        update_check: Last update check file path.
        diff --git a/doc/Shaarli-configuration.md b/doc/Shaarli-configuration.md index 4a783c0e..25647cb7 100644 --- a/doc/Shaarli-configuration.md +++ b/doc/Shaarli-configuration.md @@ -70,6 +70,7 @@ It might be useful if your IP adress often changes. **data_dir**: Data directory. **datastore**: Shaarli's links database file path. +**history**: Shaarli's operation history file path. **updates**: File path for the ran updates file. **log**: Log file path. **update_check**: Last update check file path. diff --git a/doc/Sharing-button.html b/doc/Sharing-button.html index 93710efe..f3682f8c 100644 --- a/doc/Sharing-button.html +++ b/doc/Sharing-button.html @@ -32,6 +32,7 @@

      • Browsing and Searching
      • Firefox share
      • RSS feeds
        • +
      • REST API
    • How To
    • How To
    • How To

      Theming

      -

      User CSS

      +

      Foreword

      +

      There are two ways of customizing how Shaarli looks:

      +
        +
      1. by using a custom CSS to override Shaarli's CSS
        2. +
      2. by using a full theme that provides its own RainTPL templates, CSS and Javascript resources
        3. +
      +

      Custom CSS

      +

      Shaarli's appearance can be modified by adding CSS rules to:

        -
      • Shaarli's apparence can be modified by editing CSS rules in inc/user.css. This file allows to override rules defined in the main inc/shaarli.css (only add changed rules), or define a whole new theme.
        • -
      • Do not edit inc/shaarli.css! Your changes would be overriden when updating Shaarli.
        • -
      • Some themes are available at https://github.com/shaarli/shaarli-themes.
        • +
      • Shaarli < v0.9.0: inc/user.css
        • +
      • Shaarli >= v0.9.0: data/user.css
      -

      See also:

      - -

      RainTPL template

      +

      This file allows overriding rules defined in the template CSS files (only add changed rules), or define a whole new theme.

      +

      Note: Do not edit tpl/default/css/shaarli.css! Your changes would be overridden when updating Shaarli.

      +

      See also Download CSS styles from an OPML list

      +

      Themes

      WARNING - This feature is currently being worked on and will be improved in the next releases. Experimental.

      +

      Installation:

        -
      • Find the template you'd like to install (see the list of available templates|Theming#community-themes--templates)
        • -
      • Find it's git clone URL or download the zip archive for the template.
        • -
      • In your Shaarli tpl/ directory, run git clone https://url/of/my-template/ or unpack the zip archive. +
      • find a theme you'd like to install
        • +
      • copy or clone the theme folder under tpl/<a_sweet_theme>
        • +
      • enable the theme:
          -
        • There should now be a my-template/ directory under the tpl/ dir, containing directly all the template files.
          • +
        • Shaarli < v0.9.0: edit data/config.json.php and set the value of raintpl_tpl to the new theme name:
          +"raintpl_tpl": "tpl\/my-template\/"
          • +
        • Shaarli >= v0.9.0: select the theme through the Tools page
        • -

      • Edit data/config.json.php to have Shaarli use this template, in "resource" e.g.

        -
        "raintpl_tpl": "tpl\/my-template\/",
      -

      Community themes & templates

      +

      Community CSS & themes

      +

      Custom CSS

      + +

      Themes

      +

      Shaarli forks

      + -

      Example installation: AlbinoMouse template

      +

      Example installation: AlbinoMouse theme

      With the following configuration:

      • Apache 2 / PHP 5.6
        • diff --git a/doc/Theming.md b/doc/Theming.md index a21899c2..23877e5d 100644 --- a/doc/Theming.md +++ b/doc/Theming.md @@ -1,39 +1,51 @@ #Theming -## User CSS +## Foreword +There are two ways of customizing how Shaarli looks: -- Shaarli's apparence can be modified by editing CSS rules in `inc/user.css`. This file allows to override rules defined in the main `inc/shaarli.css` (only add changed rules), or define a whole new theme. -- Do not edit `inc/shaarli.css`! Your changes would be overriden when updating Shaarli. -- Some themes are available at https://github.com/shaarli/shaarli-themes. +1. by using a custom CSS to override Shaarli's CSS +2. by using a full theme that provides its own RainTPL templates, CSS and Javascript resources -See also: -- [Download CSS styles from an OPML list](Download-CSS-styles-from-an-OPML-list.html) +## Custom CSS +Shaarli's appearance can be modified by adding CSS rules to: +- Shaarli < `v0.9.0`: `inc/user.css` +- Shaarli >= `v0.9.0`: `data/user.css` -## RainTPL template +This file allows overriding rules defined in the template CSS files (only add changed rules), or define a whole new theme. +**Note**: Do not edit `tpl/default/css/shaarli.css`! Your changes would be overridden when updating Shaarli. + +See also [Download CSS styles from an OPML list](Download-CSS-styles-from-an-OPML-list.html) + +## Themes _WARNING - This feature is currently being worked on and will be improved in the next releases. Experimental._ -- Find the template you'd like to install (see the list of [available templates|Theming#community-themes--templates](available-templates|Theming#community-themes--templates.html)) -- Find it's git clone URL or download the zip archive for the template. -- In your Shaarli `tpl/` directory, run `git clone https://url/of/my-template/` or unpack the zip archive. - - There should now be a `my-template/` directory under the `tpl/` dir, containing directly all the template files. -- Edit `data/config.json.php` to have Shaarli use this template, in `"resource"` e.g. -```json -"raintpl_tpl": "tpl\/my-template\/", -``` +Installation: +- find a theme you'd like to install +- copy or clone the theme folder under `tpl/` +- enable the theme: + - Shaarli < `v0.9.0`: edit `data/config.json.php` and set the value of `raintpl_tpl` to the new theme name: + `"raintpl_tpl": "tpl\/my-template\/"` + - Shaarli >= `v0.9.0`: select the theme through the _Tools_ page -## Community themes & templates +## Community CSS & themes +### Custom CSS +- [mrjovanovic/serious-theme-shaarli](https://github.com/mrjovanovic/serious-theme-shaarli) - A serious theme for Shaarli[](.html) +- [shaarli/shaarli-themes](https://github.com/shaarli/shaarli-themes)[](.html) + +### Themes - [AkibaTech/Shaarli Superhero Theme](https://github.com/AkibaTech/Shaarli---SuperHero-Theme) - A template/theme for Shaarli[](.html) - [alexisju/albinomouse-template](https://github.com/alexisju/albinomouse-template) - A full template for Shaarli[](.html) -- [ArthurHoaro/shaarli-launch](https://github.com/ArthurHoaro/shaarli-launch) - Customizable Shaarli theme.[](.html) +- [ArthurHoaro/shaarli-launch](https://github.com/ArthurHoaro/shaarli-launch) - Customizable Shaarli theme[](.html) - [dhoko/ShaarliTemplate](https://github.com/dhoko/ShaarliTemplate) - A template/theme for Shaarli[](.html) - [kalvn/shaarli-blocks](https://github.com/kalvn/shaarli-blocks) - A template/theme for Shaarli[](.html) -- [kalvn/Shaarli-Material](https://github.com/kalvn/Shaarli-Material) - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone.[](.html) -- [ManufacturaInd/shaarli-2004licious-theme](https://github.com/ManufacturaInd/shaarli-2004licious-theme) - A template/theme as a humble homage to the early looks of the del.icio.us site.[](.html) +- [kalvn/Shaarli-Material](https://github.com/kalvn/Shaarli-Material) - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone[](.html) +- [ManufacturaInd/shaarli-2004licious-theme](https://github.com/ManufacturaInd/shaarli-2004licious-theme) - A template/theme as a humble homage to the early looks of the del.icio.us site[](.html) + +### Shaarli forks - [misterair/Limonade](https://github.com/misterair/limonade) - A fork of (legacy) Shaarli with a new template[](.html) -- [mrjovanovic/serious-theme-shaarli](https://github.com/mrjovanovic/serious-theme-shaarli) - A serious theme for SHaarli.[](.html) - [vivienhaese/shaarlitheme](https://github.com/vivienhaese/shaarlitheme) - A Shaarli fork meant to be run in an openshift instance[](.html) -### Example installation: AlbinoMouse template +## Example installation: AlbinoMouse theme With the following configuration: - Apache 2 / PHP 5.6 - user sites are enabled, e.g. `/home/user/public_html/somedir` is served as `http://localhost/~user/somedir` diff --git a/doc/Troubleshooting.html b/doc/Troubleshooting.html index ed1c6f09..f43e6ed3 100644 --- a/doc/Troubleshooting.html +++ b/doc/Troubleshooting.html @@ -69,6 +69,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
      • Browsing and Searching
      • Firefox share
      • RSS feeds
        • +
      • REST API
    • How To
        @@ -87,6 +88,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
      • 3rd party libraries
      • Plugin System
      • Release Shaarli
        • +
      • Versioning and Branches
      • Security
      • Static analysis
      • Theming
        • @@ -172,7 +174,7 @@ Search for failed in this file to look for unauthorized login attem
      • If you have the error Warning: file_get_contents() [function.file-get-contents]: URL file-access is disabled in the server configuration in /…/index.php on line xxx, it means that your host has disabled the ability to fetch a file by HTTP in the php config (Typically in 1and1 hosting). Bad host. Change host. Or comment the following lines:
      //list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
-// FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) <head> in html 
+// FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) <head> in html 
 //if (strpos($status,'200 OK')) $title=html_extract_title($data);
      • On hosts which forbid outgoing HTTP requests (such as free.fr), some thumbnails will not work.
        • diff --git a/doc/Unit-tests.html b/doc/Unit-tests.html index 266fd33a..09611463 100644 --- a/doc/Unit-tests.html +++ b/doc/Unit-tests.html @@ -69,6 +69,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
      • Browsing and Searching
      • Firefox share
      • RSS feeds
        • +
      • REST API
    • How To +

      Executing specific tests

      +

      Add a @group annotation in a test class or method comment:

      +
      /**
+ * Netscape bookmark import
+ * @group WIP
+ */
+class BookmarkImportTest extends PHPUnit_Framework_TestCase
+{
+   [...][](.html)
+}
      +

      To run all tests annotated with @group WIP:

      +
      $ vendor/bin/phpunit --group WIP tests/
      diff --git a/doc/Unit-tests.md b/doc/Unit-tests.md index f2888780..0942ad38 100644 --- a/doc/Unit-tests.md +++ b/doc/Unit-tests.md @@ -126,3 +126,22 @@ If Xdebug has been installed and activated, two coverage reports will be generat * a summary in the console * a detailed HTML report with metrics for tested code * to open it in a web browser: `firefox coverage/index.html &` + +### Executing specific tests +Add a [`@group`](https://phpunit.de/manual/current/en/appendixes.annotations.html#appendixes.annotations.group) annotation in a test class or method comment:[](.html) + +```php +/** + * Netscape bookmark import + * @group WIP + */ +class BookmarkImportTest extends PHPUnit_Framework_TestCase +{ + [...][](.html) +} +``` + +To run all tests annotated with `@group WIP`: +```bash +$ vendor/bin/phpunit --group WIP tests/ +``` diff --git a/doc/Upgrade-and-migration.html b/doc/Upgrade-and-migration.html index a5b041d5..667215ab 100644 --- a/doc/Upgrade-and-migration.html +++ b/doc/Upgrade-and-migration.html @@ -69,6 +69,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
    • Browsing and Searching
    • Firefox share
    • RSS feeds
      • +
    • REST API
  • How To
      @@ -87,6 +88,7 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
    • 3rd party libraries
    • Plugin System
    • Release Shaarli
      • +
    • Versioning and Branches
    • Security
    • Static analysis
    • Theming
      • @@ -101,12 +103,16 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf

      Upgrade and migration

      Preparation

      +

      Note your current version

      +

      If anything goes wrong, it's important for us to know which version you're upgrading from.
      +The current version is present in the version.php file.

      Backup your data

      Shaarli stores all user data under the data directory:

      • data/config.php - main configuration file
      • data/datastore.php - bookmarked links
      • data/ipbans.php - banned IP addresses
        • +
      • data/updates.txt - contains all automatic update to the configuration and datastore files already run

      See Shaarli configuration for more information about Shaarli resources.

      It is recommended to backup this repository before starting updating/upgrading Shaarli:

      @@ -125,15 +131,11 @@ code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Inf
  • check or restore the data directory
    • -

    Upgrading from release archives

    +

    All tagged revisions can be downloaded as tarballs or ZIP archives from the releases page.

    -

    We recommend using the releases from the stable branch, which are available as:

    - -

    Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the contents of the data directory!

    -

    After upgrading, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to data/config.php (see Shaarli configuration for more details).

    +

    We recommend that you use the latest release tarball with the -full suffix. It contains the dependencies, please read Download and installation for git complete instructions.

    +

    Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the data directory!

    +

    After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to data/config.json.php (see Shaarli configuration for more details).

    Upgrading with Git

    Updating a community Shaarli

    If you have installed Shaarli from the community Git repository, simply pull new changes from your local clone:

    @@ -149,7 +151,7 @@ $ git pull tests/Url/UrlTest.php | 1 + 3 files changed, 3 insertions(+), 1 deletion(-)

    Shaarli >= v0.8.x: install/update third-party PHP dependencies using Composer:

    -
    $ composer update --no-dev
+
    $ composer install --no-dev
 
 Loading composer repositories with package information
 Updating dependencies
@@ -214,7 +216,7 @@ $ git branch -vv
   master 029f75f [sebsauvage/master] Update README.md[](.html)
 * stable 890afc3 [origin/stable] Merge pull request #509 from ArthurHoaro/v0.6.5[](.html)
    
 
    Shaarli >= v0.8.x: install/update third-party PHP dependencies using Composer:
    
-
    $ composer update --no-dev
+
    $ composer install --no-dev
 
 Loading composer repositories with package information
 Updating dependencies
@@ -238,5 +240,20 @@ $ git gc
 Total 3317 (delta 2050), reused 3301 (delta 2034)to
    
 
    Step 3: configuration
    
 
    After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to data/config.php (see Shaarli configuration for more details).
    
+
    Troubleshooting
    
+
    If the solutions provided here doesn't work, please open an issue specifying which version you're upgrading from and to.
    
+
    You must specify an integer as a key
    
+
    In v0.8.1 we changed how link keys are handled (from timestamps to incremental integers).
    
+Take a look at data/updates.txt content.
    
+
    updates.txt contains updateMethodDatastoreIds
    
+
    Try to delete it and refresh your page while being logged in.
    
+
    updates.txt doesn't exists or doesn't contain updateMethodDatastoreIds
    
+
      
+
    1. Create data/updates.txt if it doesn't exist.
      2. 
+
    2. Paste this string in the update file ;updateMethodRenameDashTags;
      3. 
+
    3. Login to Shaarli.
      4. 
+
    4. Delete the update file.
      5. 
+
    5. Refresh.
      6. 
+
    
 
 
diff --git a/doc/Upgrade-and-migration.md b/doc/Upgrade-and-migration.md
index 0bc33824..d36eb862 100644
--- a/doc/Upgrade-and-migration.md
+++ b/doc/Upgrade-and-migration.md
@@ -1,11 +1,17 @@
 #Upgrade and migration
 ## Preparation
+### Note your current version
+
+If anything goes wrong, it's important for us to know which version you're upgrading from.  
+The current version is present in the `version.php` file.
+
 ### Backup your data
 
 Shaarli stores all user data under the `data` directory:
 - `data/config.php` - main configuration file
 - `data/datastore.php` - bookmarked links
 - `data/ipbans.php` - banned IP addresses
+- `data/updates.txt` - contains all automatic update to the configuration and datastore files already run
 
 See [Shaarli configuration](Shaarli-configuration.html) for more information about Shaarli resources.
 
@@ -22,16 +28,14 @@ As all user data is kept under `data`, this is the only directory you need to wo
     - update - see the following sections
 - check or restore the `data` directory
 
-## Upgrading from release archives
+## Recommended : Upgrading from release archives
 All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page.[](.html)
 
-We _recommend_ using the releases from the `stable` branch, which are available as:
-- gzipped tarball - https://github.com/shaarli/Shaarli/archive/stable.tar.gz
-- ZIP archive - https://github.com/shaarli/Shaarli/archive/stable.zip
+We recommend that you use the latest release tarball with the `-full` suffix. It contains the dependencies, please read [Download and installation](Download-and-installation.html) for `git` complete instructions.
 
-Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the contents of the `data` directory!
+Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory!
 
-After upgrading, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to `data/config.php` (see [Shaarli configuration](Shaarli-configuration.html) for more details).
+After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to `data/config.json.php` (see [Shaarli configuration](Shaarli-configuration.html) for more details).
 
 ## Upgrading with Git
 ### Updating a community Shaarli
@@ -54,7 +58,7 @@ Fast-forward
 Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):[](.html)
 
 ```bash
-$ composer update --no-dev
+$ composer install --no-dev
 
 Loading composer repositories with package information
 Updating dependencies
@@ -129,7 +133,7 @@ $ git branch -vv
 Shaarli >= `v0.8.x`: install/update third-party PHP dependencies using [Composer](https://getcomposer.org/):[](.html)
 
 ```bash
-$ composer update --no-dev
+$ composer install --no-dev
 
 Loading composer repositories with package information
 Updating dependencies
@@ -159,3 +163,24 @@ Total 3317 (delta 2050), reused 3301 (delta 2034)to
 
 #### Step 3: configuration
 After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to `data/config.php` (see [Shaarli configuration](Shaarli-configuration.html) for more details).
+
+## Troubleshooting
+
+If the solutions provided here doesn't work, please open an issue specifying which version you're upgrading from and to.
+
+### You must specify an integer as a key
+
+In `v0.8.1` we changed how link keys are handled (from timestamps to incremental integers).
+Take a look at `data/updates.txt` content.
+
+#### `updates.txt` contains `updateMethodDatastoreIds`
+
+Try to delete it and refresh your page while being logged in.
+
+#### `updates.txt` doesn't exists or doesn't contain `updateMethodDatastoreIds`
+
+  1. Create `data/updates.txt` if it doesn't exist.
+  2. Paste this string in the update file `;updateMethodRenameDashTags;`
+  3. Login to Shaarli.
+  4. Delete the update file.
+  5. Refresh.
diff --git a/doc/Usage.html b/doc/Usage.html
index 63f21d93..b5855881 100644
--- a/doc/Usage.html
+++ b/doc/Usage.html
@@ -32,6 +32,7 @@
 
  • Browsing and Searching
    • 
 
  • Firefox share
    • 
 
  • RSS feeds
    • 
+
  • REST API
    • 
 
 
  • How To
 
      
@@ -50,6 +51,7 @@
 
    • 3rd party libraries
      • 
 
    • Plugin System
      • 
 
    • Release Shaarli
      • 
+
    • Versioning and Branches
      • 
 
    • Security
      • 
 
    • Static analysis
      • 
 
    • Theming
      • 
diff --git a/doc/Versioning-and-Branches.html b/doc/Versioning-and-Branches.html
new file mode 100644
index 00000000..4dfe4a91
--- /dev/null
+++ b/doc/Versioning-and-Branches.html
@@ -0,0 +1,156 @@
+
+
+
+  
+  
+  
+  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:
      
+
        
+
      • This branch shouldn't be used for production as it isn't necessary stable.
        • 
+
      • 3rd party aren't required to be compatible with the latest changes.
        • 
+
      • Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.
        • 
+
      • The version in this branch is always dev.
        • 
+
      
+
      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:
      
+
        
+
      • Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.
        • 
+
      
+
      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:
      
+
        
+
      • 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.
        • 
+
      • use your own versioning scheme, and state Shaarli compatibility in the release description.
        • 
+
      
+
      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`
      
+
+
diff --git a/doc/Versioning-and-Branches.md b/doc/Versioning-and-Branches.md
new file mode 100644
index 00000000..bbc7719e
--- /dev/null
+++ b/doc/Versioning-and-Branches.md
@@ -0,0 +1,76 @@
+#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:
+
+  * This branch shouldn't be used for production as it isn't necessary stable.
+  * 3rd party aren't required to be compatible with the latest changes.
+  * Official plugins, themes and libraries (contained within Shaarli organization repos) must be compatible with the master branch.
+  * The version in this branch is always `dev`.
+
+## `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:
+
+  * Shaarli release pace isn't fast, and the stable branch might be a few months behind the latest release.
+
+## 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](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)
+
+   - 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.
+   - use your own versioning scheme, and state Shaarli compatibility in the release description.
+
+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:
+
+```bash
+# 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 
+git push origin katastrophe
+# Then you just have to make a new release from the `katastrophe` branch tagged `v0.8.3-1`
+```
diff --git a/doc/_Footer.html b/doc/_Footer.html
index e8a62d2a..09473a38 100644
--- a/doc/_Footer.html
+++ b/doc/_Footer.html
@@ -32,6 +32,7 @@
 
    • Browsing and Searching
      • 
 
    • Firefox share
      • 
 
    • RSS feeds
      • 
+
    • REST API
      • 
 
    • 
 
  • How To
 
    • 
 
  • How To
 
    • 
 
  • How To
 
      
@@ -100,6 +103,7 @@
 
    • 3rd party libraries
      • 
 
    • Plugin System
      • 
 
    • Release Shaarli
      • 
+
    • Versioning and Branches
      • 
 
    • Security
      • 
 
    • Static analysis
      • 
 
    • Theming
      • 
diff --git a/doc/_Sidebar.md b/doc/_Sidebar.md
index 1778e3a3..8df2e565 100644
--- a/doc/_Sidebar.md
+++ b/doc/_Sidebar.md
@@ -14,6 +14,7 @@
     - [Browsing and Searching](Browsing-and-Searching.html)
     - [Firefox share](Firefox-share.html)
     - [RSS feeds](RSS-feeds.html)
+    - [REST API](REST-API.html)
 - How To
     - [Backup, restore, import and export](Backup,-restore,-import-and-export.html)
     - [Copy an existing installation over SSH and serve it locally](Copy-an-existing-installation-over-SSH-and-serve-it-locally.html)
@@ -28,6 +29,7 @@
     - [3rd party libraries](3rd-party-libraries.html)
     - [Plugin System](Plugin-System.html)
     - [Release Shaarli](Release-Shaarli.html)
+    - [Versioning and Branches](Versioning-and-Branches.html)
     - [Security](Security.html)
     - [Static analysis](Static-analysis.html)
     - [Theming](Theming.html)
diff --git a/doc/sidebar.html b/doc/sidebar.html
index 4dad0161..478840d1 100644
--- a/doc/sidebar.html
+++ b/doc/sidebar.html
@@ -18,6 +18,7 @@
 
    • Browsing and Searching
      • 
 
    • Firefox share
      • 
 
    • RSS feeds
      • 
+
    • REST API
      • 
 
    • 
 
  • How To