[Dev doc] Support Aide au nouveaux et nouvelles contributrices

[Plumf]

Quoi écrire ? Comment l’écrire ? et comment l’envoyer ? Trois questions que je me suis pausé lors de mes premiers pas de contributeur avec la documentation Yunohost et que je me pause toujours. Je souhaites développer la documentation et pour le moment la partie contributeur et y ajouter (pour le moment) trois pages :

1. Un guide de redactions qui serait une trame sur comment rédiger la documentation, qui permettrait aussi que chaque utilisateur·trice puisse avoir les même repères lors de la consultation de la doc des applications.
2. Un guide markdown qui se voudrait exaustif dans le cadre du wiki de Yunohost (qui ne centraliserait que ce qui fonctionne pour le wiki en markdown). Il permettrait aussi de ne pas avoir plusieurs liens qui pointent vers des sites extérieurs en anglais (ce qui pour un unique francophone peut desorienter et complexifier la contribution).
3. Un guide pour utiliser git. Afin qu’une personne lambda puisse se créer un compte sur dépot git et propulser sa documentation dans une PR sur le dépot git.

Actuellement je suis toujours en train de travailler à ces différentes pages, je les rédige en français et un coup de main pour la traduction ne me ferait pas de mal. Il s’agit aussi de pouvoir discuter et débattre du projet d’une aide pour les contributeurs·trices. Peut être manque il des choses ?
Pour ceux et celles qui ne possede un comptes github on en discute aussi ici :

Support aide au nouveaux et nouvelles contributrices

Ping @Gofannon qui semblait intéressé…

[Plumf]

Point de situation 1 : Je propose de rajouter trois pages supplémentaire à la documentation de YnH en sous menu de la partie écrire de la documentation
cf : github.com - commit b54a18238d31dd14fc6d6c13ba4866f31898fdec)

1. Une page avec un guide markdown (ici : github.com - commit 85413f6d222f0ac20ece5a6df23c8aa815402c50)
   Actuellement en version à eprouver, controler, modifier, c’est actuellement une proposition de version de publication en attente de tous les oublis observés.

2. Une page de guide à propos des contributions avec git et toutes les subtilités de l’outils qui peut faire peur. Cette pages est toujours au travail. Je compte adjoindre des vidéos (je crois savoir qu’un hébérgement peertube existe chez yunohost ?) Le document est toujours en cours de construction mais les retours critiques sont les bienvenus notamment sur les vidéos.
   La page dans sa version la plus avancée github.com - commit e47d0f17d739c8ed668d10ea28b61459e4d01607

   2.1 Je cherche des infos sur les bonnes pratiques de tutoriels ? Faut il les sonoriser ? ou plutôt mettre en valeur des parties dans la vidéo et ajouter des explications textuelles ? Ou les deux ? ???

3. Une page que je nomme pour le moment trame qui permettrai d’équiper de potentiels contributeur.trices qui ne saurait pas par ou commencer. Qui permettrait aussi de definir une roadmap des nécessité de la documentation ainsi que des “bons usages”
   Ce fichier est un prémice de reflexion, je suis pret à discuter de tout et de pourquoi. Mais aussi la prise de tout les idées qui viendraient.
   Disponible ici : github.com - commit 6b2adae6913a9fa47cf600ff12d11731d68fcaa4

N’hésitez pas à critiquer et donner votre avis ! Merci du temps accordé =)

[Plumf]

1. Un guide markdown qui se voudrait exaustif dans le cadre du wiki de Yunohost (qui ne centraliserait que ce qui fonctionne pour le wiki en markdown). Il permettrait aussi de ne pas avoir plusieurs liens qui pointent vers des sites extérieurs en anglais (ce qui pour un unique francophone peut desorienter et complexifier la contribution).

Proposition de version finale :

YunoHost/doc/blob/d55b1c1b4fed77bae25c08d4ea5a28aad0b10145/doc_markdown_guide_fr.md

• Proposition d’une version final.
• [ ] Traduire la page en anglais.
• [ ] Renvoyer vers markdowntutorial.com en français.

