Optimizing work with your projects on GitHub: getting to know the Github Template Repository

Hello everyone, CodeGym community! Today we will talk about open source and what is needed to create a quality project, IN ADDITION to the code that is being written. It is important to write a useful product. But no less important is the correct design of the repository (project repository on GitHub). This will help in the implementation of another key point - product promotion. Even if the project is super cool, but if it is poorly designed, it is not described at least in the README (you can read about what README is here), a license is not indicated, etc., etc., there will be no success. It's just that no one will notice. And if someone notices, they won't know how to interact with them. There are many things that need to be filled in from time to time, and every time copy-paste is not from the hands of the programmer, and just for this this summer, GitHub released the Template Repository feature that helps with this. So to speak, to automate the process of creating new projects. Today we will deal with what a Repository is, what a Template Repository is. Let's describe what should be in the project in addition to the code, what things you need to focus on. Let's create a Template Repository from scratch, add everything you need from my point of view. And finally, we will apply the Template Repository when creating a new repository. But first, let's deal with the terms. Theory: what should be in the general repository of any project Every open source project on GitHub should have a well-described Community Profile , which contains the following elements.

1.Issue template

Here you need to describe the rules for creating an issue in the repository: how they should be called, what the label will be, who will be assigned to it. When creating a new Issue, the following options will be offered:

• Bug report - creating an issue in order to describe a defect on the project;
• Feature request - a proposal for a new idea for the project;
• Improvement request - a proposal for improvement on the project;
• Custom issue template - if other options do not fit, you can use an empty template.

An example of what this looks like can be seen here .

2. License

The license under which the project is written. It is necessary so that those who will use the project know what is guaranteed and what is not. For example, the Apache License 2.0 says the following:

3 README

This is a description of the project, its business card. Everything that needs to be said about the project should be here. Of course, it will need to be described each time, taking into account the specifics of the project, but the headings will be the same. For example:

• Overview - a brief description of the project;
• Usage - how to use the project;
• Building - how to start the project, what is needed for this;
• Troubleshooting - describes what problems you may encounter and how to solve them;
• Release Notes - description of changes depending on the version;
• Authors - do not forget about yourself loved ones;
• Contributing - a description of how you can participate in the development of the project;
• Code of Conduct - description of the rules of participation;
• RELEASE_NOTES is a file that records all changes for new versions. It's good practice to put this in a separate document and keep a link to go in the README;
• CONTRIBUTING - a file that describes how you can contribute to the development of this project. Made as a separate file for the Contributing header in the README;
• CODE_OF_CONDUCT - a file that describes the rules for participating in the development of the project;
• Pull Request template - a template for those who will create a pull-request.

All these things are used from project to project, regardless of the programming language or its specifics.

Practice: creating your own template

As the saying goes, we move from words to deeds. Now, with an example, I'll show you how to create your own template.

1. The first thing you need is a GitHub account / sign up there .

2. Create a new repository: to do this, in the upper right corner, click +

3. When creating, fill in:

   • Repository name - in my case repository-template;
   • Description - a brief description of the project;
   • we leave Public, although you can choose Private;
   • Check the README initialization checkbox:

   • Select the license under which the project will be:

     Since in my case the template is general, gitignore is not needed either: it will be added for a specific project and programming language.

     Therefore, we click Create Repository , thereby completing the creation process. The system will automatically transfer us to a freshly created repository.

4. Filling Community Profile : in the created repository, go to the Insights tab and select Community :

   As you can see, it remains to fill out the Code of Conduce, Contributing, Issue Template, Pull Request template.

   Using the Code of Conduct example, we will show how to add them to the project.

   Click add , the system prompts you to choose Contributor Covenant or Citizen Code of Conduct :

   I choose the first one and click Review and Submit .

   Further, it will be possible to edit this file and already commit.

   At the bottom, select the Commit directly to the master branch option and click Commit new file :

   As a result, if we go back to the Community Profile , we will find that the Code of Conduct is marked as added:

   Contributing and Issue Template are added in the same way, so I won't show them. Do it yourself ;)

5. Add a Pull Request template .

   But let's talk about this separately.

   I don’t know why GitHub didn’t add the same convenient option for customizing the Pull-Request template, so I’ll have to study the Murzilka documentation and add it manually.

   To do this, in the root of the repository, click Create new file :

   The file name should be: .github/pull_request_template.md .

   Add what you need to the template and click Commit new file , as we did above. I did not intend to reinvent the wheel and found an example that seemed to me quite usable.

   Thus, the entire Community Profile will be filled in:

6. Add the Template Repository marker .

   To do this, go to the Settings option in the repository and check the box where it says Template Repository:

   And that's it, the template for creating new projects is ready. Thus, we will save a lot of time in the future when we need to create new projects. It will also help you not to miss important details, as it often happens that you forget to add something, such as a license or a clear template for an issue.

How to use the Template Repository

There are two options to use:

1. When the template is directly owned by you: when creating a new repository, you will be given the option to create based on a template from the list of templates you own:

2. When the template is alien: there are no particular problems here either. Go to that template and click the Use this template button . Here I'll use the animation from the official docs:

Summing up

In this article, we've covered:

• what is a GitHub repository;
• what is Template repository;
• what should be in the Template repository;
• how to create a Template Repository;
• how to use the Template Repository.

Of course, based on this template, you can already create more specific ones. For example, I created more templates with configured maven or gradle build systems. Further more: you can create a Spring Boot Repository Template based on the last two. To group all the templates, I created a template-repository organization on GitHub with all the templates. Follow my GitHub account

useful links

• Organization with all the templates I created
• GitHub Blog: Generate new repository with repository templates
• GitHub Help: About repositories about what repositories are.
• GitHub Help: Creating a repository from a template
• GitHub Help: Licensing a repository description of licensing for projects
• GitHub Help: Create a repo description of creating a repository
• Open Source Guides tips for creating/description of open-source projects.
• GitHub Help: adding a pull-request template - creating a template for pull-requests.

More of my articles

• Debug in Intellij IDEA: a guide for beginners
• A guide to creating a client for the Skyscanner API and publishing it to jCenter and Maven Central [Part 1]
• A guide to creating a client for the Skyscanner API and publishing it to jCenter and Maven Central [Part 2]
• Building an Airline Price Monitoring System: A Step-by-Step Guide [Part 1]
• Building an Airline Price Monitoring System: A Step-by-Step Guide [Part 2]
• Building an Airline Price Monitoring System: A Step-by-Step Guide [Part 3]
• Logging: what, how, where and with what?
• How an interview test turned into an open-source library
• History of success. 20 hours of programming per week, master's degree and personal life
• How to find a job? Resume Distribution Tips