Participer à des projets open-sources avec Git et GitHub

a marqué ce sujet comme résolu.

Bonjour à tous,

J'ai commencé (il y a 5 mois) la rédaction d'un tutoriel dont l'intitulé est Participer à des projets open-sources avec Git et GitHub.

J'aimerai obtenir un maximum de retour sur celui-ci, sur le fond ainsi que sur la forme, afin de proposer en validation un texte de qualité.

Si vous êtes intéressé, cliquez ci-dessous

Merci d'avance pour votre aide

+0 -0

Je vais lire ça avec attention mais un commentaire de l'introduction: le noyau linux est un mauvais exemple. Le dépôt est uniquement un clone de celui de Linus. Les contribution au noyau ne se passent pas du tout par github et les pr y sont refusés. Ils utilisent git de manière totalement décentralisée. Dans tous les cas github sert ici uniquement de clone et sauvegarde, c'est un mauvais exemple je pense.

+0 -0

Pour moi le plan général (les extraits) sont bien cohérents et définissent je pense un bon plan a suivre pour ce tuto.

Par contre je viens de lire le premier extrait et j'ai quelques remarques.

  • La plus importante selon moi est que cela fait trop "pas a pas sans réelle valeur info". Tu expliques "cliquez ici, tapez ca, copiez la bas" etc mais ne dit pas concrètement a quoi ça sert, c'est dommage ;
  • Pour ton bloc de "code console", précise que tu as ajoute des commentaires et déplace les éventuellement avant chaque ligne concernée pour faciliter la lecture ;
  • Dans tes captures d’écrans, rajoute des infos bidons pour donner un plus grande intérêt a l'illustration (et n’hésite pas a commenter les champs, par exemple "Title" pour une cle SSH c'est quoi ?) ;
  • "La clé publique qui finit par .pub" -> faire un rappel de ou la trouver
  • La partie "Forker le dépôt" me semble obscure. On ne sait pas tu parles de qui (Moi ? Bob ?Alice ? autre ?) et tu ne dis pas pourquoi il faut faire un fork ni ce que c'est, le néophyte ne comprendra pas.

Bref, n’hésite pas a en dire plus et a être explicite :)

+1 -0

Bonjour à tous !

La beta du tutoriel a été mise à jour.

J'ai essayé de corriger les points donnés par Eskimon et Kje. J'ai aussi rajouté deux parties : créer des tickets ; filtrer avec des tags et des jalons. Je vais les grossir un peu plus prochainement !

Merci pour vos relectures

+0 -0

Salut,

