Github.com

Pour pouvoir gérer un projet sur ce site, il faut avoir un utilisateur (le bouton « Sign up » de la page d’acucueil permet d’obtenir un compte utilisateur très facilement).

L’objectif d’utiliser ce site est donc de faciliter la contribution à la documentation grâce à l’éditeur en ligne et au système de « Pull Request » et de déclencher simplement la regénération des documentations grâce au lien automatique avec readthedocs.org.

Créer un projet

Public(s) concerné(s) : Administrateur de projet openMairie.

Il s’agit ici, de créer un nouveau repository sur github.com dans l’organisation openmairie. Le projet doit s’appeler openlogiciel-documentation (par exemple pour le logiciel openElec « openelec-documentation » et pour le logiciel openRésultat « openresultat-documentation »). Ne rien faire d’autre dans ce repository.

Depuis le tableau de bord de github.com, un clic sur le bouton « + » puis « New repository » en haut à droite de l’écran, à côté du login de l’utilisateur, permet d’accéder au formulaire de création d’un dépôt.

Voici les informations à saisir :

  • Owner : sélectionner « openmairie », pour une meilleure lisibilité du projet tous les dépôts doivent être créés dans cette organisation.
  • Repository name : le nom doit être logiciel-documentation sans accents sans espaces en minuscules (par exemple pour le logiciel openElec « openelec-documentation » et pour le logiciel openRésultat « openresultat-documentation »).
  • Description : pour que le dépôt sorte correctement dans les recherches, il faut saisir « Documentation Logiciel Sphinx » (par exemple pour openCimetière « Documentation openCimetière Sphinx »).
  • Public ou Private : sélectionner « Public » puisque les projets openMairie sont publics.
  • Initialize this repository with a README : ne pas cocher la case.

Puis il suffit de cliquer sur le bouton « Create repository ».

Importer la documentation depuis un projet subversion de l’adullact

Public(s) concerné(s) : Administrateur de projet openMairie.

Les pré-requis sont :

  • le projet doit déjà être créé sur github.com
  • être dans un terminal pour saisir les commandes suivantes
  • les commandes : svn, svn2git et git doivent être installées

Étape 0 : Modifier et définir les variables utilisées dans les commandes suivantes

export OLDPRODUCTNAME="openfoncier"
export NEWPRODUCTNAME="openads"
export ADULLACTUSER="fmichon"

Étape 1 : Récupération des logs

mkdir -p ${NEWPRODUCTNAME}-documentation/${NEWPRODUCTNAME}-documentation && cd ${NEWPRODUCTNAME}-documentation/${NEWPRODUCTNAME}-documentation
svn log -q svn://scm.adullact.net/scmrepos/svn/${OLDPRODUCTNAME}/documentation > ../LOG
cat ../LOG | awk -F '|' '/^r/ {sub("^ ", "", $2); sub(" $", "", $2); print $2" = "$2" <"$2">"}' | sort -u > ../authors-transform.txt
cat ../authors-transform.txt

Étape 2 : MANUEL - Modification des auteurs

=> Il faut faire la correspondance entre les utilisateurs de l'adullact et ceux de github
=> exemple : fmichon = Florent Michon <fmichon@atreal.fr>
=> fmichon = login de l'addulact
=> Florent Michon = nom complet du contributeur
=> fmichon@atreal.fr = mail référencé dans github
vim ../authors-transform.txt

Étape 3 : Vérification de l’intervalle

export REVS="$(tail -n2 ../LOG|head -n1|awk '{print $1}'|sed "s/r//"):$(head -n2 ../LOG|tail -n1|awk '{print $1}'|sed "s/r//")"
echo $REVS

Étape 4 : Récupération de tous les commits (très long)

svn2git --authors ../authors-transform.txt --revision $REVS -v svn://scm.adullact.net/scmrepos/svn/${OLDPRODUCTNAME}/documentation

Étape 5 : Import du code sur github

git remote add origin git@github.com:openmairie/${NEWPRODUCTNAME}-documentation.git
git push -u --all
git push --tags

Étape 6 : Suppression de l’ancien dépôt de documentation sur l’adullact pour que personne ne committe dessus

svn del -m "Déplacement de la documentation vers Github" svn+ssh://${ADULLACTUSER}@scm.adullact.net/scmrepos/svn/${OLDPRODUCTNAME}/documentation/trunk svn+ssh://${ADULLACTUSER}@scm.adullact.net/scmrepos/svn/${OLDPRODUCTNAME}/documentation/branches
echo "Documentation déplacée vers https://github.com/openmairie/${NEWPRODUCTNAME}-documentation" > ../MOVED-TO-GITHUB.txt
svn import -m "Déplacement de la documentation vers Github" ../MOVED-TO-GITHUB.txt svn+ssh://${ADULLACTUSER}@scm.adullact.net/scmrepos/svn/${OLDPRODUCTNAME}/documentation/MOVED-TO-GITHUB.txt

Faire l’import initial d’un projet sphinx

Public(s) concerné(s) : Administrateur de projet openMairie.

Contribuer à une documentation

Public(s) concerné(s) : Contributeur membre du projet openMairie.