Оптимизируем работу со своими проектами на GitHub: знакомство с Github Template Repository

Всем привет, JavaRush сообщество! Сегодня поговорим об open source и о том, что нужно для создания качественного проекта ПОМИМО кода, который пишется. Важно писать полезный продукт. Но не менее важно и правильное оформление repository (репозитория проекта на GitHub). Это поможет в реализации еще одного ключевого момента — продвижении продукта. Будь проект хоть супер крутой, но если он плохо оформлен, не описан хотя бы в README(о том что такое README можно почитать здесь), не обозначена лицензия и прочее прочее прочее, успеха не будет. Просто его никто не заметит. А если кто-то и заметит, не будет знать, как с ним взаимодействовать. Есть много вещей, которые нужно заполнять из раза в раз, и каждый раз копипастить не с руки программисту, и вот как раз для этого летом этого года GitHub выпустили Template Repository фичу, которая помогает в этом. Так сказать, автоматизировать процесс создания новых проектов. Сегодня разберемся с тем, что такое Repository, что такое Template Repository. Опишем что должно быть в проекте помимо кода, на какие вещи нужно заострить внимание. Создадим с нуля Template Repository, добавим все необходимое с моей точки зрения. И, в конце, применим Template Repository при создании нового репозитория. Но сперва разберемся с терминами. Теория: что должно быть в общем репозитории любого проектаВ каждом open source проекте на GitHub должен быть хорошо описан Community Profile, который содержит следующие элементы.

1. Issue template

Здесь нужно описать правила создания issue в репозитории: как они должны называться, какой будет label, кто будет заасайнен на него. При создании нового Issue, будут предложены такие варианты:

• Bug report — создание issue с целью описать дефект на проекте;
• Feature request — предложение новой идеи для проекта;
• Improvement request — предложение по улучшению на проекте;
• Custom issue template — если другие варианты не подошли, можно использовать пустой шаблон.

Пример того, как это выглядит, можно посмотреть здесь.

2. License

Лицензия, под которой пишется проект. Она необходима, чтобы те, кто будет использовать проект, знали что гарантируется, а что нет. Например, лицензия Apache License 2.0 говорит следующее:

3. README

Это описание проекта, его визитная карточка. Всё, что нужно сказать о проекте, должно быть здесь. Разумеется, его нужно будет описывать каждый раз, учитывая специфику проекта, но заголовки будут одни и те же. Например:

• Overview — краткое описание проекта;
• Usage — как использовать проект;
• Building — как запустить проект, что для этого нужно;
• Troubleshooting — здесь описывается то, с какими проблемами можно столкнуться и как их решить;
• Release Notes — описание изменений в зависимости от версии;
• Authors — не забываем и о себе любимых;
• Contributing — описание того, как можно поучаствовать в разработке проекта;
• Code of Conduct — описание правил участия;
• RELEASE_NOTES — файл, в котором записываются все изменения для новых версий. Хорошая практика вынести это в отдельный документ, а в README хранить ссылку для перехода;
• CONTRIBUTING — файл, в котором описано, как можно внести вклад в развитие этого проекта. Сделан как отдельный файл для Contributing заголовка в README;
• CODE_OF_CONDUCT — файл, в котором описаны правила для участия в развитии проекта;
• Pull Request template — шаблон для тех, кто будет создавать pull-request.

Все эти вещи используются от проекта к проекту независимо ни от языка программирования, ни от его специфики.

Практика: создаем свой собственный шаблон

Как говорится, от слов переходим к делу. Сейчас на примере я покажу, как создать собственный шаблон.

1. Первое, что понадобится — аккаунт на GitHub / зарегистроваться там.

2. Создаем новый репозиторий: для этого в верхнем правом углу нажимаем +

3. При создании заполняем:

   • Repository name — в моем случае repository-template;
   • Description — краткое описание проекта;
   • оставляем Public, хотя можно выбрать и Private;
   • Ставим галочку инициализации README:

   • Выбираем лицензию, под которой будет проект:

     Так как в моем случае шаблон общий, то и gitignore не нужен: он будет добавлен уже для конкретного проекта и языка программирования.

     Поэтому нажимаем Create Repository, тем самым завершая процесс создания. Система автоматически перенесет нас в свежесозданный репозиторий.

