From e3312dc0425a973bd8a77b1f17650ee0831e2327 Mon Sep 17 00:00:00 2001
From: Gangler Fabrice <fabrice.gangler@adullact.org>
Date: Thu, 27 Feb 2020 21:44:21 +0100
Subject: [PATCH] DOC: add some usefull documention (install, ...)
Refs: #26
---
README.md | 17 ++-
documentation/10_Install_doc/README.md | 8 ++
.../10_Install_doc/webapp_Installation.md | 15 +++
.../10_Install_doc/webapp_Pre-requisites.md | 95 +++++++++++++++++
.../30_Contributor_doc/GIT_CONVENTION.md | 64 +++++++++++
documentation/30_Contributor_doc/QA-tools.md | 100 ++++++++++++++++++
documentation/30_Contributor_doc/README.md | 74 +++++++++++++
documentation/README.md | 8 ++
8 files changed, 380 insertions(+), 1 deletion(-)
create mode 100644 documentation/10_Install_doc/README.md
create mode 100644 documentation/10_Install_doc/webapp_Installation.md
create mode 100644 documentation/10_Install_doc/webapp_Pre-requisites.md
create mode 100644 documentation/30_Contributor_doc/GIT_CONVENTION.md
create mode 100644 documentation/30_Contributor_doc/QA-tools.md
create mode 100644 documentation/30_Contributor_doc/README.md
create mode 100644 documentation/README.md
diff --git a/README.md b/README.md
index 692807d..f225611 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,18 @@
+[](https://gitlab.adullact.net/Comptoir/comptoir/-/blob/master/LICENSE)
+[](https://gitlab.adullact.net/Comptoir/comptoir/-/blob/master/CONTRIBUTING.md)
+[](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)
diff --git a/documentation/10_Install_doc/README.md b/documentation/10_Install_doc/README.md
new file mode 100644
index 0000000..ec1b0d6
--- /dev/null
+++ b/documentation/10_Install_doc/README.md
@@ -0,0 +1,8 @@
+# Install documentation
+
+Steps to install :
+- [Check pre-requisites](webapp_Pre-requisites.md)
+- [Install](webapp_Installation.md)
+
+
+
diff --git a/documentation/10_Install_doc/webapp_Installation.md b/documentation/10_Install_doc/webapp_Installation.md
new file mode 100644
index 0000000..cab6453
--- /dev/null
+++ b/documentation/10_Install_doc/webapp_Installation.md
@@ -0,0 +1,15 @@
+# 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/
+```
diff --git a/documentation/10_Install_doc/webapp_Pre-requisites.md b/documentation/10_Install_doc/webapp_Pre-requisites.md
new file mode 100644
index 0000000..0066136
--- /dev/null
+++ b/documentation/10_Install_doc/webapp_Pre-requisites.md
@@ -0,0 +1,95 @@
+#Â 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
+```
diff --git a/documentation/30_Contributor_doc/GIT_CONVENTION.md b/documentation/30_Contributor_doc/GIT_CONVENTION.md
new file mode 100644
index 0000000..2abf4d8
--- /dev/null
+++ b/documentation/30_Contributor_doc/GIT_CONVENTION.md
@@ -0,0 +1,64 @@
+
+# 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)
+
+
+
+
diff --git a/documentation/30_Contributor_doc/QA-tools.md b/documentation/30_Contributor_doc/QA-tools.md
new file mode 100644
index 0000000..97837ab
--- /dev/null
+++ b/documentation/30_Contributor_doc/QA-tools.md
@@ -0,0 +1,100 @@
+# 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)
diff --git a/documentation/30_Contributor_doc/README.md b/documentation/30_Contributor_doc/README.md
new file mode 100644
index 0000000..27d79d1
--- /dev/null
+++ b/documentation/30_Contributor_doc/README.md
@@ -0,0 +1,74 @@
+# 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/)
+
+```
+
+
+
diff --git a/documentation/README.md b/documentation/README.md
new file mode 100644
index 0000000..5b2d03b
--- /dev/null
+++ b/documentation/README.md
@@ -0,0 +1,8 @@
+# Documentation
+
+- [Install documentation](10_Install_doc/)
+- [Developer documentation](30_Contributor_doc/)
+- [QA : URL + online tools](QA-tools.md)
+
+
+
--
GitLab