Optimiser le travail avec vos projets sur GitHub : se familiariser avec le référentiel de modèles Github

Bonjour à tous, communauté JavaRush ! Aujourd'hui, nous parlerons de l'open source et de ce qu'il faut pour créer un projet de haute qualité EN PLUS du code écrit. Il est important d'écrire un produit utile. Mais la conception correcte du référentiel (dépôt de projet sur GitHub) n'est pas moins importante. Cela aidera à mettre en œuvre un autre point clé : la promotion du produit. Même si le projet est super cool, mais s'il est mal conçu, n'est pas décrit au moins dans le README (vous pouvez lire ce qu'est un README ici ), la licence n'est pas indiquée, etc., etc., il y aura Sans succès. C'est juste que personne ne le remarquera. Et si quelqu’un le remarque, il ne saura pas comment interagir avec lui. Il y a beaucoup de choses qui doivent être remplies encore et encore, et il n'est pas facile pour le programmeur de copier et coller à chaque fois, et juste pour cela, cet été, GitHub a publié la fonctionnalité Template Repository qui aide à cela. Pour ainsi dire, pour automatiser le processus de création de nouveaux projets. Aujourd'hui, nous allons comprendre ce qu'est un référentiel et ce qu'est un référentiel de modèles. Nous décrirons ce qui devrait figurer dans le projet en plus du code, sur quels éléments vous devez vous concentrer. Créons un référentiel de modèles à partir de zéro et ajoutons tout ce qui est nécessaire de mon point de vue. Et enfin, nous utiliserons Template Repository lors de la création d’un nouveau référentiel. Mais d’abord, comprenons les termes. Théorie : ce qui devrait figurer dans le référentiel général de tout projet. Chaque projet open source sur GitHub doit avoir un profil communautaire bien décrit , qui contient les éléments suivants.

1. Modèle de problème

Ici, vous devez décrire les règles de création d'un ticket dans le référentiel : comment ils doivent s'appeler, quelle sera l'étiquette, qui y sera affecté. Lors de la création d'un nouveau problème, les options suivantes seront proposées :

• Rapport de bug - création d'un problème pour décrire un défaut dans le projet ;
• Demande de fonctionnalité - proposition d'une nouvelle idée de projet ;
• Demande d'amélioration - proposition d'amélioration sur le projet ;
• Modèle de problème personnalisé : si les autres options ne fonctionnent pas, vous pouvez utiliser un modèle vide.

Un exemple de ce à quoi cela ressemble peut être vu ici .

2. Licence

La licence sous laquelle le projet est écrit. C'est nécessaire pour que ceux qui utiliseront le projet sachent ce qui est garanti et ce qui ne l'est pas. Par exemple, la licence Apache 2.0 indique ce qui suit :

3.LISEZMOI

Ceci est une description du projet, sa carte de visite. Tout ce qui doit être dit sur le projet doit être ici. Bien entendu, il faudra le décrire à chaque fois en tenant compte des spécificités du projet, mais les rubriques seront les mêmes. Par exemple:

• Aperçu - une brève description du projet ;
• Utilisation - comment utiliser le projet ;
• Construire - comment lancer un projet, ce qui est nécessaire pour cela ;
• Dépannage : décrit les problèmes que vous pourriez rencontrer et comment les résoudre ;
• Notes de version - description des modifications en fonction de la version ;
• Auteurs – n’oubliez pas vos proches ;
• Contribuer - une description de la manière dont vous pouvez participer au développement du projet ;
• Code de conduite - description des règles de participation ;
• RELEASE_NOTES - un fichier dans lequel toutes les modifications apportées aux nouvelles versions sont enregistrées. C'est une bonne pratique de mettre cela dans un document séparé et de stocker un lien dans le README ;
• CONTRIBUTING est un fichier qui décrit comment vous pouvez contribuer au développement de ce projet. Créé en tant que fichier distinct pour l'en-tête Contributing dans le README ;
• CODE_OF_CONDUCT - un fichier qui décrit les règles de participation au développement du projet ;
• Modèle de demande de tirage - un modèle pour ceux qui créeront une demande de tirage.

Toutes ces choses sont utilisées de projet en projet, quel que soit le langage de programmation ou ses spécificités.

Pratique : créer votre propre modèle

Comme on dit, passons des paroles aux actes. Maintenant, à l'aide d'un exemple, je vais vous montrer comment créer votre propre modèle.

1. La première chose dont vous avez besoin est un compte sur GitHub / inscrivez-vous là-bas .

2. Créer un nouveau dépôt : pour cela, cliquez sur + dans le coin supérieur droit

3. Lors de la création, remplissez :

   • Nom du référentiel - dans mon cas, modèle de référentiel ;
   • Description — brève description du projet ;
   • Nous quittons Public, bien que vous puissiez sélectionner Privé ;
   • Cochez la case d'initialisation README :

   • Sélectionnez la licence sous laquelle le projet sera :

     Puisque dans mon cas le modèle est général, gitignore n'est pas nécessaire : il sera ajouté pour un projet et un langage de programmation spécifiques.

     Par conséquent, cliquez sur Créer un référentiel , complétant ainsi le processus de création. Le système nous amènera automatiquement au référentiel nouvellement créé.

4. Remplir le profil de la communauté : dans le référentiel créé, allez dans l' onglet Insights et sélectionnez Communauté :

   Comme vous pouvez le constater, il ne reste plus qu'à remplir le modèle de code de conduite, de contribution, de problème et de demande de tirage.

   À l’aide de l’exemple du Code de conduite, nous montrerons comment les ajouter à un projet.

   Cliquez sur Ajouter , le système vous invite à sélectionner Contributor Covenant ou Citizen Code of Conduct :

   Je sélectionne le premier et clique sur Review and Submit .

   Ensuite, vous pouvez modifier ce fichier et le valider.

   En bas, sélectionnez l'option Valider directement dans la branche principale et cliquez sur Valider un nouveau fichier :

   En conséquence, si nous revenons au profil de la communauté , nous constaterons que le code de conduite est marqué comme ajouté :

   Les modèles de contribution et de problème sont ajoutés de la même manière, je ne les montrerai donc pas. Fais le toi-même ;)

5. Ajouter un modèle de demande de tirage .

   Mais parlons-en séparément.

   Je ne sais pas pourquoi GitHub n'a pas ajouté la même option pratique pour configurer le modèle Pull-Request, vous devrez donc étudier la documentation et l'ajouter manuellement.

   Pour cela, cliquez sur Créer un nouveau fichier à la racine du référentiel :

   Le nom du fichier doit être : .github/pull_request_template.md .

   Nous ajoutons ce dont nous avons besoin au modèle et cliquons sur Valider un nouveau fichier , comme nous l'avons fait ci-dessus. Je n'allais pas réinventer la roue et j'ai trouvé un exemple qui me semblait tout à fait utilisable.

   De cette façon, l'intégralité du profil communautaire sera renseignée :

6. Ajoutez un marqueur de référentiel de modèles .

   Pour ce faire, accédez à l' option Paramètres dans le référentiel et cochez la case où il est indiqué Référentiel de modèles :

   Et voilà, le modèle pour créer de nouveaux projets est prêt. Ainsi, nous gagnerons beaucoup de temps à l’avenir lorsque nous aurons besoin de créer de nouveaux projets. Cela vous aidera également à ne pas manquer des détails importants, car il arrive souvent que vous oubliiez d'ajouter quelque chose, par exemple une licence ou un modèle clair pour un problème.

Comment utiliser le référentiel de modèles

Il existe deux options d'utilisation :

1. Lorsqu'un modèle vous appartient directement : lors de la création d'un nouveau référentiel, vous aurez la possibilité de créer à partir d'un modèle de la liste des modèles que vous possédez :

2. Lorsque le modèle est étranger : il n'y a pas non plus de problèmes particuliers ici. Accédez à ce modèle et cliquez sur le bouton Utiliser ce modèle . Ici, j'utiliserai l'animation de la doc officielle :

Résumons-le

Dans cet article, nous avons examiné :

• qu'est-ce que le référentiel GitHub ;
• qu'est-ce que le référentiel de modèles ;
• ce qui devrait être dans le référentiel de modèles ;
• comment créer un référentiel de modèles ;
• comment utiliser le référentiel de modèles.

Bien entendu, à partir de ce modèle, vous pouvez déjà en créer des plus spécifiques. Par exemple, j'ai créé plus de modèles avec des systèmes de build maven ou gradle déjà configurés. De plus : vous pouvez créer un modèle de référentiel Spring Boot basé sur les deux derniers. Pour regrouper tous les modèles, j'ai créé une organisation de référentiel de modèles sur GitHub avec tous les modèles. Abonnez-vous à mon compte GitHub

Liens utiles

• Organisation avec tous les modèles que j'ai créés
• Blog GitHub : Générer un nouveau référentiel avec des modèles de référentiel, comment créer un modèle pour les référentiels
• Aide GitHub : À propos des référentiels , ce que sont les référentiels.
• Aide GitHub : Création d'un référentiel à partir d'un modèle comment créer un nouveau projet basé sur un modèle
• Aide GitHub : Licences, description du référentiel des licences pour les projets
• Aide GitHub : Créer une description de dépôt pour la création d'un référentiel
• Conseils des guides Open Source pour créer/décrire des projets open source.
• Aide GitHub : ajout d'un modèle de demande d'extraction - création d'un modèle pour les demandes d'extraction.

Plus de mes articles

• Déboguer dans Intellij IDEA : un guide pour les débutants
• Guide pour créer un client pour l'API Skyscanner et le publier dans jCenter et Maven Central [Partie 1]
• Guide pour créer un client pour l'API Skyscanner et le publier dans jCenter et Maven Central [Partie 2]
• Créer un système de surveillance du prix des billets d'avion : un guide étape par étape [Partie 1]
• Créer un système de surveillance du prix des billets d'avion : un guide étape par étape [Partie 2]
• Créer un système de surveillance du prix des billets d'avion : un guide étape par étape [Partie 3]
• Exploitation forestière : quoi, comment, où et avec quoi ?
• Comment un test d'entretien s'est transformé en une bibliothèque open source
• Histoire de succès. 20 heures de programmation par semaine, master et vie personnelle
• Comment trouver un emploi ? Conseils pour envoyer des CV