GitHub для разработчика: основы и рабочие практики

Как устроен GitHub: репозитории, профили и основные термины

GitHub — это платформа для хостинга Git‑репозиториев и совместной разработки. Важно разделять два слоя:

Git — система контроля версий (локально у вас на компьютере).

GitHub — сервис, который хранит репозитории в облаке, даёт интерфейс для команды и дополняет Git инструментами (обсуждения, ревью, автоматизация).

Ниже — «карта местности», чтобы уверенно ориентироваться в интерфейсе и терминологии.

Аккаунт и профиль

Аккаунт

Аккаунт — ваша учётная запись: логин, почта, настройки безопасности, токены, ключи, уведомления. С точки зрения прав доступа аккаунт — это то, «кто вы» на платформе.

Профиль

Профиль — публичная (или частично публичная) витрина аккаунта. Обычно включает:

аватар, имя, био, местоположение;

список репозиториев и вкладки активности;

Pinned repositories — закреплённые репозитории (показывают важные проекты);

граф активности (contributions): коммиты, PR, issues и т. п.

Отдельный элемент — Profile README: специальный README, который отображается прямо в профиле. Это удобное место для краткого представления, ссылок на проекты и правил контакта.

Репозиторий: главный объект на GitHub

Репозиторий (repository, repo) — это «папка проекта» с историей изменений (Git) и набором функций GitHub вокруг неё.

Что обычно есть в репозитории:

файлы проекта и их история;

ветки и теги;

разделы для обсуждения и работы: issues, pull requests;

настройки доступа и автоматизации.

Владелец репозитория: user vs organization

Репозиторий всегда принадлежит какому-то владельцу:

User — репозиторий в вашем личном пространстве.

Organization — репозиторий в пространстве организации (компании/сообщества). Там чаще настраивают команды, роли и политики.

Публичность репозитория

Public — виден всем.

Private — виден только тем, кому вы выдали доступ.

Это влияет на аудиторию, но не отменяет того факта, что внутри могут быть свои правила доступа: кто может писать, кто — только читать.

Как читать страницу репозитория

Визуально репозиторий на GitHub можно представить так:

Не во всех репозиториях включены все вкладки — часть функций можно отключать.

Файлы, которые часто встречаются

README.md — «входная точка» проекта: что это, как запустить, как контрибьютить.

LICENSE — лицензия (правила использования кода).

.gitignore — список файлов, которые не нужно добавлять в Git (например, временные файлы IDE).

CONTRIBUTING — правила участия (как оформлять изменения, где обсуждать).

CODEOWNERS — кто отвечает за определённые части кода (часто влияет на обязательных ревьюеров).

Ключевые термины GitHub (коротко)

Commit (коммит)

Запись об изменении в истории. Коммит — это «атомарный шаг» с автором, временем и сообщением.

Branch (ветка)

Параллельная линия разработки. Обычно есть default branch (часто main), от которой создают рабочие ветки.

Tag (тег)

Метка на конкретном коммите. Часто используют для версий: v1.0.0.

Release (релиз)

Оформленная публикация версии проекта на GitHub. Часто привязана к тегу и содержит описание изменений и артефакты.

Issue

Единица работы: баг, задача, идея, вопрос. У issue есть комментарии, метки (labels), исполнитель (assignee), сроки (milestones — если используются).

Pull Request (PR)

Запрос на внесение изменений из одной ветки в другую. PR — это место для обсуждения, проверок и ревью перед слиянием.

Review (ревью)

Проверка PR другими участниками: комментарии, запросы на правки, одобрение.

Merge (слияние)

Применение изменений из PR в целевую ветку. Политики мерджа и требования (например, «нужны 2 одобрения») задаются в настройках.

Fork (форк)

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

Star и Watch

Star — «мне нравится/в закладки» (сигнал популярности и личная коллекция).

Watch — подписка на уведомления о событиях репозитория (issues, PR, релизы и т. д.).

Права доступа и роли (самое необходимое)

Доступ к репозиторию может быть настроен на уровне:

Репозитория (кому можно читать/писать/администрировать).

Организации (команды, политики).

В общих чертах роли различаются тем, кто может:

просто читать код;

предлагать изменения (через PR);

напрямую пушить в репозиторий;

менять настройки, управлять доступами и правилами.

Мини‑проверка понимания

1) Что является «центром» проекта на GitHub — профиль или репозиторий? 2) Чем fork отличается от clone? 3) Зачем проекту README и LICENSE?

---

Задания для закрепления

1. Термины на соответствие

Соотнесите понятия и описание:

Issue

Pull request

Tag

Fork

A. Копия репозитория в вашем аккаунте B. Запрос на внесение изменений с обсуждением и ревью C. Задача/обсуждение/баг D. Метка версии на коммите

<details> <summary> Ответ </summary>

1–C, 2–B, 3–D, 4–A

</details>

2. Ситуационная задача

У вас нет прав на запись в репозиторий проекта, но вы хотите предложить исправление. Какие два шага наиболее типичны на GitHub?

<details> <summary> Ответ </summary>

1) Сделать fork репозитория в свой аккаунт. 2) Внести изменения у себя и открыть pull request в исходный репозиторий.

</details>

3. Быстрый аудит репозитория

Вы открыли репозиторий и хотите понять, насколько он «живой» и пригоден для использования. Назовите 4 сигнала, на которые стоит посмотреть на странице репозитория.

<details> <summary> Возможный ответ </summary>

1) README (есть ли описание, установка, примеры). 2) Issues/PR: активность, скорость ответов, наличие шаблонов. 3) Releases/Tags: есть ли версии и история изменений. 4) Дата последних коммитов/обновлений и наличие CI в Actions (если используется).

</details>

4. Настройка профиля

