Pag-optimize ng trabaho sa iyong mga proyekto sa GitHub: pagkilala sa Github Template Repository

Kumusta sa lahat, komunidad ng JavaRush! Ngayon ay pag-uusapan natin ang tungkol sa open source at kung ano ang kinakailangan upang lumikha ng isang de-kalidad na proyekto BUKOD sa code na nakasulat. Mahalagang magsulat ng isang kapaki-pakinabang na produkto. Ngunit hindi gaanong mahalaga ang tamang disenyo ng repositoryo (imbakan ng proyekto sa GitHub). Makakatulong ito sa pagpapatupad ng isa pang mahalagang punto - promosyon ng produkto. Kahit na ang proyekto ay sobrang cool, ngunit kung ito ay hindi maganda ang disenyo, ay hindi inilarawan ng hindi bababa sa README (maaari mong basahin ang tungkol sa kung ano ang isang README dito ), ang lisensya ay hindi ipinahiwatig, atbp., atbp., magkakaroon ng walang tagumpay. Kaya lang walang makakapansin sa kanya. At kung may makapansin, hindi nila malalaman kung paano makihalubilo sa kanya. Maraming bagay ang kailangang punan nang paulit-ulit, at hindi madali para sa programmer na kopyahin at i-paste sa bawat pagkakataon, at para lang dito, ngayong tag-init, inilabas ng GitHub ang tampok na Template Repository na tumutulong dito. Kaya't magsalita, upang i-automate ang proseso ng paglikha ng mga bagong proyekto. Ngayon ay mauunawaan natin kung ano ang isang Repository at kung ano ang isang Template Repository. Ilalarawan namin kung ano ang dapat sa proyekto bukod sa code, kung ano ang mga bagay na kailangan mong pagtuunan ng pansin. Gumawa tayo ng isang Template Repository mula sa simula at idagdag ang lahat ng kailangan mula sa aking pananaw. At panghuli, gagamitin namin ang Template Repository kapag gumagawa ng bagong repository. Ngunit una, unawain natin ang mga tuntunin. Teorya: kung ano ang dapat na nasa pangkalahatang imbakan ng anumang proyekto Ang bawat open source na proyekto sa GitHub ay dapat na may mahusay na inilarawang Profile ng Komunidad , na naglalaman ng mga sumusunod na elemento.

1. Template ng isyu

Dito kailangan mong ilarawan ang mga patakaran para sa paglikha ng isang isyu sa repositoryo: kung ano ang dapat itawag sa kanila, kung ano ang magiging label, kung sino ang itatalaga dito. Kapag gumagawa ng bagong Isyu, iaalok ang mga sumusunod na opsyon:

• Ulat ng bug - paglikha ng isang isyu upang ilarawan ang isang depekto sa proyekto;
• Kahilingan sa tampok - panukala ng isang bagong ideya para sa isang proyekto;
• Kahilingan sa pagpapabuti - panukala para sa pagpapabuti sa proyekto;
• Custom na template ng isyu - kung hindi gumana ang ibang mga opsyon, maaari kang gumamit ng walang laman na template.

Isang halimbawa ng kung ano ang hitsura nito ay makikita dito .

2. Lisensya

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

3. README

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   Name file должно быть следующее: .github/pull_request_template.md.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Организация со всеми шаблонами, которые я создал
• GitHub Blog: Generate new repository with repository templates How создать шаблон для репозиториев
• GitHub Help: About repositories о том, что такое репозитории.
• GitHub Help: Creating a repository from a template How создать новый проект на основе шаблона
• 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]
• Creation системы мониторинга цен на авиабилеты: пошаговое руководство [Часть 1]
• Creation системы мониторинга цен на авиабилеты: пошаговое руководство [Часть 2]
• Creation системы мониторинга цен на авиабилеты: пошаговое руководство [Часть 3]
• Логирование: что, How, где и чем?
• Как тестовое задание на собеседование превратилось в open-source библиотеку
• История Успеха. 20 часов программирования в неделю, магистратура и личная жизнь
• Как найти работу? Советы по рассылке резюме