[gannonwoto]

Salut,

Personnellement, je trouve que c’est une bonne idée.

Concernant la partie sur git je pense qu’il faudrait rajouter une partie “spéciale github”/ graphique. En effet il est parfois plus simple de “forcker” … le repo doc par exemple, faire ses modifications, commit et PR graphiquement que de tout faire avec git en lignes de commandes.

Concernant proposition pour le guide markdown, je rajouterais biens les lignes suivantes après la 248

Coloration Syntaxique.

Il est possible d’ajouter une coloration syntaxique aux blocs de codes en renseignant le nom du langage juste après les `

exemple:

```bash
function foo ()
{
    echo "Hello World"
    return 0
}
```

Donne

function foo ()
{
    echo "Hello World"
    return 0
}

et

```python
def hello(name):
    print("Hello "+name+" !")
```

Donne:

def hello(name):
    print("Hello "+name+" !")

Note en passant, la coloration syntaxique comme les tableaux font seulement partie du “Markdown Github”. Il me semble pas que le markdown “de base” dispose de ces fonctionnalités.

[Plumf]

@gannonwoto

Concernant la partie sur git je pense qu’il faudrait rajouter une partie “spéciale github”/ graphique.

C’était le premier objet de ce guide mais vu la puissance de l’outils en ligne de commande je commence à me dire qu’il est compliqué de zapper l’usage de git en terminal.

@gannonwoto

Note en passant, la coloration syntaxique comme les tableaux font seulement partie du “Markdown Github”. Il me semble pas que le markdown “de base” dispose de ces fonctionnalités.

Je crois aussi en effet que c’est seulement pour le Markdown flavour Github ou c’est dispo mais tant mieux pour le moment YunoHost utilise Github.

[gannonwoto]

@Plumf

C’était le premier objet de ce guide mais vu la puissance de l’outils en ligne de commande je commence à me dire qu’il est compliqué de zapper l’usage de git en terminal.

Ca dépend surtout de ce que tu veux faire. Si c’est par exemple pour corriger une erreur de typographie, changer / ajouter une dépendance dans une application yunohost , … On à pas besoin de cloner le dit repo . Tout peut se faire via Github, et c’est même plus rapide et simple.

Mais là ou je te rejoins c’est que grosso modo, toutes actions qui sont faites sur GitHub dans ces cas-là sont des commandes git. Autrement dit tout ce qui est fait avec GitHub peut se faire avec uniquement git.

A mon sens le tuto devrait présenter les choses suivantes :

1. Sous Github comment:

• « forcker » un repo
• commit
• PR

Si je me trompe pas pour les simples modifications ca devrait suffire.

2. Faire exactement la même chose sous git

• clone du repo
• creation de branche ?
• commit
• création d’une PR

Rien que ça me semble déjà pas mal. Mais ça dépend aussi jusqu’où on veut aller dans ce tuto, si c’est pour faire un manuel complet de git … il est déjà là et en français en plus : Git - Book

---

Edit: pour se qui est des commandes git à présenter :
git init
git add
git commit
git status
git push
git pull
git branch
git chekout
git diff ?
git fetch ?

[Aleks]

@gannonwoto

Edit: pour se qui est des commandes git à présenter :
git init
git add
git commit
git status
git push
git pull
git branch
git chekout
git diff ?
git fetch ?

(Attention à ne pas réinventer la roue … des tutos sur Git je pense qu’il y’en a déjà des milliers sur Internet … perso je tenterais en premier lieu de trouver un site qui propose une approche cool pour apprendre git de manière ~ludique (genre histoire de ne pas avoir à lire un énorme pavé technique écrit par et pour développeurs))

[michelw1]

Bonsoir,
JE peux vous suggérer celui-ci qui me convient bien en tant que débutant:

SocialGouv/tutoriel-gitlab

[gannonwoto]

@Aleks
Oui, c’est un peu ce que je dis avec le lien suivant https://git-scm.com/book/fr/v2 … qui pourrait en gros se traduire par rtfm … mais c’est pas vraiment pédagogique il me semble.

Si j’ai bien compris les dire de Plumf, le but est surtout d’avoir un debut de guide / initiation à git pour pouvoir effectuer des modifications simples / écrire de la doc / traduction.

C’est pourquoi à mon humble avis et si j’ai bien compris le but de la partie git un tuto spécifique à github serait déjà pas mal.

Mais comme dit plus haut tout ce qui est fait sur GitHub peut être fait en ligne de commandes. Donc un début de doc sur les principales commandes git peut aussi être pas mal… (il y en avait peut-être trop dans ma liste certes).

Par contre; bien que je pense que c’est faisable; je passe toujours pas l’interface graphique de github/gitlab pour effectuer des PR.

[gannonwoto]

Je viens de lire en diagonale, et hormis le fait que c’est pour GitLab, c’est à mon sens trop orienté création et gestion d’un repo. Mais soit dit en passant c’est pas mal fait.

[Aleks]

Il existe ce genre de site qui sont plus interactif et sexy quand on débute : https://learngitbranching.js.org/

[Plumf]

De base je me situais dans la peau d’une personne qui ne connait rient à git/GitLab/Github et qui souhaiterais contribuer dans à la documentation. Pour cela il me semblait plus facile de faire les modifications directement sur github hormis pour les cas de grosses contributions qui ne se feraient pas d’un coup et en plusieurs étapes, et la cela devient pratique de travailler en local, de façon à eviter de nombreux commits intérmediaires (Je sais de quoi je parle, pour le moment je suis un specialiste du commit intermediaire inutile).

Je prend toutes les idées et propositions faites ci-dessus elles me semble toutes intéressantes peut tre un jour si une federation de repots git existent le tuto sur gitlab sera très utile…

Bref nous avons de la ressources il n’y a pllus qu’à la mettre en ordre !

[anonyme18]

Bonjour,
Je n’ai pas franchi le pas d’ouvrir un compte Github. J’ai un Gitea sous Yunohost avec lequel je “m’amuse”.
Pour initialiser un dépôt, en local, je préfère la ligne de commande…
Pour tout ce qui est init, add, commit, pull, push, branch, checkout, je commence à être à l’aise. Avec les merge, pas du tout !
Et puis tous ces commits intermédiaires . Il y a-t-il un moyen simple de les zapper : style commit aaa -> commit ffff sans intermédiaires ?
D’autre part je me demande si en cli, en étant “invité” on peut pusher, merger sur un dépôt Github, sans avoir de compte ?
Je suis vraiment débutant et désolé si je pose des questions stupides ou dans le manuel.
Merci pour toutes les découvertes, aides, plaisirs, etc. que Yunohost me procure !

[gannonwoto]

RTFM

Je déconne,

@anonyme18

Il y a-t-il un moyen simple de les zapper : style commit aaa → commit ffff sans intermédiaires ?

Réponse courte : oui.
Réponse un peu plus longue est : oui et je t’invite à aller voir cet article

@anonyme18

D’autre part je me demande si en cli, en étant “invité” on peut pusher, merger sur un dépôt Github, sans avoir de compte ?

Non,

@anonyme18

Pour tout ce qui est init, add, commit, pull, push, branch, checkout, je commence à être à l’aise. Avec les merge, pas du tout !

C’est pourtant simple dans les cas basiques :

• tu as un fichier yunohost.txt dans ta branche master
• tu crées une nouvelle branche devMeLire (git checkout -b devMeLire)
• dans cette branche tu vas ajouter un fichier ou modifier une partie d’un fichier déjà existant (vim README.md ou nano README_fr.md).
• git add + git commit
• tu vas sur la branche master (git checkout master)
• tu merge la master avec la devMeLire avec : git merge devMeLire.
  Ou autrement dit : pour rappatrier les modifications de la branche devMeLire sur la branche master ; tu te place sur la master et tu rapatries les modifications avec git merge devMelire.

Et pas l’inverse !

C’est l’étape 3 de la séquence d’intro du lien de Aleks
(note à ce propos ; perso j’aurais mis les flèche dans l’autre sens. Elles me perturbent là.)