Назовите 3 элемента профиля, которые помогают другим быстро понять вашу специализацию и проекты.

<details> <summary> Возможный ответ </summary>

1) Краткое био (роль/стек). 2) Закреплённые репозитории (Pinned). 3) Profile README (кто вы, что делаете, как связаться, ссылки на ключевые проекты).

</details>

Создание и настройка репозитория: README, лицензия, .gitignore

В предыдущей статье мы разобрали, что такое репозиторий и какие файлы в нём встречаются. Здесь — практика: как создать репозиторий на GitHub и сразу настроить три вещи, которые определяют «первое впечатление» и удобство работы: README, лицензию и .gitignore.

1) Создаём репозиторий на GitHub (минимально правильно)

При создании репозитория вы обычно выбираете:

Название — короткое и понятное (api-gateway, cv, telegram-bot-demo).

Public/Private — зависит от того, должен ли код быть виден всем.

Initialize this repository (инициализация):

1. добавлять ли README сразу; 2. выбрать ли .gitignore из шаблонов; 3. выбрать ли LICENSE.

Практическое правило:

Если проект новый и у вас ещё нет локального репозитория — удобно инициализировать на GitHub с README/.gitignore/license.

Если проект уже существует локально — создайте пустой репозиторий на GitHub и добавьте файлы у себя, затем запушьте.

Чтобы репозиторий выглядел «живым» и понятным, заполните также:

Description — 1–2 предложения: что делает проект.

Topics — ключевые слова (поиск и навигация).

2) README: контракт с пользователем и будущим вами

README — не формальность. Это «входная точка»: по нему понимают, стоит ли проект запускать, использовать или ревьюить.

Базовая структура README

Ниже — безопасный шаблон, который подходит почти всем типам репозиториев:

Частые ошибки в README

README начинается с абзаца «Это мой проект…» без конкретики (что делает? как запустить?).

Нет раздела Быстрый старт — новичок не может проверить, что всё работает.

Команды/инструкции не соответствуют реальности (README устаревает — обновляйте вместе с изменениями).

Нет указания на секреты: люди случайно коммитят токены, потому что не знают, где хранить конфиг.

Практика: держите README коротким, а подробную документацию выносите в отдельные файлы (например, docs/), если она разрастается.

3) LICENSE: что другим разрешено делать с кодом

Лицензия отвечает на вопрос: «Можно ли использовать ваш код и на каких условиях?» Если лицензии нет, людям и компаниям часто проще не трогать ваш код, чтобы не рисковать.

Как выбрать лицензию (быстрый ориентир)

MIT — простая и очень распространённая: разрешает использовать/изменять/распространять с сохранением текста лицензии.

Apache-2.0 — похожа на MIT, но с более явными условиями по патентам (часто выбирают компании).

GPL (copyleft) — производные работы обычно обязаны распространяться на тех же условиях (подходит, если хотите, чтобы улучшения оставались открытыми).

Proprietary/All rights reserved — если вы не хотите разрешать использование кода (обычно для закрытых проектов). На GitHub такие репозитории тоже бывают.

Практические правила

Лицензию выбирают в начале, чтобы потом не разбираться с правами на уже принятые чужие контрибьюции.

Если вы копируете код/шаблоны — убедитесь, что их лицензия совместима с вашей.

Файл лицензии принято называть LICENSE (без расширения) и хранить в корне репозитория.

4) .gitignore: защита истории от мусора и случайных утечек

.gitignore — список файлов и папок, которые Git не должен добавлять в репозиторий.

Что обычно нужно игнорировать

Артефакты сборки и временные файлы (dist/, build/).

Зависимости, которые можно восстановить (часто node_modules/, кэши менеджеров пакетов — зависит от экосистемы).

Файлы IDE/ОС (.idea/, .vscode/, .DS_Store).

Локальные конфиги окружения (.env, *.local).

Пример минимального .gitignore (смысловой, без привязки к языку):

Важные нюансы

.gitignore не удаляет уже отслеживаемые файлы. Если вы случайно закоммитили секрет, добавление его в .gitignore не «спрячет» его из истории.

Секреты не должны попадать в репозиторий. .gitignore помогает, но не заменяет дисциплину и проверку.

Если вам нужна пустая папка в репозитории, Git её не хранит. Обычно добавляют файл-заглушку (например, .gitkeep) внутри папки.

Мини‑чеклист «репозиторий готов к работе»

Есть README с быстрым стартом.

Есть LICENSE (или явно принято решение её не добавлять).

Есть .gitignore, который исключает временные файлы и локальные секреты.

У репозитория заполнено описание и темы.

---

Задания для закрепления

1) Разберите ситуацию

Вы создали репозиторий, но коллега говорит: «Я не понимаю, как это запустить». Назовите 3 раздела README, которые нужно добавить/улучшить в первую очередь.

<details> <summary> Ответ </summary>

1) «Быстрый старт» (требования + шаги запуска). 2) «Конфигурация» (где задаются переменные окружения, какие обязательны). 3) «Использование» (минимальный пример сценария, чтобы проверить результат).

</details>

2) Выбор лицензии

Сопоставьте желание автора и тип лицензии:

«Хочу, чтобы код могли свободно использовать даже в коммерческих продуктах, минимум ограничений»

«Хочу, чтобы улучшения распространялись на тех же условиях и оставались открытыми»

«Хочу больше формальностей и явные условия по патентам»

A. Apache-2.0 B. GPL C. MIT

<details> <summary> Ответ </summary>

1–C, 2–B, 3–A

</details>

3) .gitignore на практике

Назовите 4 категории файлов, которые чаще всего стоит добавить в .gitignore в любом проекте (без привязки к языку).

<details> <summary> Ответ </summary>

1) Временные файлы ОС и IDE. 2) Артефакты сборки/генерации. 3) Кэши/локальные базы/временные каталоги инструментов. 4) Локальные конфигурации и файлы с секретами (например, .env).

</details>

4) Ошибка: секрет уже в репозитории

Вы случайно закоммитили файл .env с токеном и только потом добавили его в .gitignore. Что из этого верно?

Теперь токен точно не виден в репозитории.

.gitignore не убирает файл из истории.

Нужно считать токен скомпрометированным.

<details> <summary> Ответ </summary>

Верны 2 и 3. Добавление в .gitignore не удаляет уже закоммиченное, а токен нужно отозвать/заменить.

</details>

Рабочий процесс с ветками: commit, push, pull и merge

В предыдущих статьях мы разобрали, что такое репозиторий, ветки, коммиты и pull request на уровне терминов. Здесь — практический рабочий процесс: как изменения проходят путь от вашей машины до общей ветки команды.

1) Модель «локально ↔ удалённо»

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

Локальный (у вас на компьютере): здесь вы редактируете файлы, делаете коммиты.

Удалённый (на GitHub, обычно origin): сюда вы отправляете изменения и отсюда забираете обновления.

Визуально:

2) Базовый сценарий работы с веткой

Самая распространённая схема в командах: в main напрямую не пушим, работаем в отдельных ветках и вливаем через PR.

Шаг 0. Обновить базу

Перед началом работы убедитесь, что ваша локальная main не устарела:

git pull делает два действия: забирает изменения с GitHub и применяет их к вашей текущей ветке.

Шаг 1. Создать рабочую ветку

От актуальной main создаём ветку под задачу:

Именование — часть дисциплины. Хорошие паттерны:

feature/... — новая функциональность

fix/... — исправление

chore/... — техдолг/обслуживание

Шаг 2. Делать коммиты (маленькие и понятные)

Коммит — это не «сохранение на всякий случай», а логический шаг.

Практические правила:

Коммит должен быть атомарным: одна идея/одно изменение.

Сообщение коммита должно объяснять зачем, а не только что.

Не смешивайте форматирование, рефакторинг и функциональные изменения в один коммит — это усложняет ревью.

Типовой цикл:

Шаг 3. Отправить ветку на GitHub (push)

Первый пуш новой ветки:

Флаг -u (upstream) «привязывает» вашу локальную ветку к удалённой. После этого достаточно:

Шаг 4. Подтянуть изменения (pull) и не сломать себе жизнь

Пока вы работаете, main на GitHub может обновляться. Чтобы не получить большой конфликт в конце, полезно периодически подтягивать актуальную базу.

Вариант, который проще новичкам (через merge):

После git merge main ваша ветка содержит обновления из main. Если есть конфликт — Git попросит его решить.

Как выглядит конфликт и что делать

Конфликт возникает, когда Git не может автоматически совместить изменения.

Алгоритм:

Откройте файлы, помеченные конфликтом.

Вручную выберите итоговый вариант.

Удалите конфликтные маркеры.

Отметьте файлы как решённые и сделайте коммит.

3) Merge: что именно происходит при «слиянии»

Merge — это операция, которая объединяет историю и изменения из одной ветки в другую.

Есть два основных места, где вы встретите merge:

Локально, когда вы вливаете main в свою ветку, чтобы актуализироваться.

На GitHub, когда PR сливают в целевую ветку (обычно main).

Внутри команды важно договориться о политике:

Разрешён ли прямой merge в main (чаще нет).

Сколько approvals нужно для PR.

Какие проверки должны пройти (тесты/линтер).

4) Типовой поток через Pull Request (PR)

После push на GitHub обычно делают PR из feature/login в main.

Мини-чеклист перед открытием PR:

Ветка названа по задаче.

Коммиты не «мусорные» (без fix, wip в финале — если команда это не принимает).

Вы подтянули актуальную main (или GitHub показывает, что ветка может быть смержена без конфликтов).

Вы запустили минимальные проверки локально (если они есть).

После ревью возможны правки. Тогда цикл простой:

Вы вносите изменения.

Делаете коммит(ы).

Делаете git push.

PR обновится автоматически.

5) Частые ошибки и как их избежать

Работа в main вместо отдельной ветки. Решение: создавать ветку под каждую задачу.

Один огромный коммит на всю задачу. Решение: дробить по логике.

Редкий pull, конфликт в конце. Решение: регулярно актуализировать ветку.

Пуш «не туда» (в чужую ветку/в main). Решение: всегда проверять текущую ветку (git branch) перед push.

---

Задания для закрепления

1) Соберите правильный порядок шагов

Дано: вы хотите внести изменение в проект команды через ветку feature/search.

Расставьте шаги в правильном порядке:

git push -u origin feature/search

git switch -c feature/search

git pull

git commit -m "..."

git switch main

<details> <summary> Ответ </summary>

Правильный порядок:

1) git switch main 2) git pull 3) git switch -c feature/search 4) git commit -m "..." (после git add ...) 5) git push -u origin feature/search

</details>

2) Push vs Pull — объясните разницу

Своими словами объясните, что делают push и pull, и где находятся изменения «до» и «после».

<details> <summary> Ответ </summary>

push отправляет ваши локальные коммиты в удалённый репозиторий на GitHub (локально → удалённо).

pull забирает изменения из удалённого репозитория и применяет их к вашей текущей локальной ветке (удалённо → локально).

</details>

3) Ситуация: конфликт при merge

Вы сделали git merge main в своей ветке и получили конфликт. Перечислите 4 шага, чтобы закончить merge корректно.

<details> <summary> Ответ </summary>

1) Открыть конфликтные файлы и найти конфликтные блоки. 2) Выбрать итоговый вариант (вручную объединить изменения), удалить маркеры конфликта. 3) Добавить исправленные файлы: git add .... 4) Завершить merge коммитом: git commit (или git commit -m "Resolve conflict").

</details>

4) Мини-аудит истории

Какие два признака в истории коммитов чаще всего усложняют ревью в PR?

<details> <summary> Ответ </summary>

1) Очень крупные коммиты, в которых смешаны несвязанные изменения. 2) «Шумные» коммиты без смысла (например, wip, fix, «ещё одна попытка») — если их много и они не сквошатся/не приводятся в порядок.

</details>

Pull Request: код-ревью, проверки и разрешение конфликтов

Pull Request (PR) на GitHub — это «точка сборки» изменений: место, где код обсуждают, проверяют автоматикой и только потом вливают в целевую ветку (обычно main). Базовый поток работы с ветками (создание, commit/push, обновление от main) уже разобран в статье про рабочий процесс — здесь фокус именно на ревью, проверках и конфликтах.

1) Из чего состоит Pull Request (как объект)

PR — это не только «кнопка Merge». Внутри обычно есть:

Title и описание — зачем изменение, что сделано, как проверить.

Список коммитов и diff — фактические изменения по файлам.

Discussion/Conversation — комментарии и решения.

Review — статусы ревьюеров (approve / request changes / comment).

Checks — результаты CI/линтера/тестов и других интеграций.

Визуально:

2) Хорошее описание PR: меньше вопросов на ревью

Описание PR — это «контракт» между автором и ревьюером. Минимально полезная структура:

Контекст: какая проблема/задача решается.

Что изменено: 3–6 пунктов по сути (без перечисления файлов).

Как проверить: шаги для ручной проверки или сценарии.

Риски и обратная совместимость: что может сломаться.

Скрин/лог/артефакт: только если без этого трудно понять результат (например, UI).

Практика: если ревьюер вынужден угадывать «зачем» — ревью превращается в расследование.

3) Код-ревью: как проходит и что считается результатом

Виды комментариев

Line comments — точечно к строкам кода.

General comments — общие замечания в обсуждении.

Suggested changes — предложенная правка, которую автор может принять одной кнопкой.

Итоги ревью

Обычно встречаются три исхода:

Approve — можно мержить.

Request changes — есть блокирующие замечания (нужны правки).

Comment — замечания необязательные, «на подумать».

Важно различать:

Нитку обсуждения (thread) и её статус Resolve conversation.

Статус ревью (approve/request changes) — это итог ревьюера по PR в целом.

Как автору отвечать на замечания

Отвечайте прямо в нитке: что изменили или почему не согласны.

Если сделали правку — дайте ревьюеру быстрый ориентир: где именно.

Закрывайте обсуждения только когда вопрос реально решён.

Антипаттерн: «молча поправил и закрыл все нитки» — ревьюер теряет доверие к процессу.

4) Checks и политики: почему PR “красный” и что с этим делать

Что такое checks

Checks — это статусы автоматических проверок, чаще всего из GitHub Actions или внешних CI:

Сборка.

Тесты.

Линтер/форматтер.

Анализ безопасности/зависимостей.

У PR может быть состояние:

Branch protection: когда Merge недоступен

В репозитории могут быть правила для целевой ветки (защищённой ветки), например:

Требуются определённые checks.

Нужно N approvals.

Запрещён merge при неразрешённых обсуждениях.

Требуется «ветка актуальна с base branch».

Если кнопка Merge заблокирована — это не «ошибка GitHub», а сигнал: PR не удовлетворяет правилам.

5) Способы merge на GitHub и когда какой выбирать

Чаще всего доступны три стратегии:

Merge commit — сохраняет ветку как отдельную линию истории (видно, что был PR).

Squash and merge — превращает все коммиты PR в один коммит в целевой ветке (аккуратная история).

Rebase and merge — «перепроигрывает» коммиты поверх актуальной базы (линейная история, но меняются хэши коммитов).

Выбор обычно диктует команда (и настройки репозитория). Для новичков самый безопасный по последствиям в истории — squash, если команда так делает.

6) Конфликты в PR: причины и рабочие способы решения

Почему возникает конфликт

Конфликт появляется, когда PR и целевая ветка изменили одни и те же фрагменты так, что GitHub не может автоматически объединить.

Симптомы в PR:

Сообщение вида “This branch has conflicts that must be resolved”.

Кнопка merge недоступна.

Как правильно чинить конфликт

Есть два основных пути.

Вариант A (рекомендуемый): решить локально

Обновить локальную базовую ветку и подтянуть актуальное состояние.

Актуализировать вашу ветку относительно base (через merge или rebase — как принято в команде).

Разрешить конфликты в редакторе.

Сделать коммит “resolve conflicts” (или завершить rebase) и запушить в ту же ветку PR.

PR обновится автоматически, и конфликт исчезнет.

Вариант B: Resolve conflicts в интерфейсе GitHub

Подходит для простых конфликтов в текстовых файлах:

Открыть конфликтующий файл в PR.

Выбрать итоговый вариант вручную.

Закоммитить результат через веб-интерфейс.

Ограничения: веб-редактор неудобен для сложных конфликтов и может не подойти для бинарных/генерируемых файлов.

Частая ошибка

Разрешить конфликт «как-нибудь», лишь бы прошёл merge, не проверив поведение. После решения конфликта прогоните минимальную проверку (локально или дождитесь checks).

7) Мини-чеклист перед Merge

Все checks зелёные.

Получены нужные approvals.

Нет нерешённых обсуждений.

Нет конфликтов.

Описание PR отражает реальность (особенно “how to test”).

---

Задания для закрепления

1) Улучшите описание PR

Дано описание: «Fix bugs, update files». Напишите 4 пункта, которые стоит добавить в PR-описание, чтобы ревью было быстрым.

<details> <summary> Ответ </summary>

1) Контекст: какая именно проблема/баг и где проявлялся. 2) Что сделано: 3–5 конкретных изменений (например, “исправлена валидация”, “добавлены тесты на крайние случаи”). 3) Как проверить: шаги или сценарии (команды, страницы/эндпоинты, входные данные). 4) Риски: что может сломаться, нужна ли миграция/фича-флаг/обратная совместимость.

</details>

2) Разберите ситуации с checks

Ситуации:

Checks красные, ревьюер уже поставил Approve.

Checks зелёные, но висит “Request changes”.

Checks зелёные и Approve есть, но Merge заблокирован.

Опишите по 1–2 причины и что делать.

<details> <summary> Ответ </summary>

1) Возможные причины: тесты падают, линтер не проходит. Что делать: исправить причину падения, запушить правки, дождаться зелёных checks. 2) Возможные причины: ревьюер нашёл блокирующую проблему. Что делать: внести изменения, ответить в нитках, запросить повторное ревью. 3) Возможные причины: защищённая ветка требует ещё approvals, требуются разрешённые обсуждения, требуется актуальность ветки с base. Что делать: выполнить требования правил (добавить ревьюеров, закрыть обсуждения, обновить ветку и устранить конфликты).

</details>

3) Конфликт в PR

В PR написано: “This branch has conflicts that must be resolved”. Назовите 4 шага корректного решения конфликта (предпочтительно локально), чтобы PR стал mergeable.

<details> <summary> Ответ </summary>

1) Обновить локальную базовую ветку (например, main) до актуального состояния. 2) В вашей ветке PR подтянуть изменения базы (merge или rebase — по правилам команды). 3) Вручную разрешить конфликтующие файлы, убрать маркеры конфликта и сохранить корректный итог. 4) Завершить операцию (коммит “resolve conflicts” или завершение rebase) и запушить в ветку PR; дождаться обновления checks.

</details>

4) Выбор merge-стратегии

Соотнесите ситуацию и подходящую стратегию:

Команда хочет «чистую» историю по одному коммиту на PR.

Команда хочет видеть факт PR отдельным merge-коммитом.

Команда хочет линейную историю и готова к тому, что коммиты будут “переписаны” поверх базы.

<details> <summary> Ответ </summary>

1) Squash and merge. 2) Merge commit. 3) Rebase and merge.

</details>

Issues и Projects: планирование задач, метки, milestones и доски

Issues и Projects — это «операционная система» работы в GitHub: фиксируем работу в Issues, планируем и отслеживаем — в Projects. PR (процесс ревью и мерджа) мы уже разобрали отдельно; здесь фокус на том, как организовать поток задач так, чтобы команда не утонула в комментариях и хаосе.

1) Issue как единица работы

Issue удобно воспринимать как карточку, которая отвечает на три вопроса:

Что нужно сделать / что сломалось (описание проблемы).

Как понять, что готово (критерии готовности).

Кто и когда это делает (ответственные и сроки — если применимо).

Поля issue, которые реально помогают

Title — коротко и конкретно: «Ошибка 500 при пустом фильтре» лучше, чем «Баг в поиске».

Description — структура важнее объёма:

1. контекст; 2. шаги воспроизведения (для багов); 3. ожидаемое / фактическое поведение; 4. критерии готовности (Definition of Done); 5. при необходимости — окружение (версия, ОС, браузер).

Assignees — кто отвечает за движение задачи (не обязательно «кто будет кодить», а кто доведёт до результата).

Labels — классификация и приоритет.

Milestone — привязка к цели/релизу.

Мини-визуализация потока:

2) Метки (labels): язык навигации и приоритизации

Labels — самый дешёвый способ сделать issues «поисковыми» и управляемыми.

Практичная схема меток

Чтобы метки не превратились в свалку, делайте их категориями (2–5 меток на issue обычно достаточно):

Тип: bug, feature, chore, docs.

Приоритет: p0, p1, p2 (или high/medium/low).

Статус работы (если не используете Projects для статуса): triage, blocked, ready.

Компонент/область: api, frontend, auth, infra.

Полезное правило: если метка используется реже, чем раз в квартал, она, вероятно, лишняя.

Triage: быстрый разбор входящих задач

Triage — это короткий процесс, который делает входящий поток контролируемым:

проверить, что issue не дубликат;

уточнить формулировку/шаги/критерии готовности;

поставить метки: тип, приоритет, компонент;

решить: берём в работу сейчас / позже / закрываем.

3) Milestones: цели и «контейнеры» под релизы

Milestone — это группировка issues под общую цель (например, «v1.2», «Запуск пилота», «Стабилизация»). Он хорош, когда вам важно видеть прогресс не по одной задаче, а по пакету.

Как использовать milestones без бюрократии

Делайте milestones по результату, а не по датам в вакууме: «Релиз 1.4» понятнее, чем «Февраль».

Не кладите туда всё подряд: milestone должен быть управляемым по размеру.

Если задача не влезает — лучше вынести в следующий milestone, чем «тащить хвост».

4) Шаблоны issues: повышаем качество входящих задач

Когда issues пишут разные люди, качество сильно гуляет. Шаблоны (issue templates/forms) помогают стабилизировать ввод.

Что обычно стоит сделать:

Bug report:

1. шаги воспроизведения; 2. ожидаемо/фактически; 3. окружение; 4. логи/скриншоты (если нужно).

Feature request:

1. какую проблему решаем; 2. кого это касается; 3. критерии готовности; 4. ограничения/риски.

Task/Chore для техдолга: краткое описание + что будет считаться завершением.

Важно: шаблон не должен быть «допросником». Лучше меньше полей, но чтобы их реально заполняли.

5) Связь issues с PR: прозрачная трассировка

Чтобы из issue было понятно, что именно и где сделано:

Ссылайтесь на issue в PR (и наоборот). Тогда в карточке будет видна связанная работа.

Используйте ключевые слова автозакрытия в описании PR (например, Closes #123) — при мердже PR issue закроется автоматически.

Если работа частичная, фиксируйте это явно: «покрыли часть, остальное в #...». Это снижает шанс «потерянных хвостов».

6) Projects: доски и таблицы для управления потоком

Projects — это слой над issues/PR, который даёт представления: доска (board), таблица (table), иногда roadmap. По сути, это место, где вы управляете статусами, приоритетами и загрузкой.

Из чего состоит Project

Items — элементы проекта (issues, PR, черновики).

Fields — поля для управления:

1. Status (Todo/In progress/Done); 2. Priority; 3. Assignee; 4. Milestone или Iteration (если вы работаете спринтами); 5. пользовательские поля (например, «Компонент»).

Views — разные «окна» на одни и те же данные:

1. доска по статусам; 2. таблица для сортировки и фильтров; 3. вид «по людям» или «по приоритету».

Минимальный жизнеспособный процесс в Projects

Чтобы Projects не превратился в «декоративную доску», начните с простого:

Колонки статуса: Todo → In progress → In review → Done.

Обязательное правило: задача не может быть в In progress без назначенного ответственного.

Еженедельный ритуал на 10–15 минут:

1. убрать неактуальное; 2. переоценить приоритет; 3. проверить блокеры.

Автоматизация в Projects (без фанатизма)

Часто хватает двух автоматизаций:

Добавлять новые issues с определёнными метками в проект.

Переводить статус, когда PR переходит в ревью или мерджится (если команда этого ожидает).

Главный критерий: автоматизация должна уменьшать ручную работу, а не плодить «магические» перемещения, которые никто не понимает.

---

Задания для закрепления

1) Превратите «плохой» issue в хороший

Дано: «Не работает авторизация. Почините».

Составьте:

заголовок;

4 пункта описания;

3 подходящие метки.

<details> <summary> Ответ </summary>

Вариант:

1) Заголовок: «Ошибка 401 при логине с корректным паролем после обновления профиля»

2) Описание:

Контекст: после обновления профиля пользователь разлогинивается и не может войти снова.

Шаги: (1) залогиниться, (2) открыть профиль, (3) изменить телефон, (4) выйти, (5) попытаться войти.

Ожидаемо/фактически: ожидаемо — вход успешный; фактически — 401 с сообщением «invalid token».

Критерии готовности: вход работает, добавлен тест на сценарий, обновлён changelog/заметка (если принято).

3) Метки: bug, p0 (или high), auth.

</details>

2) Схема меток для репозитория

Предложите по 2 метки в каждой категории: тип, приоритет, компонент.

<details> <summary> Ответ </summary>

Пример:

Тип: bug, feature

Приоритет: p0, p2

Компонент: api, frontend

</details>

3) Milestone или нет?

Ситуации:

«Релиз 1.3 через две недели, в него входят 12 задач»

«Единичный мелкий рефакторинг без привязки к релизу»

«Большая цель “Стабилизация”, хотим закрыть 30 багов постепенно»

Для каждой ситуации решите: нужен milestone или достаточно меток/проекта.

<details> <summary> Ответ </summary>

1) Нужен milestone (релиз как контейнер задач). 2) Milestone обычно не нужен: достаточно метки chore и ведения в Project/поиск по меткам. 3) Нужен milestone или отдельный Project (если важен контроль пакета работ и прогресса по цели).

</details>

4) Настройте минимальную доску

Опишите:

колонки статуса;

одно правило «защиты от хаоса»;

один полезный фильтр для вида.

<details> <summary> Ответ </summary>

Пример:

1) Статусы: Todo, In progress, In review, Done. 2) Правило: в In progress можно переводить только задачи с назначенным исполнителем и приоритетом. 3) Фильтр: показывать только is:open и priority:p0,p1 (или аналог по вашим меткам/полям).

</details>

5) Трассировка работы: issue ↔ PR

Вы сделали PR, который полностью закрывает issue #48. Что добавить в описание PR, чтобы issue закрылся автоматически при мердже?

<details> <summary> Ответ </summary>

Добавить строку вида: Closes #48 (или эквивалент с ключевым словом автозакрытия).

</details>

Совместная работа: доступы, команды, форки и вклад в open source

Совместная разработка на GitHub сводится к двум моделям:

Вы — участник репозитория (у вас есть доступ на запись) → работаете в ветках и открываете PR.

Вы — внешний участник (прав на запись нет) → работаете через fork и открываете PR из своего форка.

Ревью, проверки и жизненный цикл PR/issue уже разобраны в предыдущих статьях; здесь — как устроены права, командная структура и вклад без доступа.

1) Модели доступа: кто и как может вносить изменения

Прямой доступ (collaborators / org members)

Если вы внутри команды, вам могут дать права на репозиторий напрямую или через организацию.

Практический принцип: минимально достаточные права. Чем меньше людей может “писать куда угодно”, тем проще защищать main и поддерживать качество.

Типовой рабочий контур выглядит так:

Вклад без доступа (fork-based)

Если репозиторий чужой или закрыт на запись, стандартный путь — fork → ветка → PR.

Это не “обход”, а нормальная модель безопасности: вы предлагаете изменения, а мейнтейнеры решают, принимать ли их.

2) Роли и разрешения: что важно понимать

Названия ролей могут немного отличаться (особенно в организациях), но смысл обычно такой:

Read — читать код и обсуждения.

Triage — разбирать issues (метки, приоритеты), но не обязательно менять код.

Write — пушить в репозиторий, создавать ветки, работать с PR.

Maintain — управлять настройками репозитория без полного администрирования.

Admin — полный контроль: доступы, правила, интеграции, защищённые ветки.

Практические выводы:

Write ≠ право мержить в main. Часто main защищён, и мердж возможен только при выполнении правил (ревью/проверки).

Triage полезна в больших проектах: разгружает мейнтейнеров, улучшает качество входящих issues.

Раздавать Admin “на всякий случай” — плохая идея: это повышает риск случайных изменений в правилах и доступах.

3) Команды в организации (Teams): зачем они нужны

В организации права удобнее выдавать не людям по одному, а командам.

Что дают Teams:

Управляемость: добавили человека в команду — он автоматически получил нужные доступы.

Единая модель ответственности: команда “владеет” областями кода.

Ревью по правилам: можно настроить, чтобы PR требовал ревью определённой команды (часто через CODEOWNERS).

Минимальная рабочая схема:

Команда devs — write.

Команда maintainers — maintain/admin.

Владение кодом: кто обязан ревьюить какие папки.

4) Форк на практике: как не отстать от оригинала

Когда вы сделали fork, у вас появляется своя копия репозитория. Важно помнить: оригинал продолжает развиваться, и ваш форк может устареть.

Термины (практические):

origin — ваш форк (куда вы пушите).

upstream — оригинальный репозиторий (откуда вы подтягиваете изменения).

Визуально:

Типовой цикл обновления форка:

Подключить upstream (делается один раз).

Периодически подтягивать upstream/main к себе.

Обновлять свою ветку, чтобы PR не конфликтовал.

Командный нюанс: если в проекте принято “держать PR актуальным с base”, обновление форка — обязательная часть работы.

5) Вклад в open source: что ожидают мейнтейнеры

Open source — это не только код, но и процесс. Часто PR отклоняют не из-за “плохого кода”, а из-за несоответствия правилам проекта.

Перед тем как писать код

Прочитайте README и правила контрибьюта (часто CONTRIBUTING).

Проверьте, нет ли уже issue/PR на эту тему.

Для больших изменений сначала обсудите идею в issue.

Как сделать PR “дружелюбным”

Держите изменения узкими: один PR — одна цель.

Опишите контекст и способ проверки (см. статью про PR).

Не ломайте стиль проекта: форматирование, линтеры, тесты.

Добавляйте тесты, если в проекте это принято.

Частые требования проектов

CLA/DCO: юридическое подтверждение права на вклад. Если проект просит — без этого не примут.

Code of Conduct: правила общения. Нарушение тона/этики может закрыть вам путь в проект даже при хорошем коде.

Security policy: уязвимости часто нельзя публиковать в issues — для этого есть отдельный процесс.

Ошибка новичка

“Я сделал большую правку, но её не мержат”. Частая причина — мейнтейнерам сложно ревьюить огромный дифф. Лучше разбивать работу на небольшие, автономные PR.

6) Практика для команды: правила, которые экономят время

Не давать прямой push в main, даже опытным: только PR.

Назначать ответственного (assignee) на issue/PR, чтобы было понятно, кто “ведёт” задачу.

CODEOWNERS/обязательные ревьюеры для критичных частей (auth, платежи, инфраструктура).

Единая договорённость по мерджу (squash/merge/rebase) — чтобы история была предсказуемой.

---

Задания для закрепления

1) Выберите правильную модель

Ситуации:

Вы сотрудник команды, у вас есть доступ write, проект защищает main.

Вы хотите исправить опечатку в чужом репозитории, доступа на запись нет.

Выберите подходящий путь для каждой ситуации:

A. Fork → ветка → PR в оригинальный репозиторий B. Ветка в основном репозитории → PR

<details> <summary> Ответ </summary>

1 — B (вы внутри репозитория, работаете через ветку и PR). 2 — A (нет доступа на запись, стандартный путь через fork).

</details>

2) Мини-сценарий про права

В репозитории участнику выдали admin, потому что “так проще”. Назовите 2 риска такого решения и 1 более безопасную альтернативу.

<details> <summary> Ответ </summary>

Риски:

Можно случайно/неправильно изменить правила защищённых веток и сломать процесс мерджа.

Можно выдать доступ посторонним или удалить важные настройки (секреты CI, интеграции).

Альтернатива:

Дать write (или maintain для ответственного мейнтейнера) и оставить admin ограниченному кругу.

</details>

3) Обновление форка

Объясните своими словами, что обычно означают origin и upstream в fork-based работе.

<details> <summary> Ответ </summary>

origin — ваш репозиторий- форк, куда вы пушите свои ветки.

upstream — оригинальный репозиторий проекта, откуда вы подтягиваете изменения, чтобы не отстать от основной ветки.

</details>

4) Open source: что сделать до PR

Перечислите 3 действия, которые стоит сделать до начала разработки, чтобы повысить шанс принятия PR.

<details> <summary> Ответ </summary>

Прочитать правила контрибьюта (например, CONTRIBUTING) и требования к стилю/тестам.

Проверить существующие issues/PR, чтобы не дублировать работу.

Обсудить идею в issue (особенно если изменение большое или спорное).

</details>

GitHub Actions: основы CI/CD и запуск автоматических проверок

GitHub Actions — встроенный механизм автоматизации на GitHub. Чаще всего его используют как CI/CD:

CI (Continuous Integration) — автоматические проверки при изменениях (сборка, тесты, линтер).

CD (Continuous Delivery/Deployment) — доставка артефактов и (иногда) деплой после успешных проверок.

