lifen-ruby-style 0.2.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: effc68d9ce8a6e338df992ce1144e24026ad90ea7bbf0762eb29385fe84f5eee
-  data.tar.gz: f3ffb929dfdff48ede8b10aacc691446734ff7ee56d43af2e65810f732682500
+  metadata.gz: f1f86ee33406608d1b9b2cf8d14d80585a09dcb798a2528c1b06a7205d61bb47
+  data.tar.gz: 42914e1c8155e225d5fcedce3d9d14ef8d5116b51df50213cd24f899aca039c8
 SHA512:
-  metadata.gz: 43fee525fe66c4b4047773346e13470d5db00421502e5f830945af58a8c8e1b5de83cc991ba3c47ccb888003d0fbd0a38b50770c828312f8ae1619ff3777437c
-  data.tar.gz: 6f1af839efdfd60fe409f0910822d50051347078b6e2267653a2093822e5d6c5c0aa863f994c0f14c824d7fde30034a75cabc989ccc632f23d5eb6cf366561bb
+  metadata.gz: b86279d1645d36567b71689f3f5b634086975cf0be3f0f29436da8ff9171d3739df1017aa21b8f4323ff423dab23410b315cbb12f11008a081fa9e6e31d3dadc
+  data.tar.gz: 28df7786610a74fe2b4bdc7534409f857962020002c7bce2271c18dfd10bf717e25ddaf0d4f3bfcf1785d2430f36feb4cf80ed700585ce812180fc2c3943ce4e

data/.overcommit.yml

@@ -0,0 +1,55 @@
+# Use this file to configure the Overcommit hooks you wish to use. This will
+# extend the default configuration defined in:
+# https://github.com/sds/overcommit/blob/master/config/default.yml
+#
+# At the topmost level of this YAML file is a key representing type of hook
+# being run (e.g. pre-commit, commit-msg, etc.). Within each type you can
+# customize each hook, such as whether to only run it on certain files (via
+# `include`), whether to only display output if it fails (via `quiet`), etc.
+#
+# For a complete list of hooks, see:
+# https://github.com/sds/overcommit/tree/master/lib/overcommit/hook
+#
+# For a complete list of options that you can use to customize hooks, see:
+# https://github.com/sds/overcommit#configuration
+#
+# Uncomment the following lines to make the configuration take effect.
+
+PreCommit:
+  Pronto:
+    enabled: true
+
+  GoFmt:
+    enabled: false
+
+CommitMsg:
+  CapitalizedSubject:
+    enabled: false
+
+  SingleLineSubject:
+    enabled: true
+    on_warn: fail
+
+  TextWidth:
+    enabled: true
+    on_warn: fail
+
+  TrailingPeriod:
+    enabled: true
+    on_warn: fail
+#PreCommit:
+#  RuboCop:
+#    enabled: true
+#    on_warn: fail # Treat all warnings as failures
+#
+#  TrailingWhitespace:
+#    enabled: true
+#    exclude:
+#      - '**/db/structure.sql' # Ignore trailing whitespace in generated files
+#
+#PostCheckout:
+#  ALL: # Special hook name that customizes all hooks of this type
+#    quiet: true # Change all post-checkout hooks to only display output on failure
+#
+#  IndexTags:
+#    enabled: true # Generate a tags file with `ctags` each time HEAD changes

data/.rubocop.yml

@@ -1 +1 @@
-inherit_from: default.yml
+inherit_from: default_rubocop.yml

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify dependencies in percy-style.gemspec

data/README.md

@@ -1,10 +1,40 @@
 # lifen-ruby-style
 
-Configuration de Rubocop chez Lifen.
+**Ensembe des outils et bonnes pratiques Ruby chez Lifen :**
+
+1. Le [Guide de style Lifen](./style_guide.md) présente les guidelines Lifen et détaille les règles de style.
+
+2. [RuboCop](https://github.com/rubocop-hq/rubocop) est un outil statique d'analyse et de formattage du code, qui repose sur le [guide de style](https://github.com/rubocop-hq/ruby-style-guide) de la communauté Ruby et que nous configurons selon le [guide de style Lifen](./style_guide.md). Nous utilisons plusieurs extensions :
+
+   - [Rubocop-performance](https://github.com/rubocop-hq/rubocop-performance) pour la performance et l'optimisation
+   - [Rubocop-rspec](https://github.com/rubocop-hq/rubocop-rspec) pour l'analyse des tests RSpec
+   - [Rubocop-rails](https://github.com/rubocop-hq/rubocop-rails) pour les vérifications spécifiques à Rails.
+
+3. [Pronto](https://github.com/prontolabs/pronto) permet de lancer simultanément **plusieurs outils d'analyse** (e.g. Rubocop, Reek, Fasterer) **sur un sous-ensemble de lignes** (e.g. le contenu de l'index ou le diff entre 2 commits). Nous ne l'utilisons pour le moment que pour l'analyse Rubocop. [Pronto Rubocop](https://github.com/prontolabs/pronto-rubocop) est l'extension qui va permettre de lancer RuboCop via Pronto.
+
+4. [Overcommit](https://github.com/sds/overcommit) permet de gérer et paramétrer les hooks Git.
+
+## Sommaire
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Rubocop](#rubocop)
+  - [Pronto](#pronto)
+  - [Overcommit](#overcommit)
+- [Utilisation d'une version locale](#utilisation-dune-version-locale)
+- [Contributions](#contributions)
+- [TODO](#todo)
+- [Archives](#archives)
 
 ## Installation
 
-Il suffit d'ajouter dans le `Gemfile` :
+<details>
+
+<summary>Pour un nouveau projet ou un repo Lifen non configuré</summary>
+
+### 1. Ajout de la gem au projet
+
+Ajouter dans le `Gemfile` :
 
 ```ruby
 group :test, :development do
@@ -18,67 +48,364 @@ Ou dans le `.gemspec` s'il s'agit d'une gem :
 spec.add_development_dependency 'lifen-ruby-style'
 ```
 
-Puis :
+### 2. Config Rubocop
+
+Créer le fichier `.rubocop.yml` avec le code suivant :
+
+```yaml
+inherit_gem:
+  lifen-ruby-style:
+    - default_rubocop.yml
+```
+
+### 3. Config Overcommit
+
+Créer le fichier `.overcommit.yml` à partir du contenu de [ce fichier](./default_overcommit.yml).
+
+Note : Il n'est pas nécessaire d'ajouter Rubocop dans les dépendances de l'application.
+
+</details>
+
+<details>
+<summary>Pour un repo Lifen déjà configuré</summary>
+
+### 1. Installer les dépendences :
 
 ```bash
 $ bundle install
 ```
 
-Il faut enfin créer le fichier `.rubocop.yml` avec le code suivant :
+En cas de problème avec l'installation de la sous-dépendance `rugged` il faudra vous assurer que `cmake` est installé sur votre machine. Si elle n'est pas installée il faudra le faire de la façon suivante :
+```bash
+brew install cmake
+```
 
-```yaml
-inherit_gem:
-  lifen-ruby-style:
-    - default.yml
+### 2. Installer les hooks Git :
+
+```bash
+$ bundle exec overcommit --install
 ```
 
-Il n'est pas nécessaire d'ajouter Rubocop dans les dépendances de l'application.
+</details>
 
-Il faut ensuite ajouter un "hook" git en créant le fichier `.git/hooks/pre-commit` avec :
+<details>
+<summary>Recommandations spécifiques pour VSCode</summary>
 
+### 1. Configuration générale
+
+```json
+  "editor.tabSize": 2,                  // Uses 2 spaces for indentation
+  "editor.rulers": [
+    80,
+    120
+  ],                                    // Add rulers at 80 and 120 characters
+  "files.trimTrailingWhitespace": true, // Remove trailing auto inserted whitespaces
+  "files.insertFinalNewline": true,     // Insert a final new line at the end of the file when saving it
+  "files.associations": {
+    "Gemfile": "ruby",
+  },                                    // Use Ruby language mode for Gemfiles
 ```
-#!/bin/bash
 
-git status -s | grep -E 'A|M' | awk '{print $2}' | xargs rubocop --display-cop-names --extra-details --parallel --force-exclusion
+### 2. Extension ruby
+
+- Installer l'extension [rebornix.ruby](https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby), qui intègre notamment `RuboCop`.
+
+  Note : Inutile d'installer [ruby-rubocop](https://marketplace.visualstudio.com/items?itemName=misogi.ruby-rubocop) qui fait doublon et qui introduit des conflits avec les environnement `rvm`.
+
+- Paramétrage recommandé de l'extension :
+
+  ```json
+    "ruby.useBundler": true,              // run non-lint commands with bundle exec
+    "ruby.useLanguageServer": true,       // use the internal language server (see below)
+    "ruby.lint": {
+      "rubocop": {
+        "useBundler": true                // enable rubocop via bundler
+      }
+    },
+    "ruby.format": "rubocop",             // use rubocop for formatting
+  ```
+
+- **FORCER RUBOCOP À RESPECTER LES EXCLUSIONS DÉFINIES DANS LE FICHIER DE PARAMÉTRAGE :**
+
+  ```bash
+  $ echo '--force-exclusion' > .rubocop
+  ```
+
+- Paramétrage recommandé pour l'auto-formatting :
+
+  ```json
+    "[ruby]": {
+      "editor.formatOnPaste": true,       // auto-format ruby code when pasting
+      "editor.formatOnSave": true         // auto-format ruby code when saving
+    },
+  ```
+
+  ou
+
+  ```json
+    "editor.formatOnPaste": true,  // auto-format code when pasting
+    "editor.formatOnSave": true,   // auto-format code when saving
+  ```
+
+### 3. Bonus - Autres extensions utiles :
+
+- [Bracket Pair Colorizer 2](https://marketplace.visualstudio.com/items?itemName=CoenraadS.bracket-pair-colorizer-2)
+- [Endwise](https://marketplace.visualstudio.com/items?itemName=kaiwood.endwise)
+- [Git Blame](https://marketplace.visualstudio.com/items?itemName=waderyan.gitblame)
+- [Rails Go to Spec ](https://marketplace.visualstudio.com/items?itemName=sporto.rails-go-to-spec)
+- [RSpec Snippets](https://marketplace.visualstudio.com/items?itemName=karunamurti.rspec-snippets)
+
+</details>
+
+<details>
+<summary>Recommandations spécifiques pour Sublime Text</summary>
+
+### Configuration de Sublime Text
+Il faut aller dans `Preferences > Settings` et modifier le fichier `Preferences.sublime-settings -- User` et y ajouter les paramètres suivants :
+```json
+{
+  ...,
+  "rulers":
+	[
+		80,
+		120
+	],
+	"tab_size": 2,
+	"translate_tabs_to_spaces": true,
+	"trim_trailing_white_space_on_save": true,
+	"word_wrap": "true",
+  ...
+}
+```
+
+### Configuration de Rubocop
+#### 1. Installation du plugin
+Il faut installer l'extension [sublime_rubocop](https://packagecontrol.io/packages/RuboCop)
+
+Et tout devrait marcher par défaut si votre système n'utilise pas rvm ou rbenv. Le cas échéant il faut personnaliser la configuration en allant dans `Preferences > Package Settings > Rubocop > Settings - User` et mettre la configuration qui va bien dans le fichier, par exemple ceci si vous utilisez Rbenv :
 ```
+{
+    "check_for_rvm": false,
+    "check_for_rbenv": true,
+    "rbenv_path": "/usr/local/bin/rbenv"
+}
+```
+
+#### 2. Utilisation
+Une fois le plugin installé vous accéderez à des commandes supplémentaires liées à Rubocop et vous pourrez par exemple :
+- Corriger automatiquement des fichiers
+- Activer/Désactiver l'auto-check des fichiers
+
+</details>
+
+<details>
+<summary>Recommandations spécifiques pour VIM (`dense-analysis/ale`)</summary>
+
+### 1. Installation
+
+#### via Plug (recommandé)
+
+- Ajoutez à votre `.vimrc` (dans la liste des plugins):
+
+  ```
+  Plug 'dense-analysis/ale'
+  ```
+
+- Lancez `:PlugInstall`
+
+#### Autres méthodes
+
+Voir https://github.com/dense-analysis/ale#3-installation
+
+### 2. Configuration recommandée
+
+Dans votre `.vimrc`:
+
+- Pour que le linter passe lorsque le texte change (hors sauvegardes):
+
+  ```
+  let g:ale_lint_on_text_changed = 'never'
+  ```
+
+- Pour que le linter passe lorsque la touche 'enter' est pressée:
+
+  ```
+  let g:ale_lint_on_enter = 1
+  ```
+
+- Pour que le linter nettoie les petites imperfections à la sauvegarde:
+  ```
+  let g:ale_fix_on_save = 1
+  let g:ale_fixers = {
+  \  'ruby': 'rubocop',
+  \  'javascript': 'eslint'
+  \}
+  ```
+  (il faut aussi configurer les "fixers")
+
+### Pour aller plus loin
+
+https://github.com/dense-analysis/ale
+
+</details>
 
 ## Usage
 
-### En local
+### Workflow
 
-Lancement de Rubocop pour vérifier :
+- Je code ma feature en local. Mon environnement (projet + IDE) étant configuré, je suis alerté en direct des règles de style que j'enfreins. Certaines sont mêmes corrigées automatiquement, lors de la sauvegarde du fichier.
+- Je commit :
+  - Un hook de pre-commit lance une analyse Pronto (= RuboCop pour le moment) sur les lignes "staged". D'autres vérifications fournies par défaut par la gem `overcommit` sont également faites. Si l'analye renvoie des erreurs, le commit est bloqué.
+  - Un hook vérifie le message de commit
+  - Si je veux bypasser les hooks (déconseillé) : `OVERCOMMIT_DISABLE=1 git commit ...`
+- Je push (pas de hooks paramétrés pour l'instant)
+
+### Commandes Rubocop
+
+Pour de la vérification :
 
 ```bash
-$ bundle exec rubocop
+$ bundle exec rubocop             # checks all the repo
+$ bundle exec rubocop [PATH]      # checks the path
+$ bundle exec rubocop --fail-fast # inspect files in order of modification time and stop after the first file
 ```
 
-Lancement de Rubocop pour corriger automatiquement :
+Pour de la correction automatique :
 
 ```bash
-$ bundle exec rubocop -a
+$ bundle exec rubocop -a                  # auto-correct offenses.
+$ bundle exec rubocop --safe              # run only safe cops.
+$ bundle exec rubocop --safe-auto-correct # run auto-correct only when it's safe.
+$ bundle exec rubocop --lint              # run only lint cops.
+$ bundle exec rubocop --fix-layout        # run only layout cops, with auto-correct on.
 ```
 
-### Sur CircleCI
+Liste des commandes disponibles :
 
-Il suffit d'ajouter dans le flow un job avant les tests (ou en parallèles) avec la commande suivante :
+```bash
+$ bundle exec rubocop --help
+```
+
+### Commandes Pronto
 
 ```bash
-git diff-tree -r --no-commit-id --name-status 'origin/develop..HEAD' | grep -E 'A|M' | awk '{print $2}' |  xargs --no-run-if-empty bundle exec rubocop --config .rubocop.yml --force-exclusion --fail-level warn
+$ bundle exec pronto run [PATH]       # Runs Pronto on the diff between last commit and master
 ```
 
-## Evolution des règles
+Vous pouvez ajouter les options suivantes :
+
+```bash
+-c, [--commit=COMMIT]      # Runs Pronto on the diff between last commit and specified commit
+-i, --index                # Analyze changes not staged for commit (does not include untracked files)
+--unstaged, --no-unstaged  # Analyze only untracked files
+--staged, --no-staged      # Analyze changes to be committed (git staging area)
+```
 
-Pour modifier la configuration, le plus simple est de le faire sur un projet en local en modifiant le `Gemfile` :
+Liste des commandes disponibles :
 
-```ruby
-group :development, :test do
-  gem 'lifen-ruby-style', path: '../lifen-ruby-style'
-end
+```bash
+$ bundle exec pronto --help
+$ bundle exec pronto help run
 ```
 
-ainsi que le fichier `.rubocop.yml` :
+### Commandes Overcommit
 
-```yaml
-inherit_from:
-  - ../lifen-ruby-style/default.yml
-```
+```bash
+$ OVERCOMMIT_DISABLE=1 git [command] # Executes the git command without running the hooks
+$ bundle exec overcommit --run                   # Run pre-commit hook against all git tracked files
+```
+
+Liste des commandes disponibles :
+
+```bash
+$ bundle exec overcommit --help
+```
+
+### CI
+
+Créer un flow avec la commande `bundle exec overcommit --run`.
+
+## Utilisation d'une version locale
+
+Pour utiliser une version locale de la gem `lifen-ruby-style` :
+
+- Cloner le repo
+
+  ```bash
+    git clone git@github.com:honestica/lifen-ruby-style.git
+  ```
+
+- Modifier le `Gemfile` de votre projet local (e.g. Alphonse) :
+
+  ```ruby
+  group :development, :test do
+    gem 'lifen-ruby-style', path: '../lifen-ruby-style'
+  end
+  ```
+
+- Modifier le fichier `.rubocop.yml` :
+
+  ```yaml
+  inherit_from:
+    - ../lifen-ruby-style/default_rubocop.yml
+  ```
+
+- Créer le fichier `.overcommit.yml` et coller le contenu du fichier `lifen-ruby-style/default_overcommit.yml`
+
+- Installer les dépendences et les hooks Git :
+
+  ```bash
+  $ bundle install
+  $ bundle exec overcommit --install
+  ```
+
+- Vous pouvez maintenant apporter des modifications à la gem (repo `lifen-ruby-style`) et les visualiser sur votre projet local (e.g. `alphonse`).
+
+**ATTENTION : La configuration d'overcommit n'est pas liée automatiquement au projet, il faut la copier/coller dans le projet cible après avoir effectué des changements.**
+
+## Contributions
+
+Comme pour n'importe quel autre projet :
+
+- cloner le repo
+- créer une nouvelle branche
+- soumettre une PR
+
+Vous allez vouloir tester localement les modifications de règle de style que vous proposez. L'idée est d'utiliser votre version locale de la gem `lifen-ruby-style` sur un projet local (e.g. Alphonse), suivre les instructions pour l'[utilisation d'une version locale](#utilisation-dune-version-locale).
+
+**ATTENTION : La configuration d'overcommit n'est pas liée automatiquement au projet, il faut la copier/coller dans le projet cible après avoir effectué des changements.**
+
+## TODO
+
+[ ] Recommandations spécifiques pour Sublime Text
+[ ] Lier la configuration d'overcommit aux repos
+[ ] Ajouter un hook de pre-push ?
+[ ] Ajouter le hook de pre-commit au CI
+[ ] Ajouter `pronto-faster` si pertinent
+[ ] Ajouter `pronto-reek` si pertinent
+[ ] Ajouter `pronto-slim_lint` si pertinent
+[ ] Ajouter `pronto-scss` si pertinent
+
+## Archives
+
+<details><summary>Ajouter un "hook" git d'exécution de rubocop</summary>
+
+Créer le fichier `.git/hooks/pre-commit` avec :
+
+```bash
+#!/bin/bash
+
+git status -s | grep -E 'A|M' | awk '{print $2}' | xargs rubocop --display-cop-names --extra-details --parallel --force-exclusion
+```
+
+</details>
+
+<details><summary>Ajouter rubocop au CircleCI</summary>
+
+Il suffit d'ajouter dans le flow un job avant les tests (ou en parallèles) avec la commande suivante :
+
+```bash
+git diff-tree -r --no-commit-id --name-status 'origin/develop..HEAD' | grep -E 'A|M' | awk '{print $2}' |  xargs --no-run-if-empty bundle exec rubocop --config .rubocop.yml --force-exclusion --fail-level warn
+```
+
+</details>

data/Rakefile

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'

data/default_overcommit.yml

@@ -0,0 +1,55 @@
+# Use this file to configure the Overcommit hooks you wish to use. This will
+# extend the default configuration defined in:
+# https://github.com/sds/overcommit/blob/master/config/default.yml
+#
+# At the topmost level of this YAML file is a key representing type of hook
+# being run (e.g. pre-commit, commit-msg, etc.). Within each type you can
+# customize each hook, such as whether to only run it on certain files (via
+# `include`), whether to only display output if it fails (via `quiet`), etc.
+#
+# For a complete list of hooks, see:
+# https://github.com/sds/overcommit/tree/master/lib/overcommit/hook
+#
+# For a complete list of options that you can use to customize hooks, see:
+# https://github.com/sds/overcommit#configuration
+#
+# Uncomment the following lines to make the configuration take effect.
+
+PreCommit:
+  Pronto:
+    enabled: true
+
+  GoFmt:
+    enabled: false
+
+CommitMsg:
+  CapitalizedSubject:
+    enabled: false
+
+  SingleLineSubject:
+    enabled: true
+    on_warn: fail
+
+  TextWidth:
+    enabled: true
+    on_warn: fail
+
+  TrailingPeriod:
+    enabled: true
+    on_warn: fail
+#PreCommit:
+#  RuboCop:
+#    enabled: true
+#    on_warn: fail # Treat all warnings as failures
+#
+#  TrailingWhitespace:
+#    enabled: true
+#    exclude:
+#      - '**/db/structure.sql' # Ignore trailing whitespace in generated files
+#
+#PostCheckout:
+#  ALL: # Special hook name that customizes all hooks of this type
+#    quiet: true # Change all post-checkout hooks to only display output on failure
+#
+#  IndexTags:
+#    enabled: true # Generate a tags file with `ctags` each time HEAD changes