Я назвал это «Операционная система Github», потому что целью этого небольшого мета-руководства является не столько подробное описание использования Github, сколько предоставление читателю удобного и общего метода или системы, действительно позволяющей «управлять» проектом профессионально, в контекст командной работы.

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

🚀 Аккаунт

Аккаунт Github является личным, вы не должны использовать корпоративную почту.

Более того, многие службы позволяют вам войти в систему с помощью Github, и если у вас уже есть учетные записи, созданные таким образом, вам придется выйти из своей учетной записи компании и войти в свою, а затем снова войти в систему с корпоративной… очень грязно.

«Организация» — это то, как Github решает эту проблему и избавляет нас от необходимости иметь 2 разных аккаунта.

В любом случае, если вы использовали корпоративную почту, вы всегда можете изменить ее из настройки › электронная почта

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

🔧 Настройки

При приглашении в нашу Организацию вам будет предложено активировать 2FA (двухфакторную аутентификацию) из соображений безопасности. настройки › безопасность

✨ Репо

создание: git-менеджер, разработанный компанией, создаст репозиторий для вас. Вы будете решать имя вместе. Если имя содержит более одного слова, в нем будут дефисы, например my-project-web.

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

admin: менеджер git назначит кого-то администратором репозитория. С этого момента администраторы будут нести ответственность за это репо.

права: администратор репозитория должен определить роли для других приглашенных внести свой вклад. Доступ к репозиторию для каждого уровня разрешений.

readme: администратор репозитория ДОЛЖЕН написать файл README.md в синтаксисе уценки, который сообщает, кто является администратором репозитория и кто является менеджером проекта, о чем репозиторий, как установить и запустить проект, технический стек и как внести свой вклад.

о себе: должно быть предоставлено описание с тегами.

Как написать хороший файл README для вашего проекта GitHub — ссылка

📝 Документация

Разработчик должен создать и поддерживать надлежащую проектную документацию с версиями кода, прежде чем писать код, даже если решение не является окончательным. Это потому, что легче рассуждать о чем-то уже задокументированном и проще писать документацию поэтапно, чем писать все сразу, рискуя забыть какую-то деталь.

  • для БД с файлом ERD-диаграммы от draw.io
  • для API с файлом .yml от open-generator
  • для конкретного потока с файлом блок-схемы из draw.io (например, поток аутентификации, такой как oAuth или SAML)

🗃️ Соглашение об именах веток

main Ветка Github по умолчанию — всегда содержит стабильную версию кода

dev основная ветка для разработчиков - содержит последнюю рабочую версию кода, отсюда запускаются ветки функций и исправлений

test версия для тестировщиков - если dev код меняется слишком быстро, чтобы его можно было точно протестировать, то эта ветка регулярно обновляется группами обновлений для тестирования

demo для заказчика - в этой ветке находится незаконченная демонстрация продукта для заказчика

prod текущий производственный код — этот код официально работает на сервере, в контейнере, на мобильных устройствах и т. д. и т. д. в любой момент времени

💄 Условные обозначения кода

Не используйте личные отступы или систему пробелов. Просто используйте соглашение.

Если вы пишете javascript, вы можете использовать Prettier с этим файлом конфигурации .prettierrc в корневой папке вашего проекта:

{
  "singleQuote": true,
  "endOfLine": "lf",
}

Красивее — ссылка

🙈 Гит игнорировать

Файл с именем .gitignore в корне вашего проекта дает вам возможность исключить из управления версиями определенные файлы (.env), папки (node_modules) или шаблоны (private-code/**/*.js)

⬆️ Обычные коммиты

Спецификация Conventional Commits — это облегченное соглашение поверх сообщений фиксации.

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

Обычные коммиты — ссылка

🔀 Гит поток

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

Самая популярная система ветвления — «Git Flow», настолько популярная, что в git CLI встроены команды, готовые к использованию. Эта система заставляет вас создавать новые ветки для каждой функции, которую вы реализуете. В конце итерации эта ветка будет автоматически объединена с основной веткой и удалена.

Полезные команды:

  • см. справку Git Flow git flow -h (взгляните)
  • создать новый поток: git flow <branch-type> start <name>
  • объединить и удалить поток: git flow <branch-type> finish <name>
  • возможные типы ветвей: feature, bugfix, release, hotfix, support

Вы должны использовать типы правильно и осмысленное имя из 1–3 слов, разделенных дефисами (-)

При создании ветки о проблеме вы должны использовать номер проблемы, например:

# start branch about issue #254
git flow bugfix start 254
# close
git flow bugfix finish 254

шпаргалка по git-flow — ссылка

Оригинал статьи Винсента Дриссена о модели ветвления — ссылка

🐛 Проблемы

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

Создать шаблон задачи GitHub — ссылка

Важно, чтобы каждая часть продукта присутствовала и постоянно работала на Github:

  • разработчики будут управлять кодом, проблемами, выпусками… всем
  • тестировщики будут иметь дело в основном с проблемами и приближающимися вехами
  • дизайнеры проектов будут решать проблемы процесса, и они должны по возможности создавать версии документации (процессов, диаграмм).
  • Дизайнеры пользовательского интерфейса и пользовательского интерфейса будут устранять графические несоответствия и запросы, а также создавать версии важных документов о системе дизайна, цветах и ​​типографике.
  • дизайнеры архитектуры и системные операторы будут документировать инфраструктуру с помощью кода.
  • менеджеры проектов будут игнорировать все, от комментариев к коммитам до проблем, они будут решать вехи и проблемы, связанные с вехами (де-факто определяя приоритеты проблем)

Общим основанием в любом случае будут «Вопросы». Каждый может открыть их, и любой вопрос может быть адресован всем, включая проектировщиков и дизайнеров пользовательского интерфейса.

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

Всегда спрашивайте и отвечайте на Github, информация всегда будет доступна.

Открыватель задач ВСЕГДА должен проверять, не открывалась ли аналогичная задача по тому же объекту, ища ее в строке поиска.

Разработчик, ответственный за решение проблемы, должен указать себя как assignee. Это напишет сообщение в истории задач, которое само по себе будет означать, что проблема обрабатывается.

🚩 Вехи

Веха определяет приблизительное время выпуска релизов, поэтому они полезны для определения сроков исправления проблемы.

Менеджер проекта с помощью разработчика должен решить, какой из следующих этапов будет содержать решение проблемы.

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

🏷️ Этикетки

Ярлыки — это НАИБОЛЕЕ способ сортировать проблемы и управлять ими.

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

Если вам нужно создать, удалить или изменить метки, вы можете перейти к репо › выпускам › меткам и использовать кнопку New label или ссылку edit или delete рядом с каждой существующей меткой.

Ярлык содержит концепцию, всегда помните, что нужно остановиться и подумать о последствиях использования этой концепции в игре с другими ранее существовавшими ярлыками.

  • Не пересекается ли это понятие с другим? mobile против android
  • Описывает ли новая метка полностью новую концепцию, или должны существовать другие метки, чтобы лучше представить эту область? server понадобится client или аналогичный?

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

🚸 Использование

Метки должны быть размещены разработчиком как можно скорее, даже если в настоящее время не ведется работа по исправлению ошибок.

Когда у разработчика есть вопрос о проблеме, он должен ВСЕГДА использовать ответ о проблеме на Github и НИКОГДА в Slack или по электронной почте, чтобы не скрывать информацию от других.

Типичный пример — когда проблема открывается с недостаточной информацией, в этом случае разработчик должен пометить проблему need more info и явно прокомментировать, упомянув, кто открыл проблему в первую очередь (с @<name>), и запросив недостающие части.

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

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

Затем разработчик закрывает вопрос и добавляет метку ready to test.

Когда тестер протестировал закрытую проблему, остается выбор:

  1. проблема решена, и ярлык ready to test будет удален
  2. проблема не решена, метка ready to test будет удалена, а проблема снова открыта с помощью кнопки Reopen issue

Таким образом, состояние вопроса всегда понятно каждому.

📸 Релизы

Когда все проблемы вехи закрыты или когда наступает определенная дата, пришло время выпустить новую версию кода. Для этого разработчик или руководитель проекта может создать новый «Релиз» на странице репозитория.

Версия, название и описание должны быть написаны следующим образом:

При сборке артефакта, такого как Android .apk, архив сборки или двоичный файл, файл необходимо прикрепить, используя соответствующую область перетаскивания. Таким образом, тестирование последней версии будет проходить намного быстрее, а отслеживание версий будет эффективным.

Благодаря использованию «обычных коммитов» и «Действий Github» написание описания релиза и сборка двоичных файлов могут быть автоматизированы.

Действия на Github — ссылка

Еще лучшим вариантом для нашего репозитория было бы использование semantic-release для автоматического повышения версии и создания релиза.

Semantic Release Automation — ссылка

📌 Шаблон репозитория

Хорошая стратегия — полностью настроить репозиторий, добавив шаблоны задач, git-экшены, ветки, файлы и структуры папок, а затем создать репозиторий шаблонов. Позже вы без особых усилий создадите новый репозиторий с теми же функциями и будете готовы внести последние изменения и начать продвигать действительно хороший код!

Создание репозитория шаблонов — ссылка

🥅 Лучшие практики

  • все это документация:
    - README.md
    - описание репозитория
    - названия веток
    - сообщение коммита
    - комментарии к выпуску
    - описание релиза
    - документация, которую вы пишете для этого проекта
  • работать над одним делом за раз
  • делать маленькие, частые, коммиты хотя бы локально
  • в конце дня или когда вы закончите push to repo
  • НИКОГДА не фиксируйте файлы конфигурации, такие как .env файлы с ключами
  • не фиксируйте зависимости или сгенерированные файлы
  • если у вас есть сломанный код, вы…
    - желательно спрятать его
    - альтернативно зафиксировать локально или
    - зафиксировать и отправить, если вы находитесь в ветке, где работаете в одиночку< br /> - но НИКОГДА не фиксируйте и не отправляйте его в основную ветку
  • с помощью обычного коммита пишите осмысленные сообщения коммита возможно используйте и правильные смайлики
  • используйте .gitignore и prettier.io
  • не смешивайте «рефакторинг» с кодом новой функции, а фиксируйте эти действия отдельно
  • если вы видите мертвый код или неиспользуемые файлы, дважды проверьте, а затем удалите их, держите их в чистоте.