Aller au contenu principal

Contribution via VS Code et clone local

Cette méthode est recommandée pour les contributions régulières ou volumineuses. Elle vous permet de travailler en local, de prévisualiser vos modifications en temps réel, et de proposer vos changements via une Pull Request.

Prérequis

Avant de commencer, assurez-vous d'avoir un compte GitHub et un accès au dépôt aps-docs. Consultez la page Prérequis si ce n'est pas encore fait.

Installation et configuration initiale​

Cette étape n'est à réaliser qu'une seule fois.

1. Installez Visual Studio Code​

VS Code est le prérequis principal pour travailler en local. Téléchargez-le sur code.visualstudio.com.

Page de téléchargement Visual Studio Code

2. Installez les extensions recommandées​

Dans VS Code, ouvrez le panneau Extensions (icône dans la barre latérale gauche) et installez :

  • Markdown Preview Enhanced — permet de prévisualiser les fichiers .md en temps réel

Extension Markdown Preview Enhanced

  • GitHub Pull Requests — permet de gérer les Pull Requests directement depuis VS Code

Extension GitHub Pull Requests

3. Clonez le dépôt​

  • Ouvrez VS Code et créez une nouvelle fenêtre (File > New Window).
  • Utilisez la commande Clone Git Repository via la palette de commandes (Ctrl+Shift+P).

Palette de commandes VS Code — Clone from GitHub

  • Sélectionnez Clone from GitHub, authentifiez-vous si nécessaire, puis choisissez le dépôt aps-docs dans la liste.
  • Choisissez un répertoire local de destination et confirmez.

Vos sources sont maintenant disponibles localement.

Contribuer au quotidien​

1. Récupérez les dernières modifications​

Avant de commencer à travailler, effectuez un pull pour synchroniser votre copie locale avec la branche principale. À faire dès lors que vous souhaitez mettre à jour la documentation, afin de partir d'une base à jour et d'éviter les conflits.

2. Créez votre branche de travail​

Dans VS Code, cliquez sur le nom de la branche en bas à gauche de la fenêtre (généralement main). Sélectionnez Create new branch et donnez-lui un nom personnel (ex. : modif-prenom).

Barre de statut VS Code avec le nom de branche (main)

astuce

Chaque contributeur travaille sur sa propre branche dédiée, ce qui évite les conflits lors de modifications simultanées.

3. Modifiez vos fichiers​

Les dossiers sur lesquels vous avez les droits de contribution sont :

  • docs-internal — documentation interne
  • docs-public — documentation publique

Explorateur de fichiers VS Code avec le dépôt aps-docs

attention

Ne modifiez pas les dossiers techniques (plugins, playwright, reports, etc.) : vous n'aurez pas les droits pour les pousser.

Prévisualisez vos modifications en temps réel grâce à l'extension Markdown Preview Enhanced (clic droit sur le fichier > Open Preview).

4. Committez vos modifications​

Depuis le panneau Source Control (icône dans la barre latérale gauche), vous verrez la liste des fichiers modifiés. Rédigez un message de commit explicite, puis cliquez sur Commit.

Panneau Source Control VS Code

remarque

Le commit est une sauvegarde locale de l'état de vos fichiers à un instant T. Rien n'est encore envoyé vers GitHub. Vous pouvez faire autant de commits que nécessaire avant de pousser.

5. Publiez votre branche et créez une Pull Request​

Une fois vos modifications prêtes, publiez votre branche sur GitHub (bouton Publish Branch). VS Code vous proposera ensuite de créer une Pull Request. Vous pouvez également le faire depuis l'extension GitHub Pull Requests dans la barre latérale.

La Pull Request permet à un administrateur de relire et valider vos modifications avant leur intégration à la branche principale.

6. Validation et déploiement​

Une fois la Pull Request approuvée et mergée par un administrateur, un workflow GitHub Actions se déclenche automatiquement pour rebuilder et déployer le site. Vos modifications sont alors visibles en ligne.

Résolution des conflits​

Si deux personnes ont modifié le même fichier, Git signalera un conflit au moment du merge. VS Code affiche clairement les deux versions (Current change et Incoming change). Vous pouvez choisir de conserver l'une, l'autre, ou les deux, puis committer la résolution.

Conseils pratiques​

  • Effectuez un pull avant chaque session de travail sur la documentation, pour partir d'une base à jour et éviter les conflits.
  • Committez régulièrement : des petits commits fréquents sont plus faciles à relire et à corriger.
  • En cas de doute sur une commande Git, Claude ou GitHub Copilot peuvent vous aider à formuler les commandes appropriées directement dans VS Code.
  • Pour vider le cache du navigateur et voir la dernière version déployée : clic droit sur le bouton Rafraîchir > Vider le cache et effectuer une actualisation forcée.