Организация и ведение проектных и исследовательских репозиториев

В рамках данного гайда мы хотим не столько продублировать прекрасный материал наших коллег из сообщества энтузиастов научного опенсорса ITMO OpenSource, сколько описать ряд дополнительных моментов, которые могут быть полезны как сотрудникам лаборатории LISA-ITMO, так и участникам всего сообщества проектов с открытым исходным кодом.

Open-source-ops

В первую очередь, рекомендуется ознакомиться с циклом материалов из раздела “Лучшие практики и примеры”, которые детально описывают важнейшие аспекты и встроенные механизмы платформы GitHub, позволяющие разработчикам проектов с открытым исходным кодом сделать их более прозрачными для сторонних contributor’ов и более удобными для команды разработки.

Дополнения

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

Issues

Говоря о задачах (Issues), рекомендуется подробно описывать каждую задачу и заполнять все доступные разделы. Использование меток (Labels) важно ограничинить, добавляя необходимые только при наличии отдельного функционального/структурного блока вашего проекта.

Для декомпозиции задач, с недавних пор, на платформе GitHub появился более удобный встроенный механизм добавления подзадач прямо из любой существующей, которым мы также рекомендуем активно пользоваться. Дополнительно существует возможность использовать механизм упоминания задач в других задачах/запросах на слияние/коммитах. Реализуется механизм посредством упоминания интересующего вас объекта в комментариях/коммитах через конструкцию вида #N, где N - номер задачи. После такого упоминания объекта в нем дополнительно появится фиксация об упоминании.

❗ ВАЖНО: все обсуждения, возникающие в ходе выполнения задачи, также следует вести либо в рамках этого Issue, либо дублировать важные моменты для сохранения истории. Если задача закрывается без изменений в кодовой базе проекта следует указать причину, чтобы также осталась история, что может пригодиться спустя время, когда к этой задаче возникнет необходимость вернуться.

Pull Requests

В контексте запросов на внесение изменений (Pull Requests/Merge Requests), по аналогии с Issues, необходимо оставлять детальное описание выполненных изменений и заполнять все доступные разделы. Обязательно следует связать запрос с задачей/ами (Issue), в рамках которой выполнялись изменения, в разделе Development созданного Pull Request’а.

Всегда следует назначать коллег на Code Review ваших изменений. Если вы работаете в репозитории в одиночку - назначьте себя! Подобная практика, когда вы оцениваете ваши же изменения спустя некоторое время, позволит вам критически оценить свой собственный код и способствует дополнительному развитию технических навыков.

❗ ВАЖНО: если работа над проектом ведется в команде - не забывайте о балансе! Цель ревью не задеть человека, а аргументированно показать, что, как и почему можно улучшить!

❗ ВАЖНО: если в репозитории настроены CI/CD-пайплайны они должны проходить, в противном случае не следует сливать изменения, поскольку есть вероятность внести в проект нерабочий код или код с ошибками, что может помешать работе ваших коллег.

Projects

Проекты - это гибкий встроенный механизм для управления вашими планами и задачами в рамках репозитория, представляющий собой различные доски. В ваших проектах мы рекомендуем использовать минимум несколько досок:

  1. Стандартная Kanban-доска с дополнительными стоблцами Review (задачи на ревью у ваших коллег) и Blocked (задачи, которые заблокированы другими или блокируются до определенного времени);

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

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

Важно, что все доски имеют встроенный удобный механизм фильтрации по любым вашим полям. Например, чтобы отобразить открытые задачи необходимо ввести -status:Done. Не бойтесь добавлять к вашим задачам новые поля и настраивать ваши доски так, как будет удобно вашей команде!

Discussions

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

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