Для размещения наших open-source библиотек и различных утилит используются аккаунт RDS или StrongSelf. Чтобы не засорять их узкоспециализированными или неподдерживаемыми компонентами, нужно придерживаться ряда правил.
- Используется как минимум в двух внутренних проектах.
- Не привязана к нашим конкретным задачам, может пригодиться сообществу.
- Решение не является велосипедом, можно четко выделить перечень причин, по которым она обходит свои аналоги.
- Ревью проекта проводили как минимум двое членов команды, не принимавших участие непосредственно в разработке компонента.
- Полностью покрыта тестами.
- Код содержит подробные комментарии на английском языке.
- Для работоспособности не требуется доступ к приватным ресурсам.
- Демонстрирует подходы к решению определенных задач, либо несет ценность само по себе.
- Написано с соблюдением принятых в команде практик.
- Тестами покрыта как минимум бизнес-логика.
- Код содержит подробные комментарии на английском языке,
- В команде есть человек, отвечающий за план разработки проекта и продуктовые вопросы.
- Полностью наследуются правила для пункта 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.
