SpeakingColors/compétences-github

GitHub pour débutants

Compétence communautaire non officielle. Les faits sont vérifiés par rapport à la documentation officielle de GitHub le cas échéant (V). Ne constitue pas un avis juridique.

Style (à suivre strictement)

• Supposez que l'utilisateur ne connaît rien et ne souhaite pas apprendre Git. Il veut le résultat.
• Donnez une étape à la fois. Nommez le bouton ou le texte du lien exact que l'utilisateur verra. Attendez qu'il confirme avoir terminé avant de donner l'étape suivante.
• Commencez par un résumé d'une ligne. Détails uniquement si demandé.
• S'il envoie une capture d'écran, lisez-la et dites-lui où il se trouve avant l'instruction suivante.
• Si vous (l'assistant) pouvez effectuer l'étape vous-même avec accès au dépôt, proposez de le faire. Demandez l'accès via l'outil approprié ou le flux de connexion. Ne demandez jamais de coller un mot de passe ou un jeton d'accès dans le chat.

1. Créer un dépôt

1. Cliquez sur le + en haut à droite de github.com, puis Nouveau dépôt.
2. Nom : court, minuscules, tirets (par exemple mon-plugin).
3. Choisissez Public (tout le monde peut voir) ou Privé.
4. Cochez Ajouter un README. Choisissez une licence dans le menu déroulant (voir section 5).
5. Cliquez sur Créer un dépôt.

Un dépôt vide affiche une page « Configuration rapide » avec des boîtes de commande. Un débutant peut ignorer tout cela et utiliser le lien « télécharger un fichier existant » à la place.

2. Mettre des fichiers dans le dépôt (web, sans Git)

Sur la page du dépôt : Ajouter un fichier, puis Télécharger des fichiers. Ensuite, faites glisser les fichiers ou cliquez sur « choisir vos fichiers ».

Limites (V : docs GitHub, Ajout d'un fichier à un dépôt) :

• 25 Mio par fichier lors du téléchargement dans le navigateur.
• Jusqu'à 100 fichiers par téléchargement.
• Fichiers plus volumineux, jusqu'à 100 Mio chacun, nécessitent la ligne de commande ; les fichiers de plus de 100 Mio ont besoin de Git Large File Storage.
• Une branche protégée ne peut pas être modifiée via le téléchargement web.
• La protection push peut bloquer un fichier contenant un secret pris en charge, comme un jeton.

Dossiers : la documentation indique que vous pouvez faire glisser un fichier ou un dossier. Si le navigateur de l'utilisateur n'accepte pas un dossier, utilisez l'une des alternatives suivantes :

• Créez le dossier dans l'éditeur web : Ajouter un fichier, Créer un nouveau fichier, tapez nomdossier/nomfichier.md dans la zone de nom (le fait de taper la barre oblique crée le dossier), ajoutez du contenu, puis validez. Vérifiez le comportement dans l'interface actuelle.
• Décompressez le dossier et téléchargez les fichiers par lots en conservant leurs chemins de dossier, ou utilisez GitHub Desktop.
• Laissez l'assistant pousser les fichiers s'il a accès au dépôt.

Les fichiers zip sont stockés comme un seul fichier ; GitHub ne les décompresse pas. Téléchargez le contenu décompressé.

Terminez par un message de validation (court, ce qui a changé) et le bouton Valider les modifications.

Vérifiez le résultat : ouvrez la page du dépôt et comparez la liste des fichiers avec ce qui était prévu. Erreur fréquente : les fichiers atterrissent à la racine au lieu de leur dossier.

3. Releases avec téléchargements (ce que les utilisateurs doivent télécharger)

Une release est une page de téléchargement étiquetée basée sur un tag Git (V : docs GitHub, À propos des releases).

1. Sur la page du dépôt, cliquez sur Releases (à droite), puis Brouillon d'une nouvelle release.
2. Choisissez un tag comme v1.0.0 (tapez-en un nouveau, puis Créer un nouveau tag).
3. Titre et notes : de quoi il s'agit, comment installer en trois étapes, ce qui a changé.
4. Faites glisser les fichiers dans la zone des assets. Les releases adaptées aux débutants incluent un installateur compilé ou un fichier par système d'exploitation, un manuel court et des instructions d'installation, pas seulement un fichier brut ou le code source.
5. Cliquez sur Publier la release.

Limites (V) : chaque fichier fait moins de 2 Gio, jusqu'à 1000 assets par release, aucune limite de taille totale ou de bande passante.

Modèle de notes de release :

• De quoi il s'agit (une ligne)
• Téléchargement : choisissez votre système (Windows, macOS, Linux)
• Installer en trois étapes
• Sommes de contrôle (SHA-256) pour chaque fichier
• Problèmes connus

4. Licence et bases du README

• Un dépôt sans licence n'est pas open source ; les autres n'ont aucun droit de le réutiliser. Choisissez-en une délibérément.
• MIT : très permissive, courte. AGPL-3.0 ou GPL : partage à l'identique. Les projets basés sur JUCE selon son option open source sont couverts par l'AGPLv3 (V : forum JUCE, personnel), donc vérifiez la licence JUCE actuelle avant de choisir.
• Ne publiez jamais de fichiers fournisseur (manuels, presets d'usine, logos, binaires) dont vous ne possédez pas les droits. Liez-les à la place.
• Le README doit répondre à : qu'est-ce que c'est, comment installer, comment utiliser, licence, comment signaler des problèmes.

5. Garder les informations privées en dehors (le plus important)

Avant le premier push public, parcourez chaque fichier et l'identité de validation pour : nom réel, email personnel, téléphone, adresse, employeur, jetons, mots de passe, chemins locaux avec le nom d'utilisateur.

Identité de validation :

• Utilisez l'adresse noreply de GitHub, affichée dans Paramètres, Emails, avec « Garder mon adresse email privée » coché. Format : <identifiant numérique>+<nomdutilisateur>@users.noreply.github.com.
• Définissez-la avant de valider : git config user.name "<nomdutilisateur>" et git config user.email "<id>+<nomdutilisateur>@users.noreply.github.com". Vérifiez avec git log --format='%an <%ae>' avant de pousser.
• Lorsqu'un assistant valide pour l'utilisateur, il doit utiliser cette identité et jamais l'email réel de l'utilisateur.

Si des données privées ont déjà été rendues publiques (V : docs GitHub, Suppression de données sensibles d'un dépôt) :

1. S'il s'agit d'un identifiant, révoquez ou changez-le d'abord. Cela peut suffire en soi.
2. Réécrivez l'historique localement avec git-filter-repo (version 2.47 ou ultérieure pour --sensitive-data-removal). Supprimez un fichier avec --invert-paths --path, ou remplacez du texte avec --replace-text.
3. Force-push pour écraser le dépôt sur GitHub.
4. Contactez le support GitHub pour supprimer les vues en cache et les références de pull request ; donnez-leur le nom du dépôt, le nombre de PR affectées et les premiers commits modifiés issus de la sortie de l'outil.
5. Les forks conservent les données ; demandez aux propriétaires des forks de les supprimer. Les collaborateurs doivent rebaser, pas fusionner.
6. Avertissement de la documentation : les clones d'autres personnes conservent les données, et une réécriture peut révéler ce qui a été supprimé. Supposez que les données ont été vues.

Modifier un commit récent suffit seulement pour la pointe de la branche ; l'ancien commit peut toujours être accessible via son lien direct jusqu'à ce que GitHub nettoie, donc l'étape 4 s'applique toujours.

5b. Choisir ce qui devient public

• Les notes de recherche, les données capturées d'appareils, les notes personnelles et les transcriptions de chat n'ont pas leur place dans un dépôt public, sauf si l'utilisateur le dit.
• Demandez avant de publier quoi que ce soit qui n'a pas été écrit pour le public.

6. Tâches quotidiennes (une à la fois)

• Modifier un fichier sur le web : ouvrez-le, icône crayon, modifiez, Valider les modifications.
• Supprimer un fichier : ouvrez-le, trois points, Supprimer le fichier, valider.
• Renommer ou déplacer : modifiez la zone de nom du fichier, en tapant le nouveau chemin ; validez.
• Épingler un dépôt sur le profil : page de profil, Personnaliser vos épingles.
• Activer une page web de projet (GitHub Pages) : Paramètres, Pages, choisissez la branche et le dossier. Vérifiez l'interface actuelle.
• Signaler ou suivre des problèmes : onglet Issues. Proposez un modèle d'issue pour les rapports de bugs.

7. En cas d'échec

• Téléchargement refusé : vérifiez la taille du fichier (limite web 25 Mio), le nombre de fichiers (100) et la branche protégée.
• Dossier manquant : les fichiers ont été téléchargés à plat ; recréez le chemin avec Créer un nouveau fichier ou re-téléchargez.
• Push rejeté avec un avertissement de secret : supprimez le secret, changez-le et réessayez.
• Ne suggérez jamais de désactiver les invites de sécurité.

Sources

• Docs GitHub, Ajout d'un fichier à un dépôt : https://docs.github.com/en/repositories/working-with-files/managing-files/adding-a-file-to-a-repository
• Docs GitHub, À propos des releases : https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases
• Docs GitHub, Suppression de données sensibles d'un dépôt : https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository