Для DevOps-инженера управление GitHub-репозиториями имеет не меньшее значение, чем содержащийся в них код. Хорошо поддерживаемые GitHub-репозитории создают основу для эффективной совместной работы и оптимизированных рабочих процессов. В этой статье мы рассмотрим 10 советов по эффективному управлению репозиториями на GitHub.
1. Четко придерживайтесь соглашения об именовании репозиториев
Соглашение об именовании репозиториев в GitHub помогает в организации и вносит ясность, что очень важно при совместной работе.
Благодаря четкому соглашению о нейминге вы сможете:
С первого взгляда определить назначение и содержание репозиторияЭффективнее искать и извлекать информацию из репозиториевПрименять стандартизированный подход в командах и проектахВнедрять автоматизацию для более эффективной работы за счет прогнозирования структуры и именования репозиториев. Например, рабочие процессы CI/CD могут разворачивать версии на основе соглашений о нейминге.
Давайте посмотрим, как подбирать имена и что конкретно можно в них включать.
Префикс для обозначения проекта или команды. Если в вашей организации есть несколько проектов или команд, названия репозиториев могут начинаться с префиксов, идентифицирующих проект или команду. Например, teamalpha_authentication_service или teambravo_data_pipeline.Описательные имена. Репозитории должны иметь описательные и конкретные названия, которые подскажут вам, что в них находится. Например, customer_support_ticketing_system или machine_learning_model_trainer.Указание на основной технологический стек. Это может быть особенно полезно для архитектур микросервисов. Например, image_processor_python или frontend_react_app.Версии или метки состояния. Если вы поддерживаете разные версии инструмента или библиотеки, или если в репозитории хранится что-то на определенной стадии разработки, укажите это в названии. Например, payment_gateway_v2 или inventory_management_deprecated.Избегайте специальных символов. Придерживайтесь букв и цифр с дефисами и символами подчеркивания, чтобы сохранить URL-совместимость и избежать путаницы. Например, invoice-generator или invoice_generator.Указание на юзкейс. Иногда полезно указать, является ли репозиторий библиотекой, сервисом, демо-версией или документацией. Например, authentication_lib, payment_api_service, demo_inventory_app, api_documentation.
Придерживаясь четкого и стандартного соглашения об именовании репозиториев, вы обеспечиваете более эффективную навигацию по репозиториям для всех членов команды. В конечном итоге это приводит к улучшению сотрудничества, экономии времени и уменьшению количества ошибок, позволяя командам сосредоточиться на разработке и развертывании, а не на организационной путанице.
2. Классифицируйте репозитории по темам
GitHub позволяет классифицировать репозитории по темам. Темы (topics) — это метки, которые можно добавлять к репозиториям для их классификации и облегчения поиска. Это отличный способ организовывать и группировать GitHub-репозитории по их назначению, технологическому стеку или любым другим критериям.
Чтобы добавить темы, относящиеся к репозиторию, перейдите в настройки «About» для редактирования сведений о репозитории и выберите раздел «Topics».
Добавлять темы в GitHub-репозитории полезно по нескольким причинам, в том числе:
Видимость. Темы облегчают другим людям поиск вашего репозитория. Когда кто-то ищет определенную тему, в результаты поиска попадут репозитории, для которых указана эта тема.Организация. Темы помогают организовывать репозитории. Вы можете группировать репозитории по их назначению, технологическому стеку или любым другим критериям.Сообщество. Указание тем поможет вам познакомиться с людьми, которые интересуются теми же темами. Когда кто-то просматривает репозиторий с определенной темой, он может увидеть другие репозитории с той же темой.Ознакомление. Указанные темы предоставляют информацию о технологиях и инструментах, популярных в вашей организации. Вы можете использовать эту информацию для выявления тенденций и принятия обоснованных решений об используемых технологиях и инструментах.Стандартизация. Темы помогают стандартизировать категоризацию репозиториев. Вы можете использовать одни и те же темы во всех репозиториях, чтобы обеспечить согласованность.
При добавлении тем в репозиторий важно выбирать темы, которые являются актуальными и значимыми. Они должны точно описывать назначение, технологический стек или другие важные характеристики репозитория.
Более подробную информацию о темах и их эффективном использовании вы можете получить из документации по темам репозиториев GitHub.
3. Используйте README.md для документирования репозитория
Хорошо документированный репозиторий — это сокровище для разработчиков, контрибьюторов и мейнтейнеров. Файл README.md — это первое, что видит посетитель, когда заходит на ваш репозиторий. И это отличное место для краткого обзора репозитория и его назначения, а также для инструкций по началу работы с ним. Файл может содержать следующую полезную информацию:
Описание проектаИнструкции по настройкеПримеры использованияРуководство для контрибьюторовИнформацию о лицензии
Хорошо написанный файл README.md может вам помочь в следующих вещах:
Привлечение контрибьюторов. Этот файл предоставляет потенциальным контрибьюторам информацию, необходимую для понимания проекта и начала работы с ним.Онбординг. README.md поможет новым членам команды освоиться в проекте.Документация. Файл README.md служит документацией для проекта. Он предоставляет пользователям информацию, необходимую для работы с проектом.Продвижение. Этот файл предоставляет потенциальным пользователям информацию, необходимую для понимания проекта и принятия решения о его использовании.Стандартизация. README.md помогает стандартизировать способ документирования проектов. Это обеспечивает последовательную структуру документирования проектов.
При написании файла README.md важно, чтобы он был кратким и содержал самую суть. Наиболее важную информацию следует поместить в верхней части файла, а при необходимости дать ссылки на более подробную информацию. Также следует использовать форматирование, чтобы файл было легко читать, и включать изображения и другие медиафайлы, где это уместно.
Более подробную информацию о том, как написать хороший файл README.md, вы можете получить в документации по README для GitHub-репозитория.
От редакции Techrocks: возможно, вас заинтересует статья «Как написать прекрасный файл README на GitHub».
4. Применяйте последовательную стратегию ветвления
Последовательная стратегия ветвления очень важна для эффективной совместной работы и управления кодом. Она обеспечивает четкую структуру управления изменениями кода и их интеграцией в кодовую базу. Она также помогает поддерживать чистую и стабильную кодовую базу и снижает риск возникновения конфликтов и ошибок.
Существует несколько стратегий ветвления, которые вы можете использовать. Например:
Gitflow. Популярная стратегия ветвления, которая использует две основные ветки, master и develop, и множество вспомогательных веток для параллельной разработки и управления релизами.Feature Branching. Каждая функция или задача разрабатывается в отдельной ветке, а затем после завершения сливается с основной веткой.Trunk-Based Development. Стратегия, при которой все изменения вносятся непосредственно в основную ветку.GitHub Flow. Облегченная стратегия ветвления, при которой используется одна основная ветка, а для каждой новой функции или исправления ошибки создаются тематические ветки.GitLab Flow. Стратегия, аналогичная GitHub Flow, но с добавлением окружений и релизных веток для управления процессом выпуска.Release Branching. Для подготовки к новому релизу из основной ветки отходит ветка релиза. Затем, после завершения релиза, она сливается обратно в основную ветку.Environment Branching. Стратегия, при которой ветви используются для управления различными окружениями. Например, могут быть ветки development, staging и production.
При выборе стратегии ветвления важно учитывать потребности вашей команды и проекта. Вы должны выбрать простую, гибкую и масштабируемую стратегию, которая поддерживает стиль работы вашей команды. Также необходимо задокументировать стратегию ветвления и убедиться, что все члены команды понимают, как она работает, и неуклонно следуют ей.
Более подробную информацию о ветвлении и о том, как использовать ветки, вы можете получить из официальной документации GitHub по ветвлению.
5. Защитите свой репозиторий с помощью правил защиты ветвей
Правила защиты ветвей — это мощная функция GitHub, которая позволяет накладывать на ветви определенные ограничения и требования. Эти правила могут помочь вам поддерживать чистую и стабильную кодовую базу. Они также помогут вам предотвратить ошибки, повысить качество и безопасность вашего кода.
Например, при помощи правил защиты ветвей вы можете сделать обязательными:
Ревьюпул-реквестов.Можно указать, что до слияния пул-реквест должно одобрить определенное число ревьюеров.Проверки состояния. Можно указать, что до слияния пул-реквестов должны быть проведены определенные проверки состояния, например проверки CI/CD.Разрешение всех обсуждавшихся вопросов перед слиянием. Вы можете потребовать, чтобы до слияния пул-реквеста автор обязательно отреагировал на все комментарии к пул-реквесту.Подписание коммитов.Можно установить, что коммиты должны быть подписаны проверенной подписью, прежде чем они будут слиты.Линейную историю. Правилом можно определить, что история коммитов в пул-реквесте должна быть линейной.Очередь слияния. Если пул-реквест прошел все необходимые проверки защиты ветвей, пользователь с правами записи в репозитории может поставить поставить его в очередь на автоматическое слияние. Это полезно для ветвей, в которые регулярно и часто делают коммиты несколько пользователей. Для запуска проверок может использоваться GitHub Actions.Успешное развертывание перед слиянием. Можно потребовать, чтобы до мержа пул-реквеста были обязательными успешные развертывания в определенных средах, например в продакшене.
Более подробную информацию о правилах защиты ветвей и их использовании вы можете получить в документации GitHub по защите ветвей репозитория.
При использовании правил защиты ветвей важно найти баланс между соблюдением ограничений и требований и возможностью эффективной работы вашей команды. Следует учитывать потребности своей команды и проекта и выбирать правила, которые поддерживают методы работы вашей команды. Также нужно задокументировать правила и убедиться, что все члены команды понимают, как они работают, и неуклонно следуют им.
6. Поддерживайте чистоту истории коммитов
Чистая история коммитов очень важна для эффективной совместной работы и управления кодом. Она обеспечивает четкую запись изменений в коде и помогает поддерживать чистую и стабильную кодовую базу. Она также облегчает понимание истории кодовой базы и снижает риск возникновения конфликтов и ошибок.
Вот несколько подходов, которые вы можете применить для поддержания чистой истории коммитов:
Описательные сообщения коммитов. Они должны объяснять цель и контекст внесенных изменений. От редакции Techrocks: рекомендуем статью «Практическое руководство по написанию хороших сообщений коммитов».Атомарные коммиты. Делайте небольшие, сфокусированные коммиты, содержащие одно логическое изменение. Это облегчает понимание истории кодовой базы, а также снижает риск возникновения конфликтов и ошибок.Содержательные заголовки коммитов. Они должны кратко описывать цель внесенных изменений.Единообразное форматирование. Например, для сообщений коммитов используйте повелительное наклонение и не превышайте длину в 50 символов.Подписи коммитов. Используйте подписи для проверки подлинности ваших коммитов и защиты от несанкционированного доступа.
Например, хорошее сообщение коммита выглядит следующим образом:
git commit -m “Add user authentication mechanism to the inventory management system”
Плохой практикой является использование расплывчатых сообщений. Пример:
git commit -m “Fixed stuff”
При ведении чистой истории коммитов важно учитывать потребности вашей команды и проекта. Вы должны выбрать простые, гибкие и масштабируемые практики, которые поддерживают стиль работы вашей команды. Также следует задокументировать эти практики и убедиться, что все члены команды понимают, как они работают, и неуклонно следуют им.
7. Используйте .gitignore
Файл .gitignore — это простой и эффективный способ управления файлами и каталогами, которые вы хотите исключить из контроля версий. Он позволяет указать шаблоны, соответствующие файлам и каталогам, которые вы хотите игнорировать, и предотвращает их добавление в репозиторий.
Файл .gitignore особенно полезен для игнорирования следующих вещей:
Артефакты сборки. Файлы и каталоги, создаваемые в процессе сборки, такие как файлы логов и временные файлы.Конфиденциальная информация. Файлы и каталоги, содержащие конфиденциальную информацию, например пароли, ключи API и файлы конфигурации.Файлы, специфичные для пользователя. Это файлы и каталоги, предназначенные для отдельных пользователей, например настройки редактора, локальная конфигурация и временные файлы.Большие файлы. Файлы и каталоги, которые имеют большой размер и не нужны для контроля версий, например медиафайлы, бинарные файлы и архивы.Логи и кэш. Файлы и каталоги, которые создаются в процессе логирования и кэширования.Тестовые файлы. Файлы и каталоги, созданные в процессе тестирования, такие как результаты тестирования, логи и артефакты тестирования.
При использовании .gitignore важно учитывать потребности вашей команды и проекта. Следует выбирать простые, гибкие и масштабируемые паттерны, которые поддерживают методы работы вашей команды.
Более подробную информацию о .gitignore и его эффективном использовании вы можете получить в GitHub-документации по .gitignore.
8. Используйте GitHub Actions для CI/CD
GitHub Actions — это мощная функция GitHub, которая позволяет автоматизировать задачи с помощью рабочих процессов. Она обеспечивает гибкий и масштабируемый способ сборки, тестирования и развертывания кода, а также помогает поддерживать чистую и стабильную кодовую базу.
GitHub Actions — это отдельная большая тема. Если вкратце, то с помощью GitHub Actions вы можете автоматизировать запуск разнообразных процессов при каждом изменении в репозитории:
Процессы сборкиТестыПроцессы развертыванияСоздание релизовГенерация документацииПроверки безопасности (сканирование уязвимостей, анализ зависимостей и анализ кода)
Также можно автоматизировать задачи IaC (инфраструктуры как кода), такие как обеспечение, настройка и развертывание инфраструктуры.
Список можно продолжать, но суть в том, что GitHub Actions — это мощный инструмент, который поможет вам автоматизировать многие задачи, связанные с управлением кодовой базой.
Более подробную информацию о GitHub Actions вы можете получить из официальной документации.
9. Используйте отслеживание ишью и проекты
GitHub предоставляет мощную систему отслеживания ишью, с помощью которой можно отслеживать проблемы, ошибки и запросы функций и управлять ими. Кроме того, он предоставляет доски состояния проектов, которые позволяют отслеживать ход работы.
Проекты GitHub (Projects) также помогут вам более эффективно управлять своей работой и улучшить сотрудничество и коммуникацию в команде.
Этот инструментарий GitHub полезен для:
Отслеживания проблем и ошибок и управления процессом их исправленияОтслеживания запросов на функции и управления процессом их реализацииПланирования и расстановки приоритетовУправления релизами и отслеживания хода работы по вехамСотрудничества и общения с командойМаркировки: можно использовать ярлыки для классификации проблем и отслеживания их выполнения. (Например, bug, enhancement, help wanted).
Более подробную информацию вы можете получить из официальной документации GitHub по отслеживанию ишью и проектам.
10. Используйте функции безопасности GitHub
GitHub предоставляет ряд функций безопасности, которые могут помочь вам повысить безопасность вашей кодовой базы. С помощью этих функций вы сможете выявлять и устранять уязвимости в системе безопасности, а также проактивно защищать ваш код от угроз безопасности и утечек.
Варианты использования функций безопасности GitHub:
Предупреждения для уязвимых зависимостей. Получение предупреждений, когда в вашем репозитории появляется уязвимая зависимость.Сканирование кода. Сканирование кода на наличие уязвимостей безопасности, секретов, переданных в коде, и ошибок кодирования.Обновления безопасности/зависимостей. Автоматическое обновление зависимостей до последней безопасной версии с помощью GitHub Dependabot.Политики безопасности и рекомендации. Создание и управление политиками безопасности и рекомендациями для вашего репозитория.Информация о зависимостях. Получение информации о безопасности/зависимостях вашей кодовой базы и определение областей для улучшения с помощью графа зависимостей.
Заключение
В этой статье мы рассказали о нескольких практиках эффективного управления репозиториями GitHub. Надеемся, вы узнали что-то новое и полезное для себя.
Перевод статьи «GitHub Repository Best Practices».
Запись Управление GitHub-репозиториями: best practices впервые появилась Techrocks.