Voici mes retours comme tu me l'as demandé :

  • Introduction
    • "Github est un site web qui permet d'héberger gratuitement des dépots Git tant qu'ils sont open-sources" Faux, cela dépend de la licence que tu appliques à tes données. Elles sont loin de toutes être open-source. Tu pourrais très bien appliquer une licence propriétaire sur un dépôt public de GitHub, rien l'empêche.
    • Dans cette introduction, tu donnes un exemple avec Alice et Bob qui sera utilisé tout au long du tutoriel mais tu n'utilises jamais Alice. Je pense que tous les "<vous>" que tu mets partout, tu devrais mettre "Alice" et dans cette introduction, mentionner que Alice est le lecteur. Comme ça, tu t'embêtes plus à savoir qui est le lecteur ou non.
    • Après lecture du tutoriel, je pense que tu devrais mentionner dans l'introduction que ce tutoriel ne s'adresse pas à des débutants de Git mais plutôt à des intermédiaires minimums.
  • Préparer le terrain
    • C'est toujours dangereux de renseigner des chemins pour suivre des étapes à faire, d'autant plus sur un site qui peut changer d'un jour à l'autre. Par expérience, je sais que le lecteur est perdu si ce qui est marqué dans son tuto ne correspond pas à ce qu'il doit vraiment faire. Je pense donc que tu devrais mentionner quelque part la version du site que tu utilises (si c'est récupérable quelque part) ou signaler que les chemins peuvent légèrement changer mais que cela n'enlève rien au fond des choses que tu expliques.
    • Pour la création d'une clé SSH, tu as une balise de code console qui est juste imbuvable. Je n'ai pas eu le courage de la lire. Déjà, les commentaires console se font des avec # et je pense que c'est inutile de surcharger à ce point cette citation de code. Explique ce que tu fais au dessus, ce qui a été fait en dessous et comment l'exploiter.
    • Tu dis que la communication SSH est sécurisée sans aller plus loin. Sans faire un cours sur la sécurité avec SSH, je pense que tu devrais expliquer l'intérêt de partager sa clé publique sur GitHub et garder bien cacher sa clé privée chez soit.
    • Une suggestion : Quand tu cites Wikipedia, je te conseil de citer une page de l'historique pour qu'elle n'évolue pas dans le temps. Potentiellement, demain, la définition du fork ne sera plus la même. Pour ta citation, l'URL serait https://fr.wikipedia.org/w/index.php?title=Fork&oldid=110384907.
    • "La différence étant que ce dernier vous appartient et que vous pouvez le modifier à volonté !" Oui et non. Tu effectues une copie des données du dépôt que tu souhaites forker, puis la propriété dépend de la licence qui est appliquée sur ces données.
    • A la toute fois, tu mentionnes comment "ajouter le dépôt de Bob" à son dépôt local mais tu n'expliques pas ce que ca va permettre concrètement. Explique ce que ca faire concrètement la commande git-remote.
  • Proposer des modifications
    • Dans l'introduction, tu mentionnes que tu seras dorénavant indépendant de GitHub mais toutes les captures sont toujours de GitHub. Tu devrais retirer cette information puisqu'elle est erronée.
    • Dans la première section "Avant de faire des modifications", tu spécifies comment se mettre sur la branche principale de Bob (que tu mentionnes master dans ton exemple mais qui n'est pas toujours le cas) qui va, concrètement, créer une branche master sur le dépôt local. Puis, tu spécifies comment créer une nouvelle branche avec un autre nom à partir de la branche principale de Bob mais tu ne mentionnes pas que les 2 commandes sont liées. Si Alice était sur la branche feature-1, la commande que tu spécifies va créer une nouvelle branche à partir de feature-1 et pas de master.
    • Dans la première section "Avant de faire des modifications", tu mentionnes dans une info bulle les problématiques de créer des branches avec des accents mais dans l'exemple juste avant, tu ne mentionnes pas le nom de la branche que tu désirais créer.
    • Dans la seconde section "Après avoir fait les modifications", tu expliques la commande push. Par contre, tu dis que le paramètre –set-upstream est obligatoire la première fois. Je n'ai jamais utilisé cette commande de ma vie et je n'en ai jamais eu besoin.
  • Vérifier des modifications
    • Dans la première section "Vérifier une pull request", tu expliques ce que c'est une QA. Je pense que tu devrais plutôt mentionner revue de code à la place de QA (qui est un terme plus utilisé) et mentionné que ZdS parle plutôt de QA. Il existe une différence entre les 2 mais elle est subtile (la revue de code se porte uniquement sur la lecture du code et la QA a une signification plus large et un peu flou).
  • Créer des tickets
    • Je ne trouve pas très pertinent le fait d'expliquer ce qu'est un ticket par contre, j'en vois beaucoup plus dans toutes les interactions possibles qu'il peut y avoir entre un ticket et une PR. Voire la possibilité d'étendre les tickets à des outils tiers comme JIRA tout en gardant ces interactions avec les PRs. (Ceci est peut-être spécifique à GitHub.)
  • Quelques pratiques courantes
    • Dans la première section "Concernant les fichiers", lorsqu'on ajoute un fichier CONTRIBUTING.md à la racine de son dépôt, il affichera un lien à la création de toutes les PR vers son dépôt. Ca me semble important à le signaler.
    • Dans la seconde section "Concernant Git", je crois que tu veux parler de "GitFlow" et non "Git". Tu devrais modifier le titre et expliquer brièvement de quoi il s'agit.

Globalement, le tutoriel est pas mal mais à encore besoin de pas mal de modifications. A noter aussi qu'il y a des fautes mais que je m'y suis pas penché plus que ça pour l'instant en me focalisant sur le contenu.

+2 -0

@Andr0 : Merci beaucoup pour tes remarques !

  • Introduction
    • Dans cette introduction, tu donnes un exemple avec Alice et Bob qui sera utilisé tout au long du tutoriel mais tu n'utilises jamais Alice. Je pense que tous les "<vous>" que tu mets partout, tu devrais mettre "Alice" et dans cette introduction, mentionner que Alice est le lecteur. Comme ça, tu t'embêtes plus à savoir qui est le lecteur ou non.

Je sais pas. Je voudrais laisser l'utilisateur dans l'histoire comme ça il est vraiment acteur de l'histoire. Je vais quand même réfléchr à ton idée plus en détail.

  • Préparer le terrain
    • C'est toujours dangereux de renseigner des chemins pour suivre des étapes à faire, d'autant plus sur un site qui peut changer d'un jour à l'autre. Par expérience, je sais que le lecteur est perdu si ce qui est marqué dans son tuto ne correspond pas à ce qu'il doit vraiment faire. Je pense donc que tu devrais mentionner quelque part la version du site que tu utilises (si c'est récupérable quelque part) ou signaler que les chemins peuvent légèrement changer mais que cela n'enlève rien au fond des choses que tu expliques.

