[github/shaarli/Shaarli.git] / doc / md / Continuous-integration-tools.md

## Local development
A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations:

- Documentation - generate a local HTML copy of the GitHub wiki
- [Static analysis](Static-analysis) - check that the code is compliant to PHP conventions
- [Unit tests](Unit-tests) - ensure there are no regressions introduced by new commits

## Automatic builds
[Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build:

- each time a commit is merged to the mainline (`master` branch)
- each time a Pull Request is submitted or updated

A build is composed of several jobs: one for each supported PHP version (see [Server requirements](Server requirements)).

Each build job:

- updates Composer
- installs 3rd-party test dependencies with Composer
- runs [Unit tests](Unit-tests)
- runs ESLint check

After all jobs have finished, Travis returns the results to GitHub:

- a status icon represents the result for the `master` branch: [![](https://api.travis-ci.org/shaarli/Shaarli.svg)](https://travis-ci.org/shaarli/Shaarli)
- Pull Requests are updated with the Travis result
    - Green: all tests have passed
    - Red: some tests failed
    - Orange: tests are pending

## Documentation
[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`.
Commit	Line	Data
53ed6d7d	1	## Local development
53ed6d7d	2	A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations:
43ad7c8e	3
53ed6d7d	4	- Documentation - generate a local HTML copy of the GitHub wiki
d7eb06bd A	5	- [Static analysis](Static-analysis) - check that the code is compliant to PHP conventions
d7eb06bd A	6	- [Unit tests](Unit-tests) - ensure there are no regressions introduced by new commits
53ed6d7d	7
	8	## Automatic builds
	9	[Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build:
43ad7c8e	10
53ed6d7d	11	- each time a commit is merged to the mainline (`master` branch)
	12	- each time a Pull Request is submitted or updated
	13
0433c688	14	A build is composed of several jobs: one for each supported PHP version (see [Server requirements](Server requirements)).
53ed6d7d	15
53ed6d7d	16	Each build job:
43ad7c8e	17
53ed6d7d	18	- updates Composer
53ed6d7d	19	- installs 3rd-party test dependencies with Composer
d7eb06bd A	20	- runs [Unit tests](Unit-tests)
d7eb06bd A	21	- runs ESLint check
53ed6d7d	22
53ed6d7d	23	After all jobs have finished, Travis returns the results to GitHub:
43ad7c8e	24
53ed6d7d	25	- a status icon represents the result for the `master` branch: [![](https://api.travis-ci.org/shaarli/Shaarli.svg)](https://travis-ci.org/shaarli/Shaarli)
	26	- Pull Requests are updated with the Travis result
	27	- Green: all tests have passed
	28	- Red: some tests failed
	29	- Orange: tests are pending
954b3c81	30
954b3c81	31	## Documentation
b4665de8	32	[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`.