В статье про Pull Request мы уже говорили, что checks могут блокировать merge. GitHub Actions — самый распространённый источник этих checks.

1) Базовые сущности Actions

Workflow (рабочий процесс)

Workflow — набор правил и шагов, описанный в YAML-файле в репозитории:

путь: .github/workflows/<name>.yml

запускается по событиям (push, PR, вручную и т. п.)

Event (событие)

Событие — «триггер», который запускает workflow. На практике чаще всего:

pull_request — проверки PR.

push — проверки при пуше в ветки.

workflow_dispatch — ручной запуск кнопкой.

schedule — запуск по расписанию.

Runner (исполнитель)

Runner — машина, где выполняются шаги.

GitHub-hosted — виртуальные машины от GitHub (быстрый старт).

Self-hosted — ваши сервера/агенты (нужно, если особая инфраструктура или доступ во внутреннюю сеть).

Jobs и steps

Workflow состоит из jobs, а каждый job — из steps.

Job — логическая единица (например, «тесты», «линтер», «сборка»).

Step — конкретная команда или подключение готового action.

Важная особенность: jobs по умолчанию выполняются параллельно, а steps — последовательно.

2) Минимальный workflow для CI

Типовая цель: проверять ветки и PR автоматически.

Пример простого workflow (скелет):

Как это читать:

name — имя workflow в интерфейсе Actions.

on — когда запускать (на PR и на push в main).

jobs.test — job с названием test.

runs-on — окружение runner.

steps:

1. uses — подключение готового action (например, checkout кода). 2. run — выполнение команд в shell.

3) Готовые actions и Marketplace

Большая часть workflow собирается из готовых блоков:

actions/checkout — получить код репозитория.

actions/cache — кешировать зависимости и ускорять сборку.

Actions для языков/сред (например, настройка Node/Python/Java).

Практическое правило: используйте популярные actions и фиксируйте версии (например, @v4), чтобы поведение не менялось неожиданно.

4) Переменные, секреты и права (безопасность)

Secrets

Секреты (токены, ключи) хранятся в настройках репозитория/организации и подставляются в workflow как переменные окружения.

Что важно:

Никогда не храните секреты в репозитории.

Считайте секрет скомпрометированным, если он попал в логи или код, и ротируйте его.

Permissions

Workflow может получать права на GitHub API (например, писать комментарии, создавать релизы). Лучше придерживаться принципа «минимально необходимые права».

PR из форков

Если проект принимает PR через fork (см. статью про форки), учтите: секреты обычно не доступны workflow’ам, запущенным из PR внешних участников — это защита от утечек.

5) Артефакты, кеш и ускорение CI

Артефакты

Артефакты — файлы, которые вы сохраняете после job (например, отчёт тестов, сборка). Это удобно, если:

нужно скачать результаты;

нужен отчёт для анализа падений;

несколько jobs используют общий результат.

Cache

Cache уменьшает время прогонов, сохраняя зависимости между запусками.

Практика:

кешируйте только то, что долго скачивается/собирается;

ключ кеша должен зависеть от файлов зависимостей (иначе получите «грязный» кеш).

6) Простая схема CI → CD

Минимальная логика CD обычно строится так:

На PR — только проверки (CI).

На merge/push в main — сборка и публикация (CD).

Визуально:

Чтобы не деплоить «что попало», деплой часто делают:

только из main;

только по тегу (например, релиз);

с ручным подтверждением через Environments (если команда использует этот механизм).

7) Отладка: что делать, если workflow падает

Откройте вкладку Actions и провалитесь в конкретный run.

Найдите упавший step — он обычно подсвечен.

Проверьте логи: часто причина — отсутствие зависимостей, неверные переменные окружения, различия ОС runner.

Используйте Re-run jobs после исправлений (или новый push).

Полезная привычка: держать проверки воспроизводимыми локально (те же команды линтера/тестов), чтобы CI не был «магией».

---

Задания для закрепления

1) Термины

Соотнесите понятие и описание:

Workflow

Runner

Job

Step

A. Машина/окружение, где выполняются действия B. Один логический набор шагов, который может выполняться параллельно с другими C. Отдельная команда или подключение готового action D. YAML-описание автоматизации в .github/workflows/

<details> <summary> Ответ </summary>

1–D, 2–A, 3–B, 4–C

</details>

2) Выбор триггера

Вам нужно:

Запускать проверки для каждого PR

Запускать ночной прогон тестов

Иметь кнопку ручного запуска для редких задач

Назовите подходящие события.

<details> <summary> Ответ </summary>

1) pull_request 2) schedule 3) workflow_dispatch

</details>

3) Проектная настройка CI

Опишите (в 4 пунктах), как вы настроите минимальный CI для репозитория команды, где изменения попадают в main только через PR.

<details> <summary> Возможный ответ </summary>

1) Создать workflow в .github/workflows/ci.yml. 2) Настроить триггер pull_request (и при необходимости push в main). 3) Добавить job с checkout кода и командами линтера/тестов. 4) Включить правило защищённой ветки так, чтобы merge был возможен только при зелёных checks (как обсуждалось в статье про PR и branch protection).

</details>

4) Безопасность

Почему небезопасно хранить токены прямо в репозитории, даже если он private? Назовите 2 причины и 1 правильную альтернативу.

<details> <summary> Ответ </summary>

Причины:

1) Токен может утечь через историю Git, логи CI, случайный PR/скриншот или неправильные права доступа. 2) Private-репозиторий не гарантирует, что секрет увидит только «нужный круг»: доступы меняются, люди уходят, репозиторий может быть форкнут/склонирован.

Альтернатива:

Хранить токены в GitHub Secrets (репозитория/организации) и передавать их в workflow как переменные окружения.

</details>