Flux de travail

Ces instructions supposent que vous disposez déjà d’un compte github et que vous avez également installé Git. Assurez-vous que git est dans votre PATH en exécutant la commande git dans n’importe quel terminal ou cmd et en vérifiant qu’elle ne génère pas d’erreur telle que « commande introuvable ». Si vous n’avez pas installé git, suivez ces instructions.

🔗Documenter des fonctionnalités non documentées

Nous sommes particulièrement intéressés à documenter les pull requests fermées qui nécessitent des ajouts ou des modifications à ce manuel. Les pull requests qui nécessitent de la documentation sont cataloguées avec une étiquette GitHub documentation : en attente.

Les étapes de haut niveau pour y parvenir sont :

  1. Afficher la liste des Pull Requests qui nécessitent de la documentation.

  2. Sélectionnez une Pull Request où vous comprenez ce qui a changé.

  3. Rédigez le changement comme détaillé dans le flux de travail ci-dessous.

  4. Lorsque vous effectuez le Pull Request, incluez un lien vers le Pull Request de l’étape 1.

🔗The documentation workflow

🔗Configuration unique

Si vous n’avez pas déjà configuré git localement, utilisez ces deux commandes pour configurer votre identité avant de valider :

  1. git config --global user.email "vous@exemple.com"

  2. git config --global user.name "Votre Nom"

Et si vous n’avez pas encore authentifié votre instance git locale avec github, suivez les instructions de GitHub CLI ici. Cela garantira que vos clés et informations d’identification sont correctement configurées.

Vous pouvez alors cloner une copie de dtdocs sur votre ordinateur.

  1. Go to https://github.com/darktable-org/dtdocs.

  2. Appuyez sur le bouton Fork puis sur le bouton Create fork.

  3. Vous serez redirigé vers une page avec votre fork de la documentation darktable. Appuyez sur le bouton Code et copiez le lien sous HTTPS.

  4. Ouvrez un terminal ou un cmd dans le répertoire souhaité où résidera le référentiel de documentation darktable. Quelque chose comme « C:\Users\votreUtilisateur\Documents\ » ou « /home/votreUtilisateur/Documents/builds ». Sous Windows et macOS/Linux, vous pouvez utiliser la commande suivante pour accéder au répertoire souhaité : cd C:\Users\votreUtilisateur\Documents\ en remplaçant le répertoire d’exemple par le vôtre.

  5. Clonez le référentiel dtdocs en exécutant : git clone https://github.com/<votre nom d'utilisateur>/dtdocs.git Modifiez l’URL par celle que vous avez copiée à l’étape 3.

  6. Vous disposez désormais d’une copie du référentiel dtdocs sur votre PC. Une configuration supplémentaire suivra avant que vous puissiez commencer à éditer des fichiers.

🔗Syncing changes

  1. Accédez à vos référentiels sur github et sélectionnez votre fork darktable.

  2. Appuyez sur Sync fork.

  3. Ouvrez un terminal ou un cmd dans votre répertoire du dépôt de darktable.

  4. Assurez-vous que vous n’avez aucune modification locale en attente en exécutant git status puis git checkout master (si vous avez suivi ce guide pour la première fois, vous serez déjà sur master).

  5. Exécutez git pull (cela garantit que votre copie locale est à jour avec votre fork sur github).

Alternativement, vous pouvez synchroniser votre fork et votre copie locale via le terminal :

  1. Assurez-vous que vous n’avez aucune modification locale en attente en exécutant git status puis git checkout master.

  2. Vérifiez vos référentiels distants : git remote -v. Vous devriez au moins voir origin (votre fork). Si upstream est manquant, ajoutez-le à l’étape suivante.

  3. Ajoutez le référentiel dtdocs en amont (une seule fois) : git remote add upstream https://github.com/darktable-org/dtdocs.git.

  4. Extrayez l’état actuel du référentiel principal vers votre copie locale : git pull upstream master.

  5. Poussez votre copie locale désormais synchronisée vers votre fork : git push origin master.

🔗Branche, modifier et créer une pull request

  1. Ouvrez un terminal ou un cmd dans votre répertoire de référentiel de documentation darktable.

  2. Exécutez git pull origin master pour obtenir les dernières modifications de GitHub.

  3. Exécutez git checkout -b branch-name et remplacez branch-name par le nom de branche souhaité. Ceci est souvent lié au travail que vous faites. Par exemple, pour ce PR https://github.com/darktable-org/darktable/pull/17589, vous pourriez l’appeler dt-synch-edit-docs.

  4. Faites le travail de documentation.

  5. Vérifiez vos fichiers modifiés avec git status. Si vous avez modifié plus de fichiers que ceux que vous avez l’intention de soumettre, vous pouvez effectuer git restore path/to/file/ pour annuler vos modifications.

  6. Exécutez git add -A. Cela construira l’index de tous les fichiers modifiés.

  7. Exécutez git commit -m "Documentation ajoutée pour blabla blabal". À l’intérieur des « », vous mettrez un petit message sur le travail que vous avez effectué.

  8. Exécutez git push --set-upstream origin branch-name Remplacez branch-name par celle que vous avez choisie préalablement.

  9. Créez votre pull request en suivant les instructions suivantes.

  10. Si vous devez effectuer d’autres corrections dans la branche actuelle, répétez simplement 3-8. Pour la commande de l’étape 3, vous pouvez omettre -b et à l’étape 8, vous pouvez simplement faire git push.

  11. Une fois que vous avez terminé et que votre pull request est fusionnée ou que vous avez terminé votre travail pour cette pull request spécifique, exécutez git checkout master pour revenir à la branche principale. Je recommande de travailler sur une seule branche/pr à la fois si vous ne savez pas comment fonctionne git.

🔗Exécution de hugo localement pour voir les changements

hugo peut également être exécuté localement pour créer un aperçu local en direct des documents. Ceci est utile pour vérifier le formatage, les liens, etc.

Exécutez hugo server -D --disableFastRender à partir du répertoire de base de votre référentiel local. Lorsqu’aucune erreur n’est rencontrée, le terminal signale : « Le serveur Web est disponible à l’adresse http://localhost:1313/usermanual/development/ (bind address 127.0.0.1) » et le site doit être disponible à l’URL. Hugo surveillera le répertoire pour détecter les modifications et le redéploiera automatiquement lors de la modification des fichiers. Lorsque vous avez une page spécifique ouverte et que vous apportez des modifications au fichier .md correspondant, le navigateur doit également recharger la page après le redéploiement automatique d’Hugo.

🔗Pull request

  1. Go to https://github.com/darktable-org/dtdocs/compare

  2. Appuyez sur Comparer entre les fourches. Sélectionnez votre référentiel, puis la branche sur laquelle vous venez de travailler.

  3. Press Create Pull Request

translations