4. Заполнение Community Profile: в созданном репозитории заходим во вкладку Insights и выбираем Community:

   Как видим, осталось заполнить Code of Conduce, Contributing, Issue Template, Pull Request template.

   На примере с Code of Conduct покажем, как добавить их на проект.

   Нажимаем add, система предлагает выбрать Contributor Covenant или Citizen Code of Conduct:

   Я выбираю первое и нажимаю Review and Submit.

   Далее, можно будет отредактировать этот файл и уже закоммитить.

   Внизу выбираем опцию Commit directly to the master branch и нажимаем Commit new file:

   В итоге, если перейдем обратно в Community Profile, обнаружим, что Code of Conduct помечен как добавленный:

   Contributing и Issue Template добавляется аналогичным образом, поэтому показывать этого не буду. Сделайте сами ;)

5. Добавляем Pull Request template.

   А вот об этом поговорим отдельно.

   Не знаю, по какой причине GitHub не добавил такую же удобную опцию для настройки шаблона Pull-Request’ов, поэтому придется изучить мурзилку документацию и руками добавить.

   Для этого в корне репозитория нажимаем Create new file:

   Имя файла должно быть следующее: .github/pull_request_template.md.

   Добавляем что нужно в шаблон и нажимаем Commit new file, как уже делали выше. Я не собирался изобретать велосипед и нашел пример, который мне показался вполне используемым.

   Таким образом, весь Community Profile будет заполнен:

6. Добавляем маркер Template Repository.

   Для этого нужно перейти в опцию Settings в репозитории и поставить галочку там, где написано Template Repository:

   И всё, шаблон для создания новых проектов готов. Тем самым мы сохраним кучу времени в будущем, когда нужно будет создавать новые проекты. А еще это поможет не пропустить важные детали, так как часто бывает, что забываешь что-то добавить, например лицензию или понятный шаблон для issue.

Как использовать Template Repository

В использовании есть два варианта:

1. Когда шаблон принадлежит непосредственно вам: при создании нового репозитория будет предоставлена опция создании на основе шаблона из списка принадлежащих вам шаблонов:

2. Когда шаблон чужой: здесь тоже нет особых проблем. Переходим на тот шаблон и нажимаем кнопку Use this template. Здесь я воспользуюсь анимацией из официальной доки:

Подведем итоги

В этой статье мы разобрали:

• что такое GitHub repository;
• что такое Template repository;
• что должно быть в Template repository;
• как создать Template Repository;
• как использовать Template Repository.

Разумеется, на основании этого шаблона уже можно создавать более конкретные. Например я создал еще шаблоны уже с настроенными maven или gradle системами сборки. Дальше больше: можно на основании последних двух создать Spring Boot Repository Template. Чтобы сгруппировать все шаблоны, я создал template-repository организацию в GitHub со всеми шаблонами. Подписывайтесь на мой GitHub аккаунт

Полезные ссылки

• Организация со всеми шаблонами, которые я создал
• GitHub Blog: Generate new repository with repository templates как создать шаблон для репозиториев
• GitHub Help: About repositories о том, что такое репозитории.
• GitHub Help: Creating a repository from a template как создать новый проект на основе шаблона
• GitHub Help: Licensing a repository описание лицензирования для проектов
• GitHub Help: Create a repo описание создания репозитория
• Open Source Guides советы по созданию/описанию open-source проектов.
• GitHub Help: adding a pull-request template - создание шаблона для pull-request’ов.

Еще мои статьи

• Debug в Intellij IDEA: гайд для новичков
• Гайд по созданию клиента для Skyscanner API и его публикации в jCenter и Maven Central [Часть 1]
• Гайд по созданию клиента для Skyscanner API и его публикации в jCenter и Maven Central [Часть 2]
• Создание системы мониторинга цен на авиабилеты: пошаговое руководство [Часть 1]
• Создание системы мониторинга цен на авиабилеты: пошаговое руководство [Часть 2]
• Создание системы мониторинга цен на авиабилеты: пошаговое руководство [Часть 3]
• Логирование: что, как, где и чем?
• Как тестовое задание на собеседование превратилось в open-source библиотеку
• История Успеха. 20 часов программирования в неделю, магистратура и личная жизнь
• Как найти работу? Советы по рассылке резюме