Tu veux parler du tout début ou j'explique quoi renseigner ? Les 3 Steps ?

  • Proposer des modifications
    • Dans la seconde section "Après avoir fait les modifications", tu expliques la commande push. Par contre, tu dis que le paramètre –set-upstream est obligatoire la première fois. Je n'ai jamais utilisé cette commande de ma vie et je n'en ai jamais eu besoin.

Moi j'ai toujours besoin de mettre ce paramètre. En voici la preuve :

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
situphen@kouign-amann-laptop:~/Documents/Dev/Python/zdsenv/zds-site$ git checkout upstream/dev 
Checking out files: 100% (192/192), done.
Note: checking out 'upstream/dev'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:

  git checkout -b new_branch_name

HEAD est maintenant sur a9c1b9b... Merge pull request #2592 from firm1/clean_files
situphen@kouign-amann-laptop:~/Documents/Dev/Python/zdsenv/zds-site$ git checkout -b test
Basculement sur la nouvelle branche 'test'
situphen@kouign-amann-laptop:~/Documents/Dev/Python/zdsenv/zds-site$ git push origin 
fatal: La branche courante test n'a pas de branche amont.
Pour pousser la branche courante et définir la distante comme amont, utilisez

    git push --set-upstream origin test

situphen@kouign-amann-laptop:~/Documents/Dev/Python/zdsenv/zds-site$
  • Proposer des modifications
    • Dans la première section "Vérifier une pull request", tu expliques ce que c'est une QA. Je pense que tu devrais plutôt mentionner revue de code à la place de QA (qui est un terme plus utilisé) et mentionné que ZdS parle plutôt de QA. Il existe une différence entre les 2 mais elle est subtile (la revue de code se porte uniquement sur la lecture du code et la QA a une signification plus large et un peu flou).

Je ne sais pas car la revue de code comme son nom l'indique est spécifique au code et donc à l'informatique, non ?

  • Créer des tickets
    • Je ne trouve pas très pertinent le fait d'expliquer ce qu'est un ticket par contre, j'en vois beaucoup plus dans toutes les interactions possibles qu'il peut y avoir entre un ticket et une PR. Voire la possibilité d'étendre les tickets à des outils tiers comme JIRA tout en gardant ces interactions avec les PRs. (Ceci est peut-être spécifique à GitHub.)

Je n'ai jamais utilisé JIRA donc je ne pense pas en parler beaucoup. Après, je peux peut-être le nommer ainsi que d'autres outils comme Travis CI ou autre !

  • Quelques pratiques courantes
    • Dans la seconde section "Concernant Git", je crois que tu veux parler de "GitFlow" et non "Git". Tu devrais modifier le titre et expliquer brièvement de quoi il s'agit.

Je voulais bien parler de ce qui concerne Git. Vu que ça n'avait pas l'air très explicite, j'ai renommé en "Concernant l'utilisation de Git", c'est bon ?

+0 -0

Je pense qu'il faudrait plus s'attarder sur un workflow de correction de bug.

C'est déjà un peu le cas, mais quand je me remets à ma propre place quand je débutais, c'est loin d'être évident.

Limite, prendre un exemple concret pourrait aider. Faire un schéma aussi.

