aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/md/dev
diff options
context:
space:
mode:
Diffstat (limited to 'doc/md/dev')
-rw-r--r--doc/md/dev/Development.md179
-rw-r--r--doc/md/dev/GnuPG-signature.md70
-rw-r--r--doc/md/dev/Plugin-system.md772
-rw-r--r--doc/md/dev/Release-Shaarli.md145
-rw-r--r--doc/md/dev/Theming.md86
-rw-r--r--doc/md/dev/Translations.md157
-rw-r--r--doc/md/dev/Unit-tests.md133
-rw-r--r--doc/md/dev/Versioning.md63
-rw-r--r--doc/md/dev/images/poedit-1.jpgbin0 -> 72956 bytes
9 files changed, 1605 insertions, 0 deletions
diff --git a/doc/md/dev/Development.md b/doc/md/dev/Development.md
new file mode 100644
index 00000000..5c085e03
--- /dev/null
+++ b/doc/md/dev/Development.md
@@ -0,0 +1,179 @@
1# Development
2
3Please read [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md)
4
5## Guidelines
6
7
8- [Unit tests](Unit-tests)
9- Javascript linting - Shaarli uses [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript).
10Run `make eslint` to check JS style.
11- [GnuPG signature](GnuPG-signature) for tags/releases
12
13
14## Third-party libraries
15
16CSS:
17
18- Yahoo UI [CSS Reset](http://yuilibrary.com/yui/docs/cssreset/) - standardize cross-browser rendering
19
20Javascript:
21
22- [Awesomeplete](https://leaverou.github.io/awesomplete/) ([GitHub](https://github.com/LeaVerou/awesomplete)) - autocompletion in input forms
23- [bLazy](http://dinbror.dk/blazy/) ([GitHub](https://github.com/dinbror/blazy)) - lazy loading for thumbnails
24- [qr.js](http://neocotic.com/qr.js/) ([GitHub](https://github.com/neocotic/qr.js)) - QR code generation
25
26PHP (managed through [`composer.json`](https://github.com/shaarli/Shaarli/blob/master/composer.json)):
27
28- [RainTPL](https://github.com/rainphp/raintpl) - HTML templating for PHP
29- [`shaarli/netscape-bookmark-parser`](https://packagist.org/packages/shaarli/netscape-bookmark-parser) - Import bookmarks from Netscape files
30- [`erusev/parsedown`](https://packagist.org/packages/erusev/parsedown) - Parse MarkDown syntax for the MarkDown plugin
31- [`slim/slim`](https://packagist.org/packages/slim/slim) - Handle routes and middleware for the REST API
32- [`ArthurHoaro/web-thumbnailer`](https://github.com/ArthurHoaro/web-thumbnailer) - PHP library which will retrieve a thumbnail for any given URL
33- [`pubsubhubbub/publisher`](https://github.com/pubsubhubbub/php-publisher) - A PubSubHubbub publisher module for PHP.
34- [`gettext/gettext`](https://github.com/php-gettext/Gettext) - PHP library to collect and manipulate gettext (.po, .mo, .php, .json, etc)
35
36
37## Security
38
39- The password is salted, hashed and stored in the data subdirectory, in a PHP file, and protected by htaccess. Even if the webserver does not support htaccess, the hash is not readable by URL. Even if the .php file is stolen, the password cannot deduced from the hash. The salt prevents rainbow-tables attacks.
40- Directories are protected using `.htaccess` files
41- Forms are protected against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery):
42 - Forms which act on data (save,delete…) contain a token generated by the server.
43 - Any posted form which does not contain a valid token is rejected.
44 - Any token can only be used once.
45 - Tokens are attached to the session and cannot be reused in another session.
46- Sessions automatically expire after 60 minutes.
47- Sessions are protected against hijacking: the session ID cannot be used from a different IP address.
48- Links are stored as an associative array which is serialized, compressed (with deflate), base64-encoded and saved as a comment in a `.php` file - even if the server does not support `.htaccess` files, the data file will still not be readable by URL.
49- Bruteforce protection: Successful and failed login attempts are logged - IP bans are enforced after a configurable amount of failures. Logs can also be used consumed by [fail2ban](../Server-configuration.md#fail2ban)
50- A pop-up notification is shown when a new release is available.
51
52## Link structure
53
54Every link available through the `LinkDB` object is represented as an array
55containing the following fields:
56
57 * `id` (integer): Unique identifier.
58 * `title` (string): Title of the link.
59 * `url` (string): URL of the link. Used for displayable links (without redirector, url encoding, etc.).
60 Can be absolute or relative for Notes.
61 * `real_url` (string): Real destination URL, can be redirected, encoded, etc.
62 * `shorturl` (string): Permalink small hash.
63 * `description` (string): Link text description.
64 * `private` (boolean): whether the link is private or not.
65 * `tags` (string): all link tags separated by a single space
66 * `thumbnail` (string|boolean): relative path of the thumbnail cache file, or false if there isn't any.
67 * `created` (DateTime): link creation date time.
68 * `updated` (DateTime): last modification date time.
69
70Small hashes are used to make a link to an entry in Shaarli. They are unique: the date of the item (eg. `20110923_150523`) is hashed with CRC32, then converted to base64 and some characters are replaced. They are always 6 characters longs and use only `A-Z a-z 0-9 - _` and `@`.
71
72
73## Directory structure
74
75Here is the directory structure of Shaarli and the purpose of the different files:
76
77```bash
78 index.php # Main program
79 application/ # Shaarli classes
80 ├── LinkDB.php
81
82 ...
83
84 └── Utils.php
85 tests/ # Shaarli unitary & functional tests
86 ├── LinkDBTest.php
87
88 ...
89
90 ├── utils # utilities to ease testing
91 │ └── ReferenceLinkDB.php
92 └── UtilsTest.php
93 assets/
94 ├── common/ # Assets shared by multiple themes
95 ├── ...
96 ├── default/ # Assets for the default template, before compilation
97 ├── fonts/ # Font files
98 ├── img/ # Images used by the default theme
99 ├── js/ # JavaScript files in ES6 syntax
100 ├── scss/ # SASS files
101 └── vintage/ # Assets for the vintage template, before compilation
102 └── ...
103 COPYING # Shaarli license
104 inc/ # static assets and 3rd party libraries
105 └── rain.tpl.class.php # RainTPL templating library
106 images/ # Images and icons used in Shaarli
107 data/ # data storage: bookmark database, configuration, logs, banlist...
108 ├── config.json.php # Shaarli configuration (login, password, timezone, title...)
109 ├── datastore.php # Your link database (compressed).
110 ├── ipban.php # IP address ban system data
111 ├── lastupdatecheck.txt # Update check timestamp file
112 └── log.txt # login/IPban log.
113 tpl/ # RainTPL templates for Shaarli. They are used to build the pages.
114 ├── default/ # Default Shaarli theme
115 ├── fonts/ # Font files
116 ├── img/ # Images
117 ├── js/ # JavaScript files compiled by Babel and compatible with all browsers
118 ├── css/ # CSS files compiled with SASS
119 └── vintage/ # Legacy Shaarli theme
120 └── ...
121 cache/ # thumbnails cache
122 # This directory is automatically created. You can erase it anytime you want.
123 tmp/ # Temporary directory for compiled RainTPL templates.
124 # This directory is automatically created. You can erase it anytime you want.
125 vendor/ # Third-party dependencies. This directory is created by Composer
126```
127
128Shaarli needs read access to:
129
130- the root index.php file
131- the `application/`, `plugins/` and `inc/` directories (recursively)
132
133Shaarli needs read/write access to the `cache/`, `data/`, `pagecache/`, and `tmp/` directories
134
135
136## Automation
137
138A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations:
139
140- [Static analysis](#Static-analysis) - check that the code is compliant to PHP conventions
141- [Unit tests](#Unit-tests) - ensure there are no regressions introduced by new commits
142- Documentation - generate a local HTML copy of the markdown documentation
143
144### Continuous Integration
145
146[Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build:
147
148- each time a commit is merged to the mainline (`master` branch)
149- each time a Pull Request is submitted or updated
150
151After all jobs have finished, Travis returns the results to GitHub:
152
153- a status icon represents the result for the `master` branch: [![](https://api.travis-ci.org/shaarli/Shaarli.svg)](https://travis-ci.org/shaarli/Shaarli)
154- Pull Requests are updated with the Travis build result.
155
156See [`.travis.yml`](https://github.com/shaarli/Shaarli/blob/master/.travis.yml).
157
158
159### Documentation
160
161[mkdocs](https://www.mkdocs.org/) is used to convert markdown documentation to HTML pages. The [public documentation](https://shaarli.readthedocs.io/en/master/) website is rendered and hosted by [readthedocs.org](https://readthedocs.org/). A copy of the documentation is also included in prebuilt [release archives](https://github.com/shaarli/Shaarli/releases) (`doc/html/` path in your Shaarli installation). To generate the HTML documentation locally, install a recent version of Python `setuptools` and run `make doc`.
162
163
164## Static analysis
165
166Patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially:
167
168- [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard
169- [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide
170
171
172**Work in progress:** Static analysis is currently being discussed here: in [#95 - Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95), [#130 - Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130)
173
174Static analysis tools can be installed with Composer, and used through Shaarli's [Makefile](https://github.com/shaarli/Shaarli/blob/master/Makefile).
175
176For an overview of the available features, see:
177
178- [Code quality: Makefile to run static code checkers](https://github.com/shaarli/Shaarli/pull/124) (#124)
179- [Run PHPCS against different coding standards](https://github.com/shaarli/Shaarli/pull/276) (#276)
diff --git a/doc/md/dev/GnuPG-signature.md b/doc/md/dev/GnuPG-signature.md
new file mode 100644
index 00000000..25578001
--- /dev/null
+++ b/doc/md/dev/GnuPG-signature.md
@@ -0,0 +1,70 @@
1## Introduction
2### PGP and GPG
3[Gnu Privacy Guard](https://gnupg.org/) (GnuPG) is an Open Source implementation of the [Pretty Good Privacy](https://en.wikipedia.org/wiki/Pretty_Good_Privacy#OpenPGP) (OpenPGP) specification. Its main purposes are digital authentication, signature and encryption. It is often used by the [FLOSS](https://en.wikipedia.org/wiki/Free_and_open-source_software) community to verify:
4
5- Linux package signatures: Debian [SecureApt](https://wiki.debian.org/SecureApt), ArchLinux [Master Keys](https://www.archlinux.org/master-keys/)
6- [Version control](https://en.wikipedia.org/wiki/Revision_control) releases & maintainer identity
7
8> You MUST understand that presence of data in the keyserver (pools) in no way connotes trust. Anyone can generate a key, with any name or email address, and upload it. All security and trust comes from evaluating security at the “object level”, via PGP [Web of trust](https://en.wikipedia.org/wiki/Web_of_trust) signatures. This keyserver makes it possible to retrieve keys, looking them up via various indices, but the collection of keys in this public pool is KNOWN to contain malicious and fraudulent keys. It is the common expectation of server operators that users understand this and use software which, like all known common OpenPGP implementations, evaluates trust accordingly. This expectation is so common that it is not normally explicitly stated.
9
10-- Phil Pennock (author of the [SKS](https://bitbucket.org/skskeyserver/sks-keyserver/wiki/Home) key server - http://sks.spodhuis.org/)
11
12Trust can be gained by having your key signed by other people (and signing their key back, too :) ), for instance during [key signing parties](https://en.wikipedia.org/wiki/Key_signing_party): [Keysigning party HOWTO](http://www.cryptnet.net/fdp/crypto/keysigning_party/en/keysigning_party.html),
13
14
15## Generate a GPG key
16- [Generating a GPG key for Git tagging](http://stackoverflow.com/a/16725717) (StackOverflow)
17- [Generating a GPG key](https://help.github.com/articles/generating-a-gpg-key/) (GitHub)
18
19### gpg - provide identity information
20```bash
21$ gpg --gen-key
22
23gpg (GnuPG) 2.1.6; Copyright (C) 2015 Free Software Foundation, Inc.
24This is free software: you are free to change and redistribute it.
25There is NO WARRANTY, to the extent permitted by law.
26
27Note: Use "gpg2 --full-gen-key" for a full featured key generation dialog.
28
29GnuPG needs to construct a user ID to identify your key.
30
31Real name: Marvin the Paranoid Android
32Email address: marvin@h2g2.net
33You selected this USER-ID:
34 "Marvin the Paranoid Android <marvin@h2g2.net>"
35
36Change (N)ame, (E)mail, or (O)kay/(Q)uit? o
37We need to generate a lot of random bytes. It is a good idea to perform
38some other action (type on the keyboard, move the mouse, utilize the
39disks) during the prime generation; this gives the random number
40generator a better chance to gain enough entropy.
41```
42
43### gpg - entropy interlude
44At this point, you will:
45- be prompted for a secure password to protect your key (the input method will depend on your Desktop Environment and configuration)
46- be asked to use your machine's input devices (mouse, keyboard, etc.) to generate random entropy; this step _may take some time_
47
48### gpg - key creation confirmation
49```bash
50gpg: key A9D53A3E marked as ultimately trusted
51public and secret key created and signed.
52
53gpg: checking the trustdb
54gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
55gpg: depth: 0 valid: 2 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 2u
56pub rsa2048/A9D53A3E 2015-07-31
57 Key fingerprint = AF2A 5381 E54B 2FD2 14C4 A9A3 0E35 ACA4 A9D5 3A3E
58uid [ultimate] Marvin the Paranoid Android <marvin@h2g2.net>
59sub rsa2048/8C0EACF1 2015-07-31
60```
61
62### gpg - submit your public key to a PGP server (Optional)
63``` bash
64$ gpg --keyserver pgp.mit.edu --send-keys A9D53A3E
65gpg: sending key A9D53A3E to hkp server pgp.mit.edu
66```
67
68## Create and push a GPG-signed tag
69
70See [Release Shaarli](Release Shaarli).
diff --git a/doc/md/dev/Plugin-system.md b/doc/md/dev/Plugin-system.md
new file mode 100644
index 00000000..c29774de
--- /dev/null
+++ b/doc/md/dev/Plugin-system.md
@@ -0,0 +1,772 @@
1# Plugin system
2
3## Developer API
4
5### What can I do with plugins?
6
7The plugin system lets you:
8
9- insert content into specific places across templates.
10- alter data before templates rendering.
11- alter data before saving new links.
12
13
14### How can I create a plugin for Shaarli?
15
16First, chose a plugin name, such as `demo_plugin`.
17
18Under `plugin` folder, create a folder named with your plugin name. Then create a <plugin_name>.meta file and a <plugin_name>.php file in that folder.
19
20You should have the following tree view:
21
22```
23| index.php
24| plugins/
25|---| demo_plugin/
26| |---| demo_plugin.meta
27| |---| demo_plugin.php
28```
29
30
31### Plugin initialization
32
33At the beginning of Shaarli execution, all enabled plugins are loaded. At this point, the plugin system looks for an `init()` function in the <plugin_name>.php to execute and run it if it exists. This function must be named this way, and takes the `ConfigManager` as parameter.
34
35 <plugin_name>_init($conf)
36
37This 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.
38
39The plugin system also looks for a `description` variable in the <plugin_name>.meta file, to be displayed in the plugin administration page.
40
41 description="The plugin does this and that."
42
43### Understanding hooks
44
45A plugin is a set of functions. Each function will be triggered by the plugin system at certain point in Shaarli execution.
46
47These functions need to be named with this pattern:
48
49```
50hook_<plugin_name>_<hook_name>($data, $conf)
51```
52
53Parameters:
54
55- data: see [$data section](https://shaarli.readthedocs.io/en/master/Plugin-System/#plugins-data)
56- conf: the `ConfigManager` instance.
57
58For example, if my plugin want to add data to the header, this function is needed:
59
60 hook_demo_plugin_render_header
61
62If this function is declared, and the plugin enabled, it will be called every time Shaarli is rendering the header.
63
64
65### Plugin's data
66
67#### Parameters
68
69Every hook function has a `$data` parameter. Its content differs for each hooks.
70
71**This parameter needs to be returned every time**, otherwise data is lost.
72
73 return $data;
74
75#### Special data
76
77Special additional data are passed to every hook through the
78`$data` parameter to give you access to additional context, and services.
79
80Complete list:
81
82 * `_PAGE_` (string): if the current hook is used to render a template, its name is passed through this additional parameter.
83 * `_LOGGEDIN_` (bool): whether the user is logged in or not.
84 * `_BASE_PATH_` (string): if Shaarli instance is hosted under a subfolder, contains the subfolder path to `index.php` (e.g. `https://domain.tld/shaarli/` -> `/shaarli/`).
85 * `_BOOKMARK_SERVICE_` (`BookmarkServiceInterface`): bookmark service instance, for advanced usage.
86
87Example:
88
89```php
90if ($data['_PAGE_'] === TemplatePage::LINKLIST && $data['LOGGEDIN'] === true) {
91 // Do something for logged in users when the link list is rendered
92}
93```
94
95#### Filling templates placeholder
96
97Template placeholders are displayed in template in specific places.
98
99RainTPL displays every element contained in the placeholder's array. These element can be added by plugins.
100
101For example, let's add a value in the placeholder `top_placeholder` which is displayed at the top of my page:
102
103```php
104$data['top_placeholder'][] = 'My content';
105# OR
106array_push($data['top_placeholder'], 'My', 'content');
107
108return $data;
109```
110
111
112#### Data manipulation
113
114When a page is displayed, every variable send to the template engine is passed to plugins before that in `$data`.
115
116The data contained by this array can be altered before template rendering.
117
118For example, in linklist, it is possible to alter every title:
119
120```php
121// mind the reference if you want $data to be altered
122foreach ($data['links'] as &$value) {
123 // String reverse every title.
124 $value['title'] = strrev($value['title']);
125}
126
127return $data;
128```
129
130### Metadata
131
132Every plugin needs a `<plugin_name>.meta` file, which is in fact an `.ini` file (`KEY="VALUE"`), to be listed in plugin administration.
133
134Each file contain two keys:
135
136- `description`: plugin description
137- `parameters`: user parameter names, separated by a `;`.
138- `parameter.<PARAMETER_NAME>`: add a text description the specified parameter.
139
140> Note: In PHP, `parse_ini_file()` seems to want strings to be between by quotes `"` in the ini file.
141
142### Understanding relative paths
143
144Because Shaarli is a self-hosted tool, an instance can either be installed at the root directory, or under a subfolder.
145This means that you can *never* use absolute paths (eg `/plugins/mything/file.png`).
146
147If a file needs to be included in server end, use simple relative path:
148`PluginManager::$PLUGINS_PATH . '/mything/template.html'`.
149
150If it needs to be included in front end side (e.g. an image),
151the relative path must be prefixed with special data `_BASE_PATH_`:
152`($data['_BASE_PATH_'] ?? '') . '/' . PluginManager::$PLUGINS_PATH . '/mything/picture.png`.
153
154Note that special placeholders for CSS and JS files (respectively `css_files` and `js_files`) are already prefixed
155with the base path in template files.
156
157### It's not working!
158
159Use `demo_plugin` as a functional example. It covers most of the plugin system features.
160
161If it's still not working, please [open an issue](https://github.com/shaarli/Shaarli/issues/new).
162
163
164### Hooks
165
166| Hooks | Description |
167| ------------- |:-------------:|
168| [render_header](#render_header) | Allow plugin to add content in page headers. |
169| [render_includes](#render_includes) | Allow plugin to include their own CSS files. |
170| [render_footer](#render_footer) | Allow plugin to add content in page footer and include their own JS files. |
171| [render_linklist](#render_linklist) | It allows to add content at the begining and end of the page, after every link displayed and to alter link data. |
172| [render_editlink](#render_editlink) | Allow to add fields in the form, or display elements. |
173| [render_tools](#render_tools) | Allow to add content at the end of the page. |
174| [render_picwall](#render_picwall) | Allow to add content at the top and bottom of the page. |
175| [render_tagcloud](#render_tagcloud) | Allow to add content at the top and bottom of the page, and after all tags. |
176| [render_taglist](#render_taglist) | Allow to add content at the top and bottom of the page, and after all tags. |
177| [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. |
178| [render_feed](#render_feed) | Allow to do add tags in RSS and ATOM feeds. |
179| [save_link](#save_link) | Allow to alter the link being saved in the datastore. |
180| [delete_link](#delete_link) | Allow to do an action before a link is deleted from the datastore. |
181| [save_plugin_parameters](#save_plugin_parameters) | Allow to manipulate plugin parameters before they're saved. |
182
183
184#### render_header
185
186Triggered on every page - allows plugins to add content in page headers.
187
188
189##### Data
190
191`$data` is an array containing:
192
193 - [Special data](#special-data)
194
195##### Template placeholders
196
197Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
198
199List of placeholders:
200
201- `buttons_toolbar`: after the list of buttons in the header.
202
203![buttons_toolbar_example](http://i.imgur.com/ssJUOrt.png)
204
205- `fields_toolbar`: after search fields in the header.
206
207> Note: This will only be called in linklist.
208
209![fields_toolbar_example](http://i.imgur.com/3GMifI2.png)
210
211
212#### render_includes
213
214Triggered on every page - allows plugins to include their own CSS files.
215
216##### data
217
218`$data` is an array containing:
219
220 - [Special data](#special-data)
221
222##### Template placeholders
223
224Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
225
226List of placeholders:
227
228- `css_files`: called after loading default CSS.
229
230> Note: only add the path of the CSS file. E.g: `plugins/demo_plugin/custom_demo.css`.
231
232
233#### render_footer
234
235Triggered on every page.
236
237Allow plugin to add content in page footer and include their own JS files.
238
239##### data
240
241`$data` is an array containing:
242
243 - [Special data](#special-data)
244
245##### Template placeholders
246
247Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
248
249List of placeholders:
250
251- `text`: called after the end of the footer text.
252- `endofpage`: called at the end of the page.
253
254![text_example](http://i.imgur.com/L5S2YEH.png)
255
256- `js_files`: called at the end of the page, to include custom JS scripts.
257
258> Note: only add the path of the JS file. E.g: `plugins/demo_plugin/custom_demo.js`.
259
260
261#### render_linklist
262
263Triggered when `linklist` is displayed (list of links, permalink, search, tag filtered, etc.).
264
265It allows to add content at the begining and end of the page, after every link displayed and to alter link data.
266
267##### data
268
269`$data` is an array containing:
270
271 - All templates data, including links.
272 - [Special data](#special-data)
273
274##### template placeholders
275
276Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
277
278List of placeholders:
279
280- `action_plugin`: next to the button "private only" at the top and bottom of the page.
281
282![action_plugin_example](http://i.imgur.com/Q12PWg0.png)
283
284- `link_plugin`: for every link, between permalink and link URL.
285
286![link_plugin_example](http://i.imgur.com/3oDPhWx.png)
287
288- `plugin_start_zone`: before displaying the template content.
289
290![plugin_start_zone_example](http://i.imgur.com/OVBkGy3.png)
291
292- `plugin_end_zone`: after displaying the template content.
293
294![plugin_end_zone_example](http://i.imgur.com/6IoRuop.png)
295
296
297#### render_editlink
298
299Triggered when the link edition form is displayed.
300
301Allow to add fields in the form, or display elements.
302
303##### data
304
305`$data` is an array containing:
306
307 - All templates data.
308 - [Special data](#special-data)
309
310##### template placeholders
311
312Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
313
314List of placeholders:
315
316- `edit_link_plugin`: after tags field.
317
318![edit_link_plugin_example](http://i.imgur.com/5u17Ens.png)
319
320
321#### render_tools
322
323Triggered when the "tools" page is displayed.
324
325Allow to add content at the end of the page.
326
327##### data
328
329`$data` is an array containing:
330
331 - All templates data.
332 - [Special data](#special-data)
333
334##### template placeholders
335
336Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
337
338List of placeholders:
339
340- `tools_plugin`: at the end of the page.
341
342![tools_plugin_example](http://i.imgur.com/Bqhu9oQ.png)
343
344
345#### render_picwall
346
347Triggered when picwall is displayed.
348
349Allow to add content at the top and bottom of the page.
350
351##### data
352
353`$data` is an array containing:
354
355 - All templates data.
356 - [Special data](#special-data)
357
358##### template placeholders
359
360Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
361
362List of placeholders:
363
364- `plugin_start_zone`: before displaying the template content.
365- `plugin_end_zone`: after displaying the template content.
366
367![plugin_start_end_zone_example](http://i.imgur.com/tVTQFER.png)
368
369
370#### render_tagcloud
371
372Triggered when tagcloud is displayed.
373
374Allow to add content at the top and bottom of the page.
375
376##### data
377
378`$data` is an array containing:
379
380 - All templates data.
381 - [Special data](#special-data)
382
383##### Template placeholders
384
385Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
386
387List of placeholders:
388
389- `plugin_start_zone`: before displaying the template content.
390- `plugin_end_zone`: after displaying the template content.
391
392For each tag, the following placeholder can be used:
393
394- `tag_plugin`: after each tag
395
396![plugin_start_end_zone_example](http://i.imgur.com/vHmyT3a.png)
397
398
399#### render_taglist
400
401Triggered when taglist is displayed - allows to add content at the top and bottom of the page.
402
403##### data
404
405`$data` is an array containing:
406
407 - All templates data.
408 - [Special data](#special-data)
409
410##### Template placeholders
411
412Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
413
414List of placeholders:
415
416- `plugin_start_zone`: before displaying the template content.
417- `plugin_end_zone`: after displaying the template content.
418
419For each tag, the following placeholder can be used:
420
421- `tag_plugin`: after each tag
422
423#### render_daily
424
425Triggered when tagcloud is displayed.
426
427Allow to add content at the top and bottom of the page, the bottom of each link and to alter data.
428
429
430##### data
431
432`$data` is an array containing:
433
434 - All templates data, including links.
435 - [Special data](#special-data)
436
437##### Template placeholders
438
439Items can be displayed in templates by adding an entry in `$data['<placeholder>']` array.
440
441List of placeholders:
442
443- `link_plugin`: used at bottom of each link.
444
445![link_plugin_example](http://i.imgur.com/hzhMfSZ.png)
446
447- `plugin_start_zone`: before displaying the template content.
448- `plugin_end_zone`: after displaying the template content.
449
450
451#### render_feed
452
453Triggered when the ATOM or RSS feed is displayed.
454
455Allow to add tags in the feed, either in the header or for each items. Items (links) can also be altered before being rendered.
456
457##### data
458
459`$data` is an array containing:
460
461 - All templates data, including links.
462 - [Special data](#special-data)
463
464##### Template placeholders
465
466Tags can be added in feeds by adding an entry in `$data['<placeholder>']` array.
467
468List of placeholders:
469
470- `feed_plugins_header`: used as a header tag in the feed.
471
472For each links:
473
474- `feed_plugins`: additional tag for every link entry.
475
476
477#### save_link
478
479Triggered when a link is save (new link or edit).
480
481Allow to alter the link being saved in the datastore.
482
483##### data
484
485`$data` is an array containing the link being saved:
486
487- id
488- title
489- url
490- shorturl
491- description
492- private
493- tags
494- created
495- updated
496
497Also [special data](#special-data).
498
499
500#### delete_link
501
502Triggered when a link is deleted.
503
504Allow to execute any action before the link is actually removed from the datastore
505
506##### data
507
508`$data` is an array containing the link being deleted:
509
510- id
511- title
512- url
513- shorturl
514- description
515- private
516- tags
517- created
518- updated
519
520Also [special data](#special-data).
521
522#### save_plugin_parameters
523
524Triggered when the plugin parameters are saved from the plugin administration page.
525
526Plugins can perform an action every times their settings are updated.
527For example it is used to update the CSS file of the `default_colors` plugins.
528
529##### data
530
531`$data` input contains the `$_POST` array.
532
533So if the plugin has a parameter called `MYPLUGIN_PARAMETER`,
534the array will contain an entry with `MYPLUGIN_PARAMETER` as a key.
535
536Also [special data](#special-data).
537
538## Guide for template designers
539
540### Plugin administration
541
542Your theme must include a plugin administration page: `pluginsadmin.html`.
543
544> Note: repo's template link needs to be added when the PR is merged.
545
546Use the default one as an example.
547
548Aside from classic RainTPL loops, plugins order is handle by JavaScript. You can just include `plugin_admin.js`, only if:
549
550- you're using a table.
551- you call orderUp() and orderUp() onclick on arrows.
552- you add data-line and data-order to your rows.
553
554Otherwise, you can use your own JS as long as this field is send by the form:
555
556<input type="hidden" name="order_{$key}" value="{$counter}">
557
558### Placeholder system
559
560In order to make plugins work with every custom themes, you need to add variable placeholder in your templates.
561
562It's a RainTPL loop like this:
563
564 {loop="$plugin_variable"}
565 {$value}
566 {/loop}
567
568You should enable `demo_plugin` for testing purpose, since it uses every placeholder available.
569
570### List of placeholders
571
572**page.header.html**
573
574At the end of the menu:
575
576 {loop="$plugins_header.buttons_toolbar"}
577 {$value}
578 {/loop}
579
580At the end of file, before clearing floating blocks:
581
582 {if="!empty($plugin_errors) && $is_logged_in"}
583 <ul class="errors">
584 {loop="plugin_errors"}
585 <li>{$value}</li>
586 {/loop}
587 </ul>
588 {/if}
589
590**includes.html**
591
592At the end of the file:
593
594```html
595{loop="$plugins_includes.css_files"}
596<link type="text/css" rel="stylesheet" href="{$value}#"/>
597{/loop}
598```
599
600**page.footer.html**
601
602At the end of your footer notes:
603
604```html
605{loop="$plugins_footer.text"}
606 {$value}
607{/loop}
608```
609
610At the end of file:
611
612```html
613{loop="$plugins_footer.js_files"}
614 <script src="{$value}#"></script>
615{/loop}
616```
617
618**linklist.html**
619
620After search fields:
621
622```html
623{loop="$plugins_header.fields_toolbar"}
624 {$value}
625{/loop}
626```
627
628Before displaying the link list (after paging):
629
630```html
631{loop="$plugin_start_zone"}
632 {$value}
633{/loop}
634```
635
636For every links (icons):
637
638```html
639{loop="$value.link_plugin"}
640 <span>{$value}</span>
641{/loop}
642```
643
644Before end paging:
645
646```html
647{loop="$plugin_end_zone"}
648 {$value}
649{/loop}
650```
651
652**linklist.paging.html**
653
654After the "private only" icon:
655
656```html
657{loop="$action_plugin"}
658 {$value}
659{/loop}
660```
661
662**editlink.html**
663
664After tags field:
665
666```html
667{loop="$edit_link_plugin"}
668 {$value}
669{/loop}
670```
671
672**tools.html**
673
674After the last tool:
675
676```html
677{loop="$tools_plugin"}
678 {$value}
679{/loop}
680```
681
682**picwall.html**
683
684Top:
685
686```html
687<div id="plugin_zone_start_picwall" class="plugin_zone">
688 {loop="$plugin_start_zone"}
689 {$value}
690 {/loop}
691</div>
692```
693
694Bottom:
695
696```html
697<div id="plugin_zone_end_picwall" class="plugin_zone">
698 {loop="$plugin_end_zone"}
699 {$value}
700 {/loop}
701</div>
702```
703
704**tagcloud.html**
705
706Top:
707
708```html
709 <div id="plugin_zone_start_tagcloud" class="plugin_zone">
710 {loop="$plugin_start_zone"}
711 {$value}
712 {/loop}
713 </div>
714```
715
716Bottom:
717
718```html
719 <div id="plugin_zone_end_tagcloud" class="plugin_zone">
720 {loop="$plugin_end_zone"}
721 {$value}
722 {/loop}
723 </div>
724```
725
726**daily.html**
727
728Top:
729
730```html
731<div id="plugin_zone_start_picwall" class="plugin_zone">
732 {loop="$plugin_start_zone"}
733 {$value}
734 {/loop}
735</div>
736```
737
738After every link:
739
740```html
741<div class="dailyEntryFooter">
742 {loop="$link.link_plugin"}
743 {$value}
744 {/loop}
745</div>
746```
747
748Bottom:
749
750```html
751<div id="plugin_zone_end_picwall" class="plugin_zone">
752 {loop="$plugin_end_zone"}
753 {$value}
754 {/loop}
755</div>
756```
757
758**feed.atom.xml** and **feed.rss.xml**:
759
760In headers tags section:
761```xml
762{loop="$feed_plugins_header"}
763 {$value}
764{/loop}
765```
766
767After each entry:
768```xml
769{loop="$value.feed_plugins"}
770 {$value}
771{/loop}
772```
diff --git a/doc/md/dev/Release-Shaarli.md b/doc/md/dev/Release-Shaarli.md
new file mode 100644
index 00000000..2c772406
--- /dev/null
+++ b/doc/md/dev/Release-Shaarli.md
@@ -0,0 +1,145 @@
1# Release Shaarli
2
3## Requirements
4
5This guide assumes that you have:
6
7- a GPG key matching your GitHub authentication credentials/email (the email address identified by the GPG key is the same as the one in your `~/.gitconfig`)
8- a GitHub fork of Shaarli
9- a local clone of your Shaarli fork, with the following remotes:
10 - `origin` pointing to your GitHub fork
11 - `upstream` pointing to the main Shaarli repository
12- maintainer permissions on the main Shaarli repository, to:
13 - push the signed tag
14 - create a new release
15- [Composer](https://getcomposer.org/) needs to be installed
16- The [venv](https://docs.python.org/3/library/venv.html) Python 3 module needs to be installed for HTML documentation generation.
17
18## Release notes and `CHANGELOG.md`
19
20GitHub allows drafting the release notes for the upcoming release, from the [Releases](https://github.com/shaarli/Shaarli/releases) page. This way, the release note can be drafted while contributions are merged to `master`. See http://keepachangelog.com/en/0.3.0/ for changelog formatting.
21
22`CHANGELOG.md` should contain the same information as the release note draft for the upcoming version. Update it to:
23
24- add new entries (additions, fixes, etc.)
25- mark the current version as released by setting its date and link
26- add a new section for the future unreleased version
27
28```bash
29## [v0.x.y](https://github.com/shaarli/Shaarli/releases/tag/v0.x.y) - UNRELEASES
30
31### Added
32
33### Changed
34
35### Fixed
36
37### Removed
38
39### Deprecated
40
41### Security
42
43```
44
45
46## Update the list of Git contributors
47
48```bash
49$ make authors
50$ git commit -s -m "Update AUTHORS"
51```
52
53## Create and merge a Pull Request
54
55Create a Pull Request to marge changes from your remote, into `master` in the community Shaarli repository, and have it merged.
56
57
58## Create the release branch and update shaarli_version.php
59
60```bash
61# fetch latest changes from master to your local copy
62git checkout master
63git pull upstream master
64
65# If releasing a new minor version, create a release branch
66$ git checkout -b v0.x
67
68# Bump shaarli_version.php from dev to 0.x.0, **without the v**
69$ vim shaarli_version.php
70$ git add shaarli_version
71$ git commit -s -m "Bump Shaarli version to v0.x.0"
72$ git push upstream v0.x
73```
74
75## Create and push a signed tag
76
77Git [tags](http://git-scm.com/book/en/v2/Distributed-Git-Maintaining-a-Project#Tagging-Your-Releases) are used to identify specific revisions with a unique version number that follows [semantic versioning](https://semver.org/)
78
79```bash
80# update your local copy
81git checkout v0.5
82git pull upstream v0.5
83
84# create a signed tag
85git tag -s -m "Release v0.5.0" v0.5.0
86
87# push the tag to upstream
88git push --tags upstream
89```
90
91Here is how to verify a signed tag. [`v0.5.0`](https://github.com/shaarli/Shaarli/releases/tag/v0.5.0) is the first GPG-signed tag pushed on the Community Shaarli. Let's have a look at its signature!
92
93```bash
94# update the list of available tags
95git fetch upstream
96
97# get the SHA1 reference of the tag
98git show-ref tags/v0.5.0
99# gives: f7762cf803f03f5caf4b8078359a63783d0090c1 refs/tags/v0.5.0
100
101# verify the tag signature information
102git verify-tag f7762cf803f03f5caf4b8078359a63783d0090c1
103# gpg: Signature made Thu 30 Jul 2015 11:46:34 CEST using RSA key ID 4100DF6F
104# gpg: Good signature from "VirtualTam <virtualtam@flibidi.net>" [ultimate]
105```
106
107## Publish the GitHub release
108
109- In the `master` banch, update version badges in `README.md` to point to the newly released Shaarli version
110- Update the previously drafted [release](https://github.com/shaarli/Shaarli/releases) (notes, tag) and publish it
111- Profit!
112
113
114## Generate full release zip archives
115
116Release archives will contain Shaarli code plus all required third-party libraries. They are useful for users who:
117
118- have no SSH access, no possibility to install PHP packages/server extensions, no possibility to run scripts (shared hosting)
119- do not want to install build/dev dependencies on their server
120
121 `git checkout` the appropriate branch, then:
122
123```bash
124# checkout the appropriate branch
125git checkout 0.x.y
126# generate zip archives
127make release_archive
128```
129
130This will create `shaarli-v0.x.y-full.tar`, `shaarli-v0.x.y-full.zip`. These archives need to be manually uploaded on the previously created GitHub [release](https://github.com/shaarli/Shaarli/releases).
131
132
133### Update the `latest` branch
134
135```bash
136# checkout the 'latest' branch
137git checkout latest
138# merge changes from your newly published release branch
139git merge v0.x.y
140# fix eventual conflicts with git mergetool...
141# run tests
142make test
143# push the latest branch
144git push upstream latest
145```
diff --git a/doc/md/dev/Theming.md b/doc/md/dev/Theming.md
new file mode 100644
index 00000000..1ad30465
--- /dev/null
+++ b/doc/md/dev/Theming.md
@@ -0,0 +1,86 @@
1# Theming
2
3## Foreword
4
5There are two ways of customizing how Shaarli looks:
6
71. by using a custom CSS to override Shaarli's CSS
82. by using a full theme that provides its own RainTPL templates, CSS and Javascript resources
9
10## Custom CSS
11
12Shaarli's appearance can be modified by adding CSS rules to:
13
14- Shaarli < `v0.9.0`: `inc/user.css`
15- Shaarli >= `v0.9.0`: `data/user.css`
16
17This file allows overriding rules defined in the template CSS files (only add changed rules), or define a whole new theme.
18
19**Note**: Do not edit `tpl/default/css/shaarli.css`! Your changes would be overridden when updating Shaarli.
20
21## Themes
22
23Installation:
24
25- find a theme you'd like to install
26- copy or clone the theme folder under `tpl/<a_sweet_theme>`
27- enable the theme:
28 - Shaarli < `v0.9.0`: edit `data/config.json.php` and set the value of `raintpl_tpl` to the new theme name:
29 `"raintpl_tpl": "tpl\/my-template\/"`
30 - Shaarli >= `v0.9.0`: select the theme through the _Tools_ page
31
32## Community CSS & themes
33
34### Custom CSS
35
36- [mrjovanovic/serious-theme-shaarli](https://github.com/mrjovanovic/serious-theme-shaarli) - A serious theme for Shaarli
37- [shaarli/shaarli-themes](https://github.com/shaarli/shaarli-themes)
38
39### Themes
40
41- [AkibaTech/Shaarli Superhero Theme](https://github.com/AkibaTech/Shaarli---SuperHero-Theme) - A template/theme for Shaarli
42- [alexisju/albinomouse-template](https://github.com/alexisju/albinomouse-template) - A full template for Shaarli
43- [ArthurHoaro/shaarli-launch](https://github.com/ArthurHoaro/shaarli-launch) - Customizable Shaarli theme
44- [dhoko/ShaarliTemplate](https://github.com/dhoko/ShaarliTemplate) - A template/theme for Shaarli
45- [kalvn/shaarli-blocks](https://github.com/kalvn/shaarli-blocks) - A template/theme for Shaarli
46- [kalvn/Shaarli-Material](https://github.com/kalvn/Shaarli-Material) - A theme (template) based on Google's Material Design for Shaarli, the superfast delicious clone
47- [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
48- [xfnw/shaarli-default-dark](https://github.com/xfnw/shaarli-default-dark) - The default theme but nice and dark for your eyeballs
49
50### Shaarli forks
51
52- [misterair/Limonade](https://github.com/misterair/limonade) - A fork of (legacy) Shaarli with a new template
53- [vivienhaese/shaarlitheme](https://github.com/vivienhaese/shaarlitheme) - A Shaarli fork meant to be run in an openshift instance
54
55## Example installation: AlbinoMouse theme
56
57With the following configuration:
58
59- Apache 2 / PHP 5.6
60- user sites are enabled, e.g. `/home/user/public_html/somedir` is served as `http://localhost/~user/somedir`
61- `http` is the name of the Apache user
62
63```bash
64$ cd ~/public_html
65
66# clone repositories
67$ git clone https://github.com/shaarli/Shaarli.git shaarli
68$ pushd shaarli/tpl
69$ git clone https://github.com/alexisju/albinomouse-template.git
70$ popd
71
72# set access rights for Apache
73$ chgrp -R http shaarli
74$ chmod g+rwx shaarli shaarli/cache shaarli/data shaarli/pagecache shaarli/tmp
75```
76
77Get config written:
78- go to the freshly installed site
79- fill the install form
80- log in to Shaarli
81
82Edit Shaarli's [configuration](Shaarli-configuration):
83```bash
84# the file should be owned by Apache, thus not writeable => sudo
85$ sudo sed -i s=tpl=tpl/albinomouse-template=g shaarli/data/config.php
86```
diff --git a/doc/md/dev/Translations.md b/doc/md/dev/Translations.md
new file mode 100644
index 00000000..8f3b8f10
--- /dev/null
+++ b/doc/md/dev/Translations.md
@@ -0,0 +1,157 @@
1## Translations
2
3Shaarli supports [gettext](https://www.gnu.org/software/gettext/manual/gettext.html) translations
4since `>= v0.9.2`.
5
6Note that only the `default` theme supports translations.
7
8### Contributing
9
10We encourage the community to contribute to Shaarli translations, either by improving existing translations or submitting a new language.
11
12Contributing to the translation does not require software development knowledge.
13
14Please submit a pull request with the `.po` file updated/created. Note that the compiled file (`.mo`) is not stored on the repository, and is generated during the release process.
15
16
17### How to
18
19Install [Poedit](https://poedit.net/) (used to extract strings to translate from the PHP source code, and generate `.po` files).
20
21Due to the usage of a template engine, it's important to generate PHP cache files to extract every translatable string. You can either use [this script](https://gist.github.com/ArthurHoaro/5d0323f758ab2401ef444a53f54e9a07) (recommended) or visit every template page in your browser to generate cache files, while logged in. Here is a list :
22
23```
24http://<replace_domain>/
25http://<replace_domain>/login
26http://<replace_domain>/daily
27http://<replace_domain>/tags/cloud
28http://<replace_domain>/tags/list
29http://<replace_domain>/picture-wall
30http://<replace_domain>/?nonope
31http://<replace_domain>/admin/add-shaare
32http://<replace_domain>/admin/password
33http://<replace_domain>/admin/tags
34http://<replace_domain>/admin/configure
35http://<replace_domain>/admin/tools
36http://<replace_domain>/admin/shaare
37http://<replace_domain>/admin/export
38http://<replace_domain>/admin/import
39http://<replace_domain>/admin/plugins
40```
41
42
43#### Improve existing translations
44
45- In Poedit, click on "Edit a Translation
46- Open `inc/languages/<lang>/LC_MESSAGES/shaarli.po` under Shaarli's directory
47- The existing list of translatable strings should load
48- Click on the "Update" button.
49- Start editing translations.
50
51![poedit-screenshot](images/poedit-1.jpg)
52
53Save when you're done, then you can submit a pull request containing the updated `shaarli.po`.
54
55
56#### Add a new language
57
58- In Poedit select "Create New Translation"
59- Open `inc/languages/<lang>/LC_MESSAGES/shaarli.po` under Shaarli's directory
60- Select the language you want to create.
61- Click on `File > Save as...`, save your file in `<shaarli directory>/inc/language/<new language>/LC_MESSAGES/shaarli.po` (`<new language>` here should be the language code respecting the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-2) format in lowercase - e.g. `de` for German)
62- Click on the "Update" button
63- Start editing translations.
64
65Save when you're done, then you can submit a pull request containing the new `shaarli.po`.
66
67
68### Theme translations
69
70[Theme](Theming) translation extensions are loaded automatically if they're present.
71
72As a theme developer, all you have to do is to add the `.po` and `.mo` compiled file like this:
73
74```
75tpl/<theme name>/language/<lang>/LC_MESSAGES/<theme name>.po
76tpl/<theme name>/language/<lang>/LC_MESSAGES/<theme name>.mo
77```
78
79Where `<lang>` is the ISO 3166-1 alpha-2 language code.
80
81Read the following section "Extend Shaarli's translation" to learn how to generate those files.
82
83
84### Extend Shaarli's translation
85
86If you're writing a custom theme, or a non official plugin, you might want to use the translation system,
87but you won't be able to able to override Shaarli's translation.
88
89However, you can add your own translation domain which extends the main translation list.
90
91> Note that you can find a live example of translation extension in the `demo_plugin`.
92
93First, create your translation files tree directory:
94
95```
96<your_module>/languages/<ISO 3166-1 alpha-2 language code>/LC_MESSAGES/
97```
98
99Your `.po` files must be named like your domain. E.g. if your translation domain is `my_theme`, then your file will be
100`my_theme.po`.
101
102Users have to register your extension in their configuration with the parameter
103`translation.extensions.<domain>: <translation files path>`.
104
105Example:
106
107```php
108if (! $conf->exists('translation.extensions.my_theme')) {
109 $conf->set('translation.extensions.my_theme', '<your_module>/languages/');
110 $conf->write(true);
111}
112```
113
114> Note that the page needs to be reloaded after the registration.
115
116It is then recommended to create a custom translation function which will call the `t()` function with your domain.
117For example :
118
119```php
120function my_theme_t($text, $nText = '', $nb = 1)
121{
122 return t($text, $nText, $nb, 'my_theme'); // the last parameter is your translation domain.
123}
124```
125
126All strings which can be translated should be processed through your function:
127
128```php
129my_theme_t('Comment');
130my_theme_t('Comment', 'Comments', 2);
131```
132
133Or in templates:
134
135```php
136{'Comment'|my_theme_t}
137{function="my_theme_t('Comment', 'Comments', 2)"}
138```
139
140> Note than in template, you need to visit your page at least once to generate a cache file.
141
142When you're done, open Poedit and load translation strings from sources:
143
144 1. `File > New`
145 2. Choose your language
146 3. Save your `PO` file in `<your_module>/languages/<language code>/LC_MESSAGES/my_theme.po`.
147 4. Go to `Catalog > Properties...`
148 5. Fill the `Translation Properties` tab
149 6. Add your source path in the `Sources Paths` tab
150 7. In the `Sources Keywords` tab uncheck "Also use default keywords" and add the following lines:
151
152```
153my_theme_t
154my_theme_t:1,2
155```
156
157Click on the "Update" button and you're free to start your translations!
diff --git a/doc/md/dev/Unit-tests.md b/doc/md/dev/Unit-tests.md
new file mode 100644
index 00000000..fd286bf0
--- /dev/null
+++ b/doc/md/dev/Unit-tests.md
@@ -0,0 +1,133 @@
1# Unit tests
2
3Shaarli uses the [PHPUnit](https://phpunit.de/) test framework; it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool.
4
5## Install composer
6
7You can either use:
8
9- a system-wide version, e.g. installed through your distro's package manager
10- a local version, downloadable [here](https://getcomposer.org/download/).
11
12```bash
13# for Debian-based distros
14sudo apt install composer
15```
16
17
18## Install Shaarli dev dependencies
19
20```bash
21$ cd /path/to/shaarli
22$ make composer_dependencies_dev
23```
24
25## Install and enable Xdebug to generate PHPUnit coverage reports
26
27
28[Xdebug](http://xdebug.org/docs/install) is a PHP extension which provides debugging and profiling capabilities. Install Xdebug:
29
30```bash
31# for Debian-based distros:
32sudo apt install php-xdebug
33
34# for ArchLinux:
35pacman -S xdebug
36
37# then add the following line to /etc/php/php.ini
38zend_extension=xdebug.so
39```
40
41## Run unit tests
42
43Ensure tests pass successuflly:
44
45```bash
46make test
47# ...
48# OK (36 tests, 65 assertions)
49```
50
51In case of failure the test suite will point you to actual errors and output a summary:
52
53```bash
54make test
55# ...
56# FAILURES!
57# Tests: 36, Assertions: 63, Errors: 1, Failures: 2.
58```
59
60By default, PHPUnit will run all suitable tests found under the `tests` directory. Each test has 3 possible outcomes:
61
62- `.` - success
63- `F` - failure: the test was run but its results are invalid
64 - the code does not behave as expected
65 - dependencies to external elements: globals, session, cache...
66- `E` - error: something went wrong and the tested code has crashed
67 - typos in the code, or in the test code
68 - dependencies to missing external elements
69
70If Xdebug has been installed and activated, two coverage reports will be generated:
71
72- a summary in the console
73- a detailed HTML report with metrics for tested code
74 - to open it in a web browser: `firefox coverage/index.html &`
75
76
77### Executing specific tests
78
79Add a [`@group`](https://phpunit.de/manual/current/en/appendixes.annotations.html#appendixes.annotations.group) annotation in a test class or method comment:
80
81```php
82/**
83 * Netscape bookmark import
84 * @group WIP
85 */
86class BookmarkImportTest extends PHPUnit_Framework_TestCase
87{
88 [...]
89}
90```
91
92To run all tests annotated with `@group WIP`:
93```bash
94$ vendor/bin/phpunit --group WIP tests/
95```
96
97## Running tests inside Docker containers
98
99Unit tests can be run inside [Docker](../Docker.md) containers.
100
101Test Dockerfiles are located under `tests/docker/<distribution>/Dockerfile`, and can be used to build Docker images to run Shaarli test suites under commonLinux environments. Dockerfiles are provided for the following environments:
102
103- [`alpine36`](https://github.com/shaarli/Shaarli/blob/master/tests/docker/alpine36/Dockerfile) - [Alpine Linux 3.6](https://www.alpinelinux.org/downloads/)
104- [`debian8`](https://github.com/shaarli/Shaarli/blob/master/tests/docker/debian8/Dockerfile) - [Debian 8 Jessie](https://www.debian.org/DebianJessie) (oldoldstable)
105- [`debian9`](https://github.com/shaarli/Shaarli/blob/master/tests/docker/debian9/Dockerfile) - [Debian 9 Stretch](https://wiki.debian.org/DebianStretch) (oldstable)
106- [`ubuntu16`](https://github.com/shaarli/Shaarli/blob/master/tests/docker/ubuntu16/Dockerfile) - [Ubuntu 16.04 Xenial Xerus](http://releases.ubuntu.com/16.04/) (old LTS)
107
108Each image provides:
109- a base Linux OS
110- Shaarli PHP dependencies (OS packages)
111- test PHP dependencies (OS packages)
112- Composer
113- Tests that run inside the conatiner using a standard Linux user account (running tests as `root` would bypass permission checks and may hide issues)
114
115Build a test image:
116
117```bash
118# build the Debian 9 Docker image
119cd /path/to/shaarli/tests/docker/debian9
120docker build -t shaarli-test:debian9 .
121```
122
123Run unit tests in a container:
124
125```bash
126cd /path/to/shaarli
127# install/update 3rd-party test dependencies
128composer install --prefer-dist
129# run tests using the freshly built image
130docker run -v $PWD:/shaarli shaarli-test:debian9 docker_test
131# run the full test campaign
132docker run -v $PWD:/shaarli shaarli-test:debian9 docker_all_tests
133```
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```
diff --git a/doc/md/dev/images/poedit-1.jpg b/doc/md/dev/images/poedit-1.jpg
new file mode 100644
index 00000000..673ae6d6
--- /dev/null
+++ b/doc/md/dev/images/poedit-1.jpg
Binary files differ