Для размещения наших open source библиотек и различных утилит используется GitHub. Чтобы не засорять его узкоспециализированными или неподдерживаемыми компонентами, нужно придерживаться ряда правил.
- Используется как минимум в двух внутренних проектах,
- Не привязана к нашим конкретным задачам, может пригодиться сообществу,
- Решение не является велосипедом, можно четко выделить перечень причин, по которым оно обходит свои аналоги,
- Ревью проекта проводили как минимум двое членов команды, не принимавших участие непосредственно в разработке компонента,
- Полностью покрыта тестами,
- Код содержит подробные комментарии на английском языке.
- Для работоспособности не требуется доступ к приватным ресурсам,
- Демонстрирует подходы к решению определенных задач, либо несет ценность само по себе,
- Написано с соблюдением принятых в команде практик,
- Тестами покрыта как минимум бизнес-логика,
- Код содержит подробные комментарии на английском языке,
- В команде есть человек, отвечающий за план разработки проекта и продуктовые вопросы.
- Полностью наследуются правила для пункта 1,
- Написано на языке, который знает больше одного человека в команде.
- Необходим для работоспособности одного из open source приложений, расположенных на нашем же GitHub,
- Содержит кардинальные улучшения, по каким-то причинам не принимаемые автором оригинального компонента.
Каждый проект должен иметь подробный Readme на английском языке. Должны присутствовать следующие разделы:
- Описание проекта,
- Скриншот (если возможно снять),
- Инструкция по установке/интеграции, требуемое окружение,
- Максимально простой пример использования,
- Лицензия,
- Имя автора.
Пример Readme: Generamba
Статья на тему: Building Popular Projects
В случае, если примера из Readme недостаточно для понимания правил и возможностей работы с проектом, дополнительная документация ведется с использованием GitHub Wiki.
Пример Wiki: Generamba Wiki
- Работаем по GitFlow,
- Коммиты пишутся на английском языке,
- Если изменение относится к какому-то issue, это упоминатся в тексте коммита,
- Ко всем версиям обязательно добавляются release notes, содержащие полный перечень всех изменений.
Пример: Generamba release 0.7.2
Для ведения задач по всем open source проектом стараемся использовать функционал GitHub - Issues и Milestones. В этом случае конкретного набора правил нет, скорее перечень рекомендаций:
- Milestone удобно использовать для разделения задач по версиям. К примеру, Version 0.7.2, Backlog. Это позволяет быстро оценивать прогресс выполнения задач для определенной версии и помогает при составлении release notes.
- Для разделения задач по эпикам, проставления приоритета или других отметок, можно использовать Labels - по сути, обычные теги. Примеры: Backend, Bug. Все issues ведутся на английском языке.
- У каждого issue должен быть не только заголовок, но и относительно подробное описание - любой сторонний человек должен быть способен понять смысл задачи и самостоятельно выполнить ее.
- Те же правила относятся и к составлению Pull Request'ов. Кроме того, не забывайте линковать их к соответствующим Issues.
- Если задача находится в разработке, у нее должен быть явно проставлен Assignee, во избежание конфликтов.
- Если при выполнении задачи возникли какие-то проблемы, желательно описать их в комментариях.
- При общении в комментариях старайтесь быть максимально открытыми и доброжелательными, даже если псотавленный вопрос откровенно глупый.
Если на проект возможно написать тесты, они должны быть. Для Continuous Integration используется система Travis CI.
Примеры конфигов:
В Readme проекта добавляется значок с текущим статусом прохождения тестов. Если Pull Request не проходит тесты, он не сливается в develop.
