Skip to content
GitLab
Commit e3312dc0 authored by Fabrice Gangler's avatar Fabrice Gangler 🎨
Browse files

DOC: add some usefull documention (install, ...) 

Refs: #26
parent 3d0a0f9a
Hide whitespace changes
Inline Side-by-side
README.md
View file @ e3312dc0
[![License : AGPL v3](https://img.shields.io/badge/license-AGPL3-blue.svg)](https://gitlab.adullact.net/Comptoir/comptoir/-/blob/master/LICENSE)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://gitlab.adullact.net/Comptoir/comptoir/-/blob/master/CONTRIBUTING.md)
[![Code of Conduct](https://img.shields.io/badge/code%20of-conduct-ff69b4.svg?style=flat-square)](https://gitlab.adullact.net/Comptoir/comptoir/-/blob/master/CODE_OF_CONDUCT.md)
# Comptoir
Comptoir du Libre v3+ (Symfony)
\ No newline at end of file
Comptoir du Libre v3+ (Symfony)
## Documentation
- [Install documentation](documentation/10_Install_doc/)
- [Developer documentation](documentation/30_Contributor_doc/)
- [QA : URL + online tools](documentation/QA-tools.md)
## License
[AGPL v3](LICENSE)
documentation/10_Install_doc/README.md 0 → 100644
View file @ e3312dc0
# Install documentation
Steps to install :
- [Check pre-requisites](webapp_Pre-requisites.md)
- [Install](webapp_Installation.md)
documentation/10_Install_doc/webapp_Installation.md 0 → 100644
View file @ e3312dc0
# Web application installation
You should have already [check pre-requisites](webapp_Pre-requisites.md).
## Ubuntu 18.04
```bash
# Grab source code and installing dependencies
git clone git@gitlab.adullact.net:Comptoir/comptoir.git
cd comptoir/webapp/
composer install
# Starting a web server (not ready for production)
php -S 127.0.0.1:8383 -t public/
```
documentation/10_Install_doc/webapp_Pre-requisites.md 0 → 100644
View file @ e3312dc0
# Prerequisites for web application installation
## Prerequesites
- PHP >= **7.2.5**
- composer
- PHP extensions:
- `ext-ctype` `*`
- `ext-curl`
- `ext-iconv` `*`
- `ext-json`
- `ext-PDO` `*`
- `ext-tokenizer` `*`
- `ext-xml`
- `ext-zip`
`*` installed by default with PHP via the `php-common` package (Ubuntu 18.04)
## Ubuntu 18.04
### 0. Verify prerequisites
#### PHP version
```bash
# List php versions available on the host:
sudo update-alternatives --list php
# Display the default php version:
sudo update-alternatives --display php
php -v
# If suitable PHP version is available, enable it:
sudo update-alternatives --set php /usr/bin/php7.2
php -v
```
#### Checks webapp prerequisites
Checks that PHP and extensions versions match the platform requirements of the installed packages:
```bash
git clone git@gitlab.adullact.net:Comptoir/comptoir.git
cd comptoir/webapp/
composer check-platform-reqs
```
Documentation: https://getcomposer.org/doc/03-cli.md#check-platform-reqs
### 1. Install correct PHP version + extensions
```bash
sudo apt-get update
sudo apt install \
php7.2 \
php7.0-curl \
php7.2-json \
php7.0-xml \
php7.0-zip
```
### 2. Install composer
```bash
sudo apt-get update
sudo apt install composer
```
### 3. Enabled the PHP version needed by webapp
```bash
sudo update-alternatives --set php /usr/bin/php7.2
php -v
```
and verify again with:
```bash
composer check-platform-reqs
```
### Optional
Download `composer` packages in parallel:
- [hirak/prestissimo](https://packagist.org/packages/hirak/prestissimo), a composer plugin that downloads packages in parallel
- `hirak/prestissimo` must be installed globaled for the user who launch `composer install` command.
```bash
composer global require hirak/prestissimo
# hirak/prestissimo requires ext-curl
php -v
sudo apt -y install php<Major.Minor>-curl
```
documentation/30_Contributor_doc/GIT_CONVENTION.md 0 → 100644
View file @ e3312dc0
# Versioning, Changelog and GIT Commit message
## Versioning
We tend to follow the [semantic versioning](http://semver.org/) recommendations :
```shell script
MAJOR.MINOR.PATCH
# MAJOR ---> a breaking change (incompatible API changes)
# MINOR ---> add a new feature
# PATCH ---> fix a bug
```
## Changelog
We use a changelog file which contains a curated, chronologically
ordered list of notable changes for each version of a project.
see: [Keep a Changelog](https://keepachangelog.com/)
## Git Commit message convention
We follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) :
```
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
```
### Type
- `build`: changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm).
- `ci`: changes to the CI configuration files and scripts
- `chore`: update something without impacting the user (ex: bump a dependency in composer.json).
- `docs`: documentation only changes
- `feat`: add a new feature (equivalent to a `MINOR` in Semantic Versioning)
- `fix`: fix a bug (equivalent to a `PATCH` in Semantic Versioning).
- `perf`: a code change that improves performance.
- `refactor`: a code change that neither fixes a bug nor adds a feature.
- `revert`: revert a commit.
- `style`: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
- `test`: adding missing tests, refactoring tests; no production code change.
### Regex
The commit message should follow this regex:
```perl
/^(revert: )?(build|ci|chore|docs|feat|fix|perf|refactor|style|refactor|revert|style|test|)(\(.+\))?: .{1,50}/
```
### See also
- [Git Commit Msg](http://karma-runner.github.io/1.0/dev/git-commit-msg.html)
- [Semantic Commit Messages](https://seesparkbox.com/foundry/semantic_commit_messages)
- [Enhance your git log with conventional commits](https://dev.to/maxpou/enhance-your-git-log-with-conventional-commits-3ea4)
- [Working with Git : conventional commits, branch model naming](https://slides.com/damianopetrungaro/working-with-git#/)
- [fr / Comment écrire un bon message de commit ?](https://www.dotnetdojo.com/git-commit/)
- examples:
- [Angular commit guidelines](https://github.com/angular/angular/blob/master/CONTRIBUTING.md#-commit-message-guidelines)
- [Vue.js commit guidelines](https://github.com/vuejs/vue/blob/dev/.github/COMMIT_CONVENTION.md)
documentation/30_Contributor_doc/QA-tools.md 0 → 100644
View file @ e3312dc0
# QA
https://comptoir-du-libre.org
## URL
- [http + with www](http://www.comptoir-du-libre.org)
- [http + without www](http://comptoir-du-libre.org)
- [https + with www](https://www.comptoir-du-libre.org)
- [https + without www](https://comptoir-du-libre.org) :
- Files:
* [/humans.txt](https://comptoir-du-libre.org/humans.txt)
* [/robots.txt](https://comptoir-du-libre.org/robots.txt)
* [/.well-known/security.txt](https://comptoir-du-libre.org/.well-known/security.txt)
````
https://comptoir-du-libre.org
https://www.comptoir-du-libre.org
http://www.comptoir-du-libre.org
http://comptoir-du-libre.org
https://comptoir-du-libre.org/humans.txt
https://comptoir-du-libre.org/robots.txt
https://comptoir-du-libre.org/.well-known/security.txt
````
## QA - Online tools
`*` preconfigured tools
* HTTP Response :
* [httpstatus.io](https://httpstatus.io/)
* [URLitor - HTTP Status & Redirect Checker](http://www.urlitor.com/)
* [HTTP Response Checker](https://www.webmoves.net/tools/responsechecker)
* [Server Headers](http://tools.seobook.com/server-header-checker/?url=https%3A%2F%2Fcomptoir-du-libre.org%0D%0Ahttps%3A%2F%2Fwww.comptoir-du-libre.org%0D%0Ahttp%3A%2F%2Fwww.comptoir-du-libre.org%0D%0Ahttp%3A%2F%2Fcomptoir-du-libre.org%0D%0A&useragent=11&protocol=11) `*`
* Security
* [Hardenize](https://www.hardenize.com) (DNS, SMTP, web server)
* [Mozilla Observatory](https://observatory.mozilla.org/analyze/comptoir-du-libre.org) `*` (HTTP header, SSL, cookies, ...)
* [Security Headers](https://securityheaders.io/?q=https://comptoir-du-libre.org) `*` (HTTP header)
* Content-Security-Policy (CSP)
* [cspvalidator.org](https://cspvalidator.org/#url=https://comptoir-du-libre.org) `*`
* [csp-evaluator.withgoogle.com](https://csp-evaluator.withgoogle.com/?csp=https://comptoir-du-libre.org) `*`
* SSL
* [ssllabs.com](https://www.ssllabs.com/ssltest/analyze?d=comptoir-du-libre.org) `*`
* [tls.imirhil.fr](https://tls.imirhil.fr/https/comptoir-du-libre.org) `*`
* DNS
* [DNSViz](http://dnsviz.net/d/comptoir-du-libre.org/dnssec/) `*` (DNSSEC)
* [DNSSEC Analyzer (Verisign Labs)](https://dnssec-debugger.verisignlabs.com/comptoir-du-libre.org) `*` (DNSSEC)
* [Zonemaster (iiS and AFNIC)](https://zonemaster.net/domain_check)
* W3C tools
* [HTML validator](https://validator.w3.org/nu/?doc=https://comptoir-du-libre.org&showsource=yes&showoutline=yes&showimagereport=yes) `*`
* [CSS validator](https://jigsaw.w3.org/css-validator/validator?uri=https://comptoir-du-libre.org&profile=css3) `*`
* [i18n checker](https://validator.w3.org/i18n-checker/check?uri=https://comptoir-du-libre.org) `*`
* [Link checker](https://validator.w3.org/checklink?uri=https://comptoir-du-libre.org&hide_type=all&depth=&check=Check) `*`
* Web accessibility
* [Asqatasun](https://app.asqatasun.org)
* Web perf
* [Yellowlab](http://yellowlab.tools)
* [Webpagetest](https://www.webpagetest.org/)
* [Test a single asset from 14 locations](https://tools.keycdn.com/performance?url=https://comptoir-du-libre.org) `*`
* HTTP/2
* [Http2.pro](https://http2.pro/check?url=https://comptoir-du-libre.org) `*` (check server HTTP/2, ALPN, and Server-push support)
* Global tools (webperf, accessibility, security, ...)
* [Dareboost](https://www.dareboost.com) (free trial)
* [Sonarwhal](https://sonarwhal.com/scanner/)
------
* Social networks
* [Twitter card validator](https://cards-dev.twitter.com/validator)
* structured data (JSON-LD, rdf, schema.org, microformats.org, ...)
* [Google structured data testing tool](https://search.google.com/structured-data/testing-tool#url=https://comptoir-du-libre.org/) `*`
* [Structured Data Linter](http://linter.structured-data.org/?url=https://comptoir-du-libre.org) `*`
* [Microdata Parser](https://www.webmoves.net/tools/microdata)
* Google image
* [images used on the website](https://www.google.fr/search?tbm=isch&q=site:comptoir-du-libre.org) `*` (site:comptoir-du-libre.org)
* [images used on the website but hosted on other domains](https://www.google.fr/search?tbm=isch&q=site:comptoir-du-libre.org+-src:comptoir-du-libre.org) `*` (site:comptoir-du-libre.org -src:comptoir-du-libre.org)
* [images hosted on the domain name](https://www.google.fr/search?tbm=isch&q=src:comptoir-du-libre.org) `*` (src:comptoir-du-libre.org)
* [images hosted on the domain name and used by other domain names (hotlinks)](https://www.google.fr/search?tbm=isch&q=src:comptoir-du-libre.org+-site:comptoir-du-libre.org) `*` (src:comptoir-du-libre.org -site:comptoir-du-libre.org)
## QA - Open-source softwares
* [W3C tools](https://w3c.github.io/developers/tools/#tools)
* Security
* [Arachni](https://github.com/Arachni/arachni) (web application security scanner framework)
* Content-Security-Policy (CSP)
* [salvation](https://github.com/shapesecurity/salvation) (Java parser, warn about policy errors)
* Mozilla Observatory
* [CLI client for Mozilla Observatory](https://github.com/mozilla/observatory-cli)
* [HTTP Observatory](https://github.com/mozilla/http-observatory) (local scanner : CLI and CI)
* Web accessibility
* Asqatasun
* [Asqatsun Docker image](https://hub.docker.com/r/asqatasun/asqatasun/)
* [Install Asqatasun on a server](https://doc.asqatasun.org/en/10_Install_doc/Asqatasun/)
* Web perf
* Webpagetest
* [Yellowlab](https://github.com/gmetais/YellowLabTools/) (API, npm CLI, Grunt task, ...)
* [Sitespeed.io](https://www.sitespeed.io/) (npm or docker is needed)
* Global tools
* [Sonarwhal](https://github.com/sonarwhal/sonarwhal) (Node.js v8)
documentation/30_Contributor_doc/README.md 0 → 100644
View file @ e3312dc0
# Developer documentation
Here you will find information for people willing
to understand the internals of **Comptoir-du-Libre**
or bring help to its development.
# Getting started
- [Versioning, Changelog and GIT Commit message](GIT_CONVENTION.md)
- [Install documentation](../10_Install_doc/)
# Start coding
```bash
# Grab source code and installing dependencies
git clone git@gitlab.adullact.net:Comptoir/comptoir.git
cd comptoir/webapp/
composer install
# Starting a web server (not ready for production)
php -S 127.0.0.1:8383 -t public/
```
## Units tests and Functional tests
- https://symfony.com/doc/current/testing.html
- https://symfony.com/doc/current/testing/database.html
- https://symfony.com/doc/current/testing/functional_tests_assertions.html
```bash
cd webapp/
# Run tests
bin/phpunit
bin/phpunit --group ... # Only runs tests from the specified group(s)
bin/phpunit --exclude-group ... # Exclude tests from the specified group(s)
bin/phpunit --testdox-text tests/doc_testsList.txt # run and generated doc
bin/phpunit --testdox-html tests/doc_testsList.html # run and generated doc
# Add functionnal tests and unit tests
bin/console make:functional-test # Creates a new functionnal test
bin/console make:unit-test # Creates a new unit test
bin/phpunit help
bin/phpunit --list-groups # List available test groups
bin/phpunit --list-suites # List available test suites
bin/phpunit --list-tests # List available tests
```
## Symfony Console
```bash
cd webapp/
bin/console about # Displays information about the current project
bin/console help <command> # Displays help for a command
bin/console list # Lists commands
bin/console doctrine:database:create # Creates a new database
bin/console make:migration # Creates a new database migration based on entities changes
bin/console doctrine:migration:migrate # Executes a migration to a specified version or the latest available version.
bin/console make:fixtures # Creates a new class to load Doctrine fixtures
bin/console doctrine:fixtures:load # Load data fixtures to your database
...
bin/console make:controller # Creates a new controller class
bin/console make:crud # Creates CRUD for Doctrine entity class
bin/console make:entity # Creates or updates a Doctrine entity class, and optionally an API Platform resource
bin/console make:form # Creates a new form class
...
bin/console debug:router # Lists all the configured routes in your application
bin/console debug:router <routeName> # Get very specific information on a single route
bin/console router:match <routePath> # Find out which route is associated with the given URL (ex: /blog/)
```
documentation/README.md 0 → 100644
View file @ e3312dc0
# Documentation
- [Install documentation](10_Install_doc/)
- [Developer documentation](30_Contributor_doc/)
- [QA : URL + online tools](QA-tools.md)
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment