Optimizing work with your projects on GitHub: getting acquainted with Github Template Repository

Hello everyone, JavaRush community! Today we’ll talk about open source and what it takes to create a high-quality project IN ADDITION to the code that is 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 implementing another key point - product promotion. Even if the project is super cool, but if it is poorly designed, is not described at least in the README (you can read about what a README is here ), the license is not indicated, etc., etc., there will be no success. It's just that no one will notice him. And if someone notices, they won’t know how to interact with him. There are a lot of things that need to be filled out over and over again, and it’s not easy for the programmer to copy and paste each time, 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 understand what a Repository is and what a Template Repository is. We will describe what should be in the project besides the code, what things you need to focus on. Let's create a Template Repository from scratch and add everything necessary from my point of view. And finally, we will use Template Repository when creating a new repository. But first, let's understand 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: what 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 to describe a defect in the project;
• Feature request - proposal of a new idea for a project;
• Improvement request - proposal for improvement on the project;
• Custom issue template - if other options do not work, 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 calling 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 launch a project, what is needed for this;
• Troubleshooting - this describes what problems you may encounter and how to solve them;
• Release Notes - description of changes depending on the version;
• Authors - don’t forget about your 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 - a file in which all changes for new versions are recorded. It’s a good practice to put this in a separate document and store a link in the README;
• CONTRIBUTING is 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 they say, let's move from words to action. Now, using an example, I will show you how to create your own template.

1. The first thing you need is an account on GitHub / register there .

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

3. When creating, fill in:

   • Repository name - in my case repository-template;
   • Description — brief description of the project;
   • We leave Public, although you can select Private;
   • Check the README initialization box:

   • Select the license under which the project will be:

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

     Therefore, click Create Repository , thereby completing the creation process. The system will automatically take us to the newly created repository.

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

   As you can see, all that remains is 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 a project.

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

   I select the first one and click Review and Submit .

   Next, you can edit this file and commit it.

   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 Code of Conduct is marked as added:

   Contributing and Issue Template are added in a similar way, so I won’t show this. Do it yourself ;)

5. Add Pull Request template .

   But let's talk about this separately.

   I don’t know why GitHub hasn’t added the same convenient option for setting up the Pull-Request template, so you’ll have to study the documentation and add it manually.

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

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

   We add what we need to the template and click Commit new file , as we did above. I wasn't going to reinvent the wheel and found an example that seemed quite usable to me.

   This way the entire Community Profile will be filled in:

6. Add a 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. This will also help you not to miss important details, since it often happens that you forget to add something, for example a license or a clear template for an issue.

How to use Template Repository

There are two options for use:

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

2. When the template is foreign: there are no special problems here either. Go to that template and click the Use this template button . Here I will use the animation from the official doc:

Let's sum it up

In this article we looked at:

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

Of course, based on this template, you can already create more specific ones. For example, I created more templates with maven or gradle build systems already configured. 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. Subscribe to my GitHub account

useful links

• Organization with all the templates I created
• GitHub Blog: Generate new repository with repository templates how to create a template for repositories
• GitHub Help: About repositories about what repositories are.
• GitHub Help: Creating a repository from a template how to create a new project based on 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/describing 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
• Guide to creating a client for the Skyscanner API and publishing it in jCenter and Maven Central [Part 1]
• Guide to creating a client for the Skyscanner API and publishing it in jCenter and Maven Central [Part 2]
• Creating an air ticket price monitoring system: a step-by-step guide [Part 1]
• Creating an air ticket price monitoring system: a step-by-step guide [Part 2]
• Creating an air ticket 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? Tips for sending out resumes