CONTRIBUTING.md

Améliorer le site public de l'Incubateur

Ajouter une Startup

En un clic par l'interface web de GitHub 😃

Les logos doivent être carrés et de préférence à une résolution supérieure à 512 ⨉ 512 pixels. Les illustrations doivent être en 16:9, et à une résolution supérieure à 1280 ⨉ 720 pixels.

Sinon, offline : dupliquer un fichier de description dans le dossier _startup et suivre les instruction ci-dessous sur l'édition.

Pour le titre de la startup, s'en tenir aux règles usuelles, c'est-à-dire sauf cas particuliers : le premier mot prend une majsucule, les autres non. (Ce n'est pas grave de se tromper, mais il faut s'attendre à ce que ça soit corrigé plus tard.)

Pour l'énoncé de mission, utiliser une phrase à l'infinitif, qui complète « En investissant dans ce produit, l'État cherche à… » ou « l'État cherche à rendre plus facile de… ».

Éditer la description d'une Startup existante

Modifier le fichier $id_startup.md de description de la Startup dans le dossier _startup.

La documentation des différentes propriétés à renseigner est accessible en cliquant sur le lien de création d'une nouvelle Startup dans la section précédente.

Publier un billet

1. Écrire le billet

En un clic par l'interface web de GitHub 😃

Pour ajouter une image au billet, créer un fichier JPEG dans img/posts du même nom que le fichier contenant le post (donc par exemple AAAA-MM-DD-titre.jpg). À l'affichage, l'image sera redimensionnée : les dimensions exactes de l'image ont donc peu d'importance.

Sinon, offline : créer un nouveau post dans le dossier _posts.

2. Faire revoir le billet

Avant d'ouvrir une pull request, diffuser un lien privé de prévisualisation à [email protected].

Par exemple, créer un Gist privé.

Recueillez l'avis d'au moins 2 membres de l'incubateur. Après de potentielles itérations, si aucun des destinataires n'a posé de véto à la publication, l'auteur peut ouvrir une pull request pour dernières vérifications syntaxiques et fonctionnelles.

Ajouter un événement

En un clic par l'interface web de GitHub 😃

Un événement est un type de billet particulier. Il a donc quelques métadonnées supplémentaires (start, end…), mais est équivalent pour le reste, dont l'ajout d'images et la création offline.

Notamment, attention, la date dans le nom du fichier au format AAAA-MM-DD-nom_evenement.md est la date à laquelle vous souhaitez que l'événement soit annoncé sur le site (et non la date de l'événement lui-même).

Ajouter un membre à l'équipe Incubateur

En un clic par l'interface web de GitHub 😃

Attention, l'image doit être carrée et de préférence à une résolution supérieure à 512 ⨉ 512 pixels.

Le nom du fichier est important : il doit correspondre au nom de la personne, selon le schéma prenom.nom. Les parties prenom et nom sont en minuscules et sans accents. Les espaces des noms propres sont remplacés par _ et les tirets restent. Rien de très important ne dépend du respect de ces conventions, par contre il est important que cet identifiant et celui du mail @beta.gouv.fr correspondent. Cela nous permet de traiter automatiquement divers sujets liés à la gestion RH tels que abonnement et désabonnement des listes de diffusion, anticipation des fins de contrat, etc.

Sinon, offline : créer un nouveau fichier de description dans le dossier _authors et renseigner les informations en prenant exemple sur un fichier de description existant déjà dans ce dossier.

Modifier le contenu éditorial

Rechercher le contenu à modifier et éditer le fichier correspondant.

Modifier les startups mises en avant sur la page d'accueil

Mettre à jour la propriété featured de la phase correspondante pour référencer le nom du fichier dans lequel la startup à mettre en avant est décrite dans index.html.

Modifier la présentation du site

Ce site est construit avec Jekyll, un générateur de sites statiques. La version utilisée est celle actuellement en production sur GitHub Pages.

Pour l'améliorer, installer Ruby et Jekyll dans leurs versions de production :

git clone https://github.com/sgmap/beta.gouv.fr.git
cd beta.gouv.fr
gem install bundler --no-ri --no-rdoc
bundle install
bundle exec jekyll serve

Les fichiers pertinents pour une modification de la présentation sont probablement dans les dossiers _layouts et css.

Dépendances : un Gemfile particulier

Afin de minimiser les écarts entre les versions de développement et les versions de production, ce dépôt contient un fichier Gemfile (spécification des versions minimum des dépendances), comme beaucoup de dépôts Ruby. Ce fichier Gemfile a par ailleurs un fonctionnement un peu particulier : lorsque c'est possible, il obtient sur le site de Github le numéro de version de Github Pages le plus récent, et tente de mettre à jour les dépendances.

Modifier le logo

La source du logo est dans le répertoire _sources. Il s'agit d'un SVG contenant du texte. Pour le rendre accessible à tous les utilisateurs, il importe de le transformer en un SVG contenant des path.

Cela peut être fait à la ligne de commande avec Inkscape :

inkscape --export-text-to-path `pwd`/_sources/logo.svg -l `pwd`/img/logo.svg
svgo --multipass img/logo.svg  # optimisation, cf. https://jakearchibald.github.io/svgomg/

Déploiement

Prévisualisation (staging)

Chaque pull request est déployée dans Heroku, une fois le build passé. Une notification est envoyée sur la pull request :

Vous pouvez suivre le lien de la notification pour accéder à la version de l'application correspondant à la pull request.

Production

Ce site est déployé en continu avec Github Pages. La branche qui reflète la production est master.

Pousser sur master, c’est partager avec le monde… ce qui signifie donc qu'il faut être très prudent avec ce pouvoir et privilégier l'usage de pull requests 😉

C'est pourquoi la branche master est protégée : il est impossible de mettre en production sans que les tests automatisés n'aient validé que le site pouvait être généré correctement et qu'au moins un pair humain ait revu les modifications proposées.