Sur le schéma, on retrouverait github.com/alice/repo, github.com/bob/repo et chacune de ces actions pourrait être une flèche :

  • fork du repo original,
  • checkout du projet chez soi,
  • synchro entre l'upstream et l'origin,
  • travail en local, commit,
  • push origin / branche
  • Pull request entre les deux repos

Autre remarque pour les listes de diffusion : beaucoup de projets utilisent Google Group.

Et parmi les bonnes pratiques, quand on travaille sur un projet open source, quand on soumet une issue de type bug, il faut au moins indiquer une façon de reproduire le bug, et si le bug est programmatique (pas graphique) fournir un petit exemple de code (minimal) sur son propre repo qui reproduit le bug.

  1. ça évite (très souvent) de remonter un buf qui n'en est pas un "ah bah tiens, sur un exemple simple je reproduis pas, ah le bug est sans doute dans mon code…"

  2. ça fait gagner du temps à tout le monde en règle générale et c'est très bien vu

Ensuite, quand on soumet une nouvelle fonctionnalité, en règle générale on fournit (c'est vrai pour ZdS notamment, mais aussi pour tous les projets open source sur lesquels j'ai travaillé) un test unitaire qui permet de tester cette nouvelle fonctionnalité (et un test bien ciblé, pas un truc qui teste autre chose au passage).

+0 -0

Mes remarques :

Tu peux preciser que l'ajout d'une cle SSH est facultative, mais c'est plus chiant car il faudra alors taper son mot de passe pour chaque chose ou presque

Puis, on ajoute le dépôt de Bob :

Dans la balise secrète, autant on s'en fout de virtualenv (car ca n'a rien a voir avec GitHub et compagnie) mais autant on (je) s'attend a voir apparaître des conventions comme origin et upstream

git checkout -b …

Tu pourrais preciser qu'un dernier parametre peut-etre un SHA de commit ou carrement une branche. Ce dernier parametre sert de "point de depart" de notre nouvelle branche. Si on ne precise rien c'est le HEAD qui est pris comme depart.

Pour les PR, ca serait bien de préciser en secret qu'il peut y avoir des règles de contribution a lire et respecter pour se voir accepté. Tu le dis plus tard, trop tard a mon gout…

Pour l'ajout des remotes c'est balot de passer par le https alors que tu as propose l'ajout d'une cle SSH au debut pour permettre de passer par le protocole git…

Participer à une pull request: Pourquoi refaire un set-upstream ?

+0 -0

Bonjour à tous !

La beta du tutoriel a été mise à jour.

Modification de l'histoire pour éviter les "<vous>"

Correction des commentaires d'Eskimon sauf

Pour l'ajout des remotes c'est balot de passer par le https alors que tu as propose l'ajout d'une cle SSH au debut pour permettre de passer par le protocole git…

Est-ce que le protocole de Git a un avantage par rapport à HTTPS quand c'est juste pour lire un dépôt distant ?

Merci pour vos relectures

+0 -0

Je ne pense pas qu'il y ait de "s" à "open-source".

Introduction

Git est un puissant logiciel permettant de ne perdre aucun bout de ses travaux.

Pas sûr qu'il soit nécessaire de définir Git, surtout que je doute que ce soit possible en une phrase. J'enlèverais ce paragraphe.

Il a été créé par Linus Torvalds pour le développement du noyau Linux !

Le point d'exclamation fait bizarre.

il s'est donc décidé à partager les fiches de révision de ces examens en libre accès sur GitHub

à placer les fiches

et est allée voir ces fiches

est allée consulter

Sinon, ça répète "À la vue de toutes les fautes".

elle a absolument voulue aider Bob a

voulu

Bob à

Préparer le terrain

le plus simple et rapide est de prendre la formule gratuite Free

Oui, mais le lecteur ne voudra pas nécessairement aller au plus simple et au plus rapide. Je dirais simplement que ce tutoriel n'est dédié qu'à cette formule, que nous prenons donc.

Capture d'écran de la page d'inscription

Point.

Il en faudrait une de la deuxième étape.

Pour être sûr de votre identité GitHub

Pour être sûr de votre identité, GitHub

il est possible de créer une paire de clés SSH

