nqb / form-debops

Formation DebOps

TODO

• ❏ Section à remplacer par des tickets

• ❏ Mise à jour LICENSE

• ❏ Tester Antora pour la mise à dispotion des documents

• ❏ S’inspirer de software carprentry

• ❏ Mentionner l’endroit où récupérer les livrables directement la documentation (homepage)

• ❏ Revoir utilisation de la template

Organisation du dépôt

Répertoires :

• formateur : document formateur

• apprenant : document apprenant

• source : source du document

• codes : codes sources utilisés dans la formation

• modeles : modèles de documents

Pour modifier le contenu, il suffit de modifier les fichiers dans le répertoire source.

Le document formateur est identique au document apprenant mais il contient les corrigés.

Cours et foire aux questions

La rédaction d’un cours et d’une foire aux questions peuvent se faire directement dans le dossier source.

Environnement et travaux pratiques

Environnement

Les travaux pratiques doivent pouvoir s’exécuter dans un environnement reproductible. Cet environnement fait partie du dépôt et se trouve à la racine pour simplifier sa mise en place.

Le formateur se sert de cet environnement pour préparer, revoir et faire évoluer la formation. Le répertoire codes est forcément monté pour le formateur. Pour les apprenants, ce n’est pas nécessaire.

Idéalement, cet environnement est intégré à un système d’intégration continue pour tester l’ensemble des codes de façon automatique.

Travaux pratiques

Les travaux pratiques impliquent l’utilisation des répertoires formateur et apprenant pour afficher/masquer les corrigés des travaux.

Livrables pour les apprenants

L’accès au dépôt contenant le code source de la formation est toujours public.

Le code source de la formation est géré comme un logiciel : il y a des versions avec un ChangeLog associé et des livrables. Ceci permet aux apprenants de récupérer en tout temps la dernière version d’une formation.

Les livrables sont : * Cours * Foire aux questions * Travaux pratiques avec les corrigés * Environnement * Codes

Les documents AsciiDoc doivent être accessibles aux formats suivants : * HTML * PDF * ePub

L’environnement et les codes doivent être récupérables dans une archive.

Tous ces liens doivent être mentionnés dans la documentation elle-même et dans ce document.

Création d’une nouvelle formation

1. Créer un nouveau dépôt avec le nom form-nom-logiciel en important le code de form-skel

2. Cloner le dépôt

git clone https://github.com/nqb/form-name.git
cd form-name

# then write, learn, write, learn :-)
# 0. wipe README.asciidoc
# 1. edit formateur/master.asciidoc
# 2. edit source/global_attributes.asciidoc
# 3. start with ebauche.mm

Création d’un nouveau TP

Checkliste :

• ❏ définir le numéro et le nom du TP

  • TP : numero_tp_nom_tp

  • Corrigé : numero_tp_s_nom_tp (s pour solutions)

• ❏ créer le fichier préfixé avec le numéro du TP dans source en se basant sur modeles/exercice.asciidoc

• ❏ créer le corrigé dans source/solutions en se basant sur modeles/corrige.asciidoc

• ❏ créer les codes dans code

Utilisation des codes

Les codes sources utilisés dans la formation se trouvent dans le répertoire codes. Ils doivent être exécutables.

Avec Vagrant

Pour utiliser les codes depuis la machine virtuelle Vagrant livrée avec le projet :

$ vagrant up
[..]
# in the VM
[vagrant@localhost ~]$ /codes/tp1/install-ansible-with-pipsi.sh

Avec Docker

Pour utiliser les codes directement dans un conteneur Docker :

$ docker container run --name $(basename ${PWD}) --volume="${PWD}/codes":/codes -it debian bash
[..]
# in the container
# install dependencies and run:
root@6cd5d887c4c8:/# /codes/tp1/install-ansible-with-pipsi.sh

Revue des documents

Checkliste :

• ❏ changer le prompt PS1="$ \w "

• ❏ mettre à jour la version du logiciel dans global attributes

• ❏ vérifier tous les liens dans les sections Documentation

• ❏ tester tous les codes (kitchen.yml)

Build

Pré-requis

• asciidoctor

• ruby-coderay pour la coloration syntaxique

Génération HTML

make

Usage

Pour l’utilisation de ce dépôt, se référer au squelette de formation.