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

Всім привіт, JavaRush спільнота! Сьогодні поговоримо про open source і про те, що потрібно для створення якісного проекту Окрім коду, який пишеться. Важливо писати корисний продукт. Але не менш важливим є і правильне оформлення репозиторії (репозиторія проекту на GitHub). Це допоможе в реалізації ще одного ключового моменту – просування продукту. Будь проект хоч супер крутий, але якщо він погано оформлений, не описаний хоча б у README (про те, що таке README можна почитати тут), не позначено ліцензію та інше інше, успіху не буде. Просто його ніхто не помітить. А якщо хтось і помітить, не знатиме, як із ним взаємодіяти. Є багато речей, які потрібно заповнювати раз у раз, і щоразу копіпастити не з руки програмісту, і ось якраз для цього влітку цього року GitHub випустабо Template Repository фічу, яка допомагає в цьому . Так би мовити, автоматизувати процес створення нових проектів. Сьогодні розберемося із тим, що таке Repository, що таке Template Repository. Опишемо, що має бути в проекті крім коду, на які речі потрібно загострити увагу. Створимо з нуля Template Repository, додамо все необхідне на мій погляд. І, насамкінець, застосуємо Template Repository при створенні нового репозиторію. Але спершу розберемося з термінами. Теорія: що має бути в загальному репозиторії будь-якого проекту У кожному open source проекті на GitHub має бути добре описаний Community Profile , який містить такі елементи.

1. Issue template

Тут потрібно описати правила створення іссуе в репозиторії: як вони повинні називатися, якою буде label, хто буде заасайнен на нього. При створенні нового Issue, буде запропоновано такі варіанти:

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

Приклад того, як це виглядає, можна побачити тут .

2. Ліцензія

Ліцензія, під якою пишеться проект. Вона необхідна, щоб ті, хто використовуватиме проект, знали, що гарантується, а що ні. Наприклад, ліцензія 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 Help: About repositories про те, що таке репозиторії.
• GitHub Help: Як створити новий проект на основі шаблону
• 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 годин програмування на тиждень, магістратура та особисте життя
• Як знайти роботу? Поради щодо розсилки резюме