Переписать «правила работы с Github»
taqyon opened this issue · comments
Правила работы с GitHub
Для более эффективной работы, мы в своей команде используем Github. Для нас GitHub это место где находится вся необходимая информация для работы и место где находится истина — код.
Github в нашей команде используют все: разработчики, дизайнеры, менеджеры, заказчики и все все все. Все находятся в одной среде и все всё видят. И это прекрасно. Но для того чтобы использовать GitHub эффективно, к нему надо привыкнуть и его надо освоить.
В этом кратком руководстве, мы собрали собственные командные практики работы с GitHub. Также здесь есть ссылки на официальные руководства GitHub для расширения кругозора.
Работа с Issues
Issues — это место где мы обсуждаем всю важную работу, от начала (создание issue) и до конца (закрытие issue).
Важно чтобы обсуждение по той или иной задаче/проблеме проходило внутри Issue. Это позволяет отследить историю в случае возникновения такой проблемы, а также даёт возможность просто делиться ссылкой на Issue или конкретный комментарий внутри Issue.
Issue Labels
Сам по себе Issue не несёт никакого «смыслового окраса». Для этого, мы применяем лейблы.
Например:
- Issue с лейблом documents — это задача или проблема, которая относится к документации
- Issue с лейблом feature — означает что там лежит какая-то информация о фиче
- Issue с лейблом bug, ну ты понял
Поэтому очень желательно, чтобы Issues не оставались без лейблов. Список доступных лейблов доступен с правой стороны Issue, заголовок Labels:
Управление Лейблами на GitHub Docs
Отдельно про Markdown
Markdown — это облегчённый язык разметки. Эта разметка позволяет сделать текст жирным или наклонным (италик).
Делать удобные для отображения списки:
- Раз
- Два
- Три
А также цитировать своих собеседников:
Привет! Всё готово к релизу, погнали?
Чел, сегодня пятница, какой релиз :|
Весь этот набор разметки, позволяет сделать самое главное: писать красивые и чётко сформулированные мысли в текстовом виде.
Это очень важно для командной работы. Потому что текст в Issues потеряется в самую последнюю очередь. А хорошо сформулированная мысль, позволит быстро донести суть до своих собеседников.
Поэтому важно ознакомиться с Основным синтаксисом письма и форматирования Markdown на GitHub Docs. Там же есть секция с продвинутыми практиками.
Работа с Branches
Стоит ли всё-таки оставлять эту секцию или нет? Мне непонятно.
Работа с Pull Request
Pull Requests позволяют вам сообщить другим об изменениях, которые вы внесли в ветку в репозитории на GitHub. После открытия Pull Request'а вы можете обсудить и просмотреть потенциальные изменения с коллегами и добавить последующие коммиты до того, как ваши изменения будут объединены в базовую ветку.
Из документации к Pull Request'ам на GitHub Docs
Как создавать?
Создание Pull Request'а на Github Docs
Когда создавать?
Можно сразу после первых коммитов. Ежедневно, к концу рабочего дня должно коммититься текущее состояние вашей ветки. Если пр не готов к ревью - он отправляется в драфт (также по этой причине нет смысла использовать WIP в коммит месседжах: если работа в процессе - пр находится в драфте)
Это необходимо для прозрачности процесса, чтобы вовремя выявить недочеты при написании кода, пока кодовая база вокруг них не разрослась, они не остались незамеченными и не превратились в легаси.
В будущем такой подход также помогает при навигации по истории коммитов.
Кого ставить в assignee?
Указываем себя, как автора. Это позволит потом по PR делать фильтрацию и получает предсказуемые результаты.
Кого указывать в ревьюверах?
Лида (ментора) или если таковой отсутствует - @TorinAsakura
Что за статусы проверок?
У проектов могут быть настроены проверки проектов, которые выполняются при создании и обновлении Pull Request'а. В них можно получить всю необходимую информацию о выполнении тестов.
Можно ли форсить ветку? (Нужна ли эта секция? Не слишком всё усложняет на данном этапе?)
Можно, но только если от этого больше пользы, чем вреда. Когда можно:
- Когда ревью еще не провели.
- Когда в ветку еще ничего не вливали (обновленный dev)
- Когда PR на этой ветке еще нет.
Когда нельзя:
- Когда ревью провели. Комментарии привязываются к хешу коммитов. Если форснуть, то это уже новые коммиты, даже если в них ничего не менялось. Из-за этого весь прогресс ревью тупо слетает. В итоге ревьюверу нужно потратить время, чтобы определиться, где он оставлял ревью, а где нет.
- Когда форсом можно ненароком ввести в заблуждение. После форса достаточно муторно посмотреть, что же в итоге изменилось. Можно, конечно, выдрать хеши и пойти в diff, чтобы посмотреть, что изменилось.
Лучше пусть будут лишние коммиты (коммиты лишними не бывают), так процесс выглядит более прозрачным и последовательным.
Conventional Commits или Соглашение о коммитах
«Соглашение о коммитах» — простое соглашение о том, как нужно писать сообщения коммитов. Оно описывает простой набор правил для создания понятной истории коммитов, а также позволяет проще разрабатывать инструменты автоматизации, основанные на истории коммитов.
Цитата из официального документа соглашения
Мы придерживаемся данного соглашения и требуем этого от всех разработчиков, членов нашей команды. Поэтому данное соглашение нужно изучить и соблюдать в своей работе.
Важно! Никакой кириллицы ни в коде, ни в комментариях к коммитам, ни в названиях бранчей быть не должно
Post Scriptum
Эффективная работа в GitHub для нас очень важна. Здесь протекает вся рабочая «жизнь» проектов над которыми мы работаем. Поэтому для нас важно, чтобы каждый соблюдал базовые правила работы с этим инструментом.
Вообще, у GitHub довольно обширная и полезная документация, с которой рекомендуется ознакомиться.
Если незнаком или мало опыта с Git, то вот полезный тур на русском языке по нему. Чёрт побери, Git!?! быстрая и понятная подсказка по Git'у. Или Интерактивная визуализация и учебник по Git.
Добавил файл. Италиком выделил спорные места. Секция Pull Request'Ами почти полностью выдернута из текущей версии конвенции. Остальное написано с нуля.
Пожалуйста, ознакомьтесь и внесите необходимы правки. Или задавайте свои вопросы тут.
Работа с Branches
Стоит ли всё-таки оставлять эту секцию или нет? Мне непонятно.
Я думаю что здесь только стоит упомянуть про то, как нужно называть свои ветки, потому что в conventional commits (насколько мне известно) про это не написано. (а если и написано, то явно не на самом видном месте)
Вижу это как-то так:
Ветка именуется в соответствии с типом изменений и кратким описанием. Типы изменений: feat, chore, fix - в общем все те, что и в conventional commits. Описание - буквально 2-3 слова про характер изменений, не больше.
Примеры: fix/uikit-compatibility, feat/payout-service, chore/deps-upgrade
Можно ли форсить ветку? (Нужна ли эта секция? Не слишком всё усложняет на данном этапе?)
Соглашусь на самом деле, новички обычно даже не знают что это значит и что так можно делать, и, следовательно, особо этим не злоупотребляют. Я за то чтобы убрать
Это чисто мое видение, обязательно нужен комментарий от @TorinAsakura, может я вообще во всем не прав
P.S. Интересно, конечно, что ты все-таки остановился на ohshitgit без цензуры)
P.S. Интересно, конечно, что ты все-таки остановился на ohshitgit без цензуры)
Вообще я выбирал как раз таки цензурную версию. Я проверил ссылку, там лежит ohdangitgit. То есть та что без мата.
@taqyon еще добавь пожалуйста пункт про то, что никакой кириллицы ни в коде, ни в коммит мессседжах, ни в названиях бранчей быть не должно
@taqyon еще добавь пожалуйста пункт про то, что никакой кириллицы ни в коде, ни в коммит мессседжах, ни в названиях бранчей быть не должно
Хотел отдельным пул реквестом отправить, но нихера не понял и создал коммит в существующем: d5fc65b (#28)