Je ferais une note rapide sur ce qu'est SSH et à quoi ça sert. Avec un lien fournissant plus de détails.

Grâce à cette paire de clé

clés

Je vais utiliser ici l'utilitaire ssh-keygen très répandu sur GNU/Linux.

Et si je suis sous Windows et Mac ?

identiques). C'est

identiques) ; c'est

les paramètres de GitHub

les paramètres SSH de votre compte

puis cliquer sur Add SSH key

cliquez

Capture d'écran des paramètres

Capture d'écran des paramètres SSH.

allez sur le dépôt de Bob

Comment je fais ?

Voici le bouton sur lequel cliquer

Le bouton sur lequel cliquer.

Pour ce faire, on lance cette commande :

Où ça ?

clonera le dépôt dans le dossier "Cours d'Alice" !

Le point d'exclamation me semble de trop.

Puis, on ajoute le dépôt de Bob :

Ce n'est pas très clair. On l'ajoute où ?

D'ailleurs, tu devrais expliquer pourquoi tu as un coup git@ et un autre https://.

Et on télécharge son contenu :

Mais je l'ai déjà fait avec le fork, non ?

Merci pour ce tutoriel ! La suite bientôt ! :)

+0 -0

Hello.

Il y a quelque chose qui me gène dans ce tuto, c'est que j'ai du mal à voir ce que tu souhaites expliquer et où tu veux aller. Il y a des tonnes de façons différentes de participer à un projet Github, et la seule façon de ne pas faire n'importe quoi est de contacter les mainteneurs/lire les instructions de contribution/encore autre chose selon le projet. Or, j'ai l'impression que tu as rédigé ce tuto avec une seule vision en tête (qui doit être grosso-modo celle de ZdS) et que tu as écrit la liste des choses que tu as faites toi dans ton cas particulier pour participer. Résultat des courses, on se retrouve juste avec une liste un peu décousue de boutons à cliquer et de commandes à taper sans avoir une vue d'ensemble, un recul général sur ce qui est en train de se passer. Tu mélanges des détails sans grande importance (enregistrer une clé SSH par exemple) avec des choses beaucoup plus capitales sans marquer de différence. Tout est un peu balancé en vrac sans trame de fond ni articulation, et de manière plutôt expéditive.

Du coup, j'aurais tendance à dire qu'il faut déjà que tu cernes bien toi-même le modèle participatif que tu souhaites présenter et que tu évites de t'éparpiller dans tous les sens en ne gardant que ce qui est vraiment essentiel de comprendre.

+1 -0

Il y a des tonnes de façons différentes de participer à un projet Github, et la seule façon de ne pas faire n'importe quoi est de contacter les mainteneurs/lire les instructions de contribution/encore autre chose selon le projet.

Je devrais peut-être préciser ça au début du tutoriel, effectivement.

Or, j'ai l'impression que tu as rédigé ce tuto avec une seule vision en tête (qui doit être grosso-modo celle de ZdS) et que tu as écrit la liste des choses que tu as faites toi dans ton cas particulier pour participer.

Ouais, j'ai sûrement été pas mal influencé par le fonctionnement du projet ZdS. En fait, je me demande même si j'ai assez d'expérience dans les projets open-source pour écrire ce tutoriel.

Résultat des courses, on se retrouve juste avec une liste un peu décousue de boutons à cliquer et de commandes à taper sans avoir une vue d'ensemble, un recul général sur ce qui est en train de se passer. Tu mélanges des détails sans grande importance (enregistrer une clé SSH par exemple) avec des choses beaucoup plus capitales sans marquer de différence. Tout est un peu balancé en vrac sans trame de fond ni articulation, et de manière plutôt expéditive.

Ce n'est pas la première fois que j'entends ça donc je vais essayer d'améliorer ça et de rendre mon tutoriel plus vivant et plus instructif.

Du coup, j'aurais tendance à dire qu'il faut déjà que tu cernes bien toi-même le modèle participatif que tu souhaites présenter

Tu as raison.

et que tu évites de t'éparpiller dans tous les sens en ne gardant que ce qui est vraiment essentiel de comprendre.

J'ai quelques difficultés à organiser mes écrits mais je vais essayer de faire mieux !

+0 -0
Ce sujet est verrouillé.