Skip to content

Latest commit

 

History

History
239 lines (158 loc) · 14.2 KB

CONTRIBUTING.md

File metadata and controls

239 lines (158 loc) · 14.2 KB
Raw

Pré-requis

Pour contribuer au site lescastcodeurs.com vous aurez tout d’abord besoin de Git. La page d’aide de GitHub est un bon point de départ, le blog d’Emmanuel sur les trucs et astuces de Git est utile également.

Vous aurez aussi besoin de Jekyll. Pour son installation, référez-vous à sa documentation officielle et suivez la procédure en fonction de votre système d’exploitation.

Pour les habitués la procédure est la suivante une fois Ruby 3.3+, RubyGems, et GCC / Make (pour les gems natives) installés :

gem install bundler

Mettre à jour lescastcodeurs.com

Pour mettre à jour lescastcodeurs.com vous devez :

  1. Faire un fork du dépôt de code
  2. Apporter vos modifications
  3. Proposer une pull-request au mainteneur du dépôt

Si les modifications que vous comptez apporter sont d’ampleur pensez à prévenir au préalable le mainteneur par un ticket GitHub ou par mail pour lui demander son avis.

Faire un fork du dépôt de code

Si vous ne savez pas comment faire, jetez un coup d’œil à la documentation de GitHub sur le sujet. Ensuite récupérez les sources de lescastcodeurs.com et créez une nouvelle branche :

git clone git@github.com:<your-github-username>/lescastcodeurs.com.git

cd lescastcodeurs.com
git checkout -b ma-branche

Apporter vos modifications

Quand vous aurez récupéré les sources et créé votre branche de développement, lancez les commandes suivantes à partir de la racine du dépôt :

./bin/serve

Apportez ensuite vos modifications et prévisualisez-les au fur et à mesure dans votre navigateur.

Les modifications de contenu (ajout, modification ou suppression de page) et les modifications de CSS sont automatiquement détectées. lescastcodeurs.com est alors automatiquement reconstruit et les pages ouvertes dans votre navigateur sont automatiquement rafraichies. À noter que le rechargement automatique ne fonctionne pas si vous êtes sur une page 404.

Les modifications de layout nécessitent un rechargement manuel de la page. Et les modifications de configuration (i.e. du fichier _config.yml) nécessitent un redémarrage du site.

Si pour une raison quelconque vos changements ne sont pas visibles, redémarrez à l’aide de ./bin/serve.

Proposer une pull-request au mainteneur du dépôt

Encore une fois si vous ne savez pas comment faire, jetez un coup d’œil à la documentation de GitHub sur le sujet.

Procédures

Construire le site

Pour construire le site exécuter :

./bin/build

Le site est alors disponible dans le répertoire _site.

Publier le site

La publication du site passe par l’exécution du workflow GitHub Actions deploy. Ce workflow décompose globalement de la manière suivante :

  1. Préparation de l’environnement (ruby, configuration SSH nécessaire pour le rsync)
  2. Construction du site à l’aide de bin/build
  3. Déploiement du site à l’aide de bin/deploy (rsync)

Pour fonctionner ce workflow GitHub Actions nécessite la déclaration des secrets suivants :

  • DEPLOY_USER (obligatoire) : indique l’utilisateur SSH à utiliser pour la publication du site,
  • DEPLOY_KEY (obligatoire) : contient la clé SSH privée utilisée pour la connexion au serveur,
  • DEPLOY_HOST (obligatoire) : indique le serveur sur lequel le site doit être publié,
  • DEPLOY_PORT (obligatoire) : indique le port SSH du serveur sur lequel le site doit être publié,
  • DEPLOY_TARGET (obligatoire) : indique le répertoire cible sur le serveur où les fichiers du site seront copiés,
  • DEPLOY_OPTIONS (optionnel) : indique les options additionnelles à passer à rsync.

Il est aussi possible de lancer manuellement la publication du site :

./bin/build && ./bin/deploy

Le script bin/deploy utilise les variables DEPLOY_* si elles sont définies. Si elles ne le sont pas des valeurs par défaut sont utilisées (cf. bin/deploy).

Mise à jour des dépendances

La mise à jour de l'ensemble des dépendances du site passe par le script update-dependencies. Pour l'utiliser, exécuter :

./bin/update-dependencies

Une fois cela fait il ne reste plus qu’à tester que le site fonctionne bien puis commiter le tout, généralement en séparant le type de mise à jour (Jekyll, Bootstrap...).

Quelques petites choses doivent de plus être connus en fonction du type de dépendances.

Paquets Ruby

Les dépendances Ruby sont décrites dans le fichier Gemfile. Le script update-dependencies met à jour les paquets en fonction de ce fichier.

Généralement les mises à jour majeures doivent être appliquées à la main en modifiant le Gemfile. Une fois ces mises à jour terminées pensez à relancer update-dependencies pour mettre à jour le Gemfile.lock.

CSS et JS

Les dépendances CSS et JS sont hébergées dans le répertoire assets pour des problématiques liées à la RGPD (cf. #95). Le script update-dependencies met à jour ces dépendances en fonction d'informations renseignées dans le script lui-même.

Généralement toutes les mises à jour se font automatiquement, à l'exception des mises à jour pouvant nuire au fonctionnement du site (Bootstrap). Ces mises à jour doivent être appliquées à la main en modifiant le script update-dependencies.

Ruby

La version de Ruby recommandée et utilisée pour construire le site doit être mise à jour entièrement à la main :

  1. Mettre à jour le paragraphe Pré-requis de ce guide de contribution,
  2. Mettre à jour la tâche Setup ruby dans le workflow de déploiement.

Les versions de Ruby utilisables dépendent de Jekyll. On utilisera a minima une version encore maintenue.

Suivi des mises à jour

Que la mise à jour soit en grande partie automatique ou manuelle, pour appliquer les mises à jour il faut déjà que vous soyez au courant qu'elles existent. Pour cela plusieurs moyens :

Ajouter un membre à l’équipe

Ajouter le fichier dans _team.

Les propriétés du fichier sont les suivantes :

  • name : le nom, par exemple Emmanuel Bernard
  • gravatar_hash : le md5 de l’email utilisé pour gravatar c-a-d md5sum mon.email@domain.com => 1fc6aa04011b2f0f9721df913b0fd415
  • blog : lien vers le blog (optionnel)
  • website : lien vers le site web (optionnel)
  • twitter : nom d’utilisateur twitter (optionnel)

Lancement de lescastcodeurs.com en mode production

Vous pouvez activer le mode production à l’aide de la variable JEKYLL_ENV="production" ou en utilisant le script serve :

./bin/serve --prod

Suite au retrait de Google Analytics et de Disqus (voir #95), le mode production est identique au mode development.

Notes et recommandations

Et pourquoi pas GitHub pages ?

Cette question s’est posée lors de la migration de lescastcodeurs.com vers Jekyll (cf. #35). Il a été décidé de ne pas héberger lescastcodeurs.com sur GitHub Pages dans le but de pouvoir conserver les règles htaccess actuellement en place.

Si un jour l’hébergement sur GitHub Page est souhaité il faudra bien faire attention à la version de Jekyll utilisée. En effet lescastcodeurs.com utilise, au 18/11/2020, Jekyll 4.1 alors que GitHub Page fonctionne encore avec Jekyll 3.9 (mais a priori rien n’empêche lescastcodeurs.com de fonctionner avec Jekyll 3.9).

Les plugins utilisés par lescastcodeurs.com

jekyll-feed n’est pas utilisé, car l’ajout d’enclosure, nécessaire pour les posts relatifs aux épisodes, n’est pas supporté. Le template utilisé dans le plugin a néanmoins servi de base pour celui du site.

De la bonne utilisation des plugins Jekyll

Dans la mesure du possible n’utilisez que des plugins Jekyll officiels. et supportés par GitHub Pages. Les plugins fournis par la communauté ont tendance à être très lent à se mettre à jour ( Jekyll 4, qui est pourtant sorti le 20/08/2019, n’est au 17/11/2020 toujours pas supporté par certains des plugins les plus populaires) ou pire encore à n’être plus maintenu du tout au bout d’un certain temps.

De la bonne utilisation des liens

Pour créer des liens vers des pages, posts, images ou tout autre fichier présent dans ce dépôt de code préférez l’utilisation de tags link ou post_url à celle des filtres relative_url ou absolute_url. L’utilisation de ces tags est plus concise que celle des filtres, et surtout quand on utilise les tags les liens sont validés et Jekyll ne build pas si la ressource n’est pas trouvée. Cette recommandation ne s’applique pas aux liens externes ou au contenu généré (flux RSS, feuille de style...).

Notes sur l’intégration de Bootstrap

Dans le but de faciliter les mises à jour de Bootstrap / JQuery le choix a été fait d’utiliser le CDN cdn.jsdelivr.net. On utilise : bootstrap.min.css pour la partie CSS, mais aussi bootstrap.bundle.min.js et jquery.slim.min.js qui sont nécessaires pour le collapse de la barre de menu.

Ce type d’intégration a été choisi car :

  • La mise à jour de Bootstrap / JQuery via bundler n’était pas possible sans utiliser jekyll-assets. Hors ce plugin ne supporte pas Jekyll 4 (et n’est pas compatible avec GitHub Pages).
  • L’utilisation des SCSS aurait nécessité l’utilisation de Autoprefixer (depuis a priori Bootstrap 4).
  • On souhaitait s’épargner le téléchargement et la recopie manuelle des fichiers JS / CSS de Bootstrap / JQuery à chaque mise à jour.

Notes sur l’intégration de Simple-Jekyll-Search

La configuration de Simple-Jekyll-Search est directement dans le layout search.html.

L’index de recherche est créé grâce au templates search.json :

  • L’intégralité du contenu des articles est présent dans l’index : la taille du fichier généré n’est en effet que de ~ 750 KO pour 265 posts (et 250 KO si gzippé). Bref pas grand-chose avec les connexions actuelles ou par rapport à une simple image.
  • Les retours chariots n’ont pas été supprimés (strip_newlines) de l’extrait (car il est affiché sur la page de recherche) ni du contenu (par sécurité). Quand on les supprime des mots sont en effet "fusionnés" (par exemple Maxime\nCriteo -> MaximeCriteo). Il n’est pas certain que ça dérange Simple-Jekyll-Search lors de la recherche, mais bon...

Todo

  • keep video directory
  • trouver un moyen de traduire les titres des pages "paginées" (pas faisable avec jekyll-paginate ?)
  • trouver une liste de termes à exclure pour tenter d’améliorer la recherche avec Simple-Jekyll-Search.
  • remove todo :)