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

Меня зовут Женя, я все еще фронтенд-разработчик в команде Quick Experiments inDrive. В этой статье буду делиться своим выводами, а также прикладывать дополнительные ссылки, чтобы познакомить вас с материалом более подробно.

Сначала немного мотивации: если вы считаете, что не можете создать проект из-за отсутствия опыта, уверяю вас — это не так сложно, как кажется. Плюс в процессе подготовки вы сильно прокачаетесь как специалист.

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

Цели

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

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

Анализ существующих решений

Если вы твердо намерены реализовать свою идею, нужно начать не с кодинга, а с изучения проектов-аналогов. Скорее всего, идея уже была реализована в том или ином виде. Желательно проанализировать большинство таких проектов, изучить документацию, а в идеале — попробовать их в деле. 

Важно ответить для себя на вопросы: в полной ли мере эта библиотека решает наши проблемы? Нет ли явных минусов в процессе работы? Насколько понятно написана документация? Не заброшен ли проект? Может проще и полезнее для сообщества самому исправить найденные недочеты? Ответы на эти вопросы помогут в создании собственного решения.

Выбор названия

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

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

Давайте рассмотрим библиотеки с хорошими названиями:

• use-debounce — хороший пример краткого нейминга. Глагол use дает понять, что речь идет о реактовском хуке, а debounce — собственно, о дебаунсе.

• Day.js — и снова название короткое, но запоминающееся и уникальное. Разработчики сразу могут понять, что это JavaScript-библиотека, которая отображает дату для браузеров с API.

Выбор лицензии

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

Чтобы разобраться в огромном количестве лицензий необязательно иметь юридическое образование. Команда GitHub создала сайт, чтобы помочь разработчикам понять, как лицензировать код. Для выбора подходящей лицензии нужно определиться, какие цели вы преследуете при создании своего решения. MIT, Apache 2.0 и GPLv3 — самые популярные лицензии с открытым исходным кодом, но есть и другие варианты на выбор.

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

README.md

При установке библиотек пользователи чаще руководствуются не объективной полезностью, а количеством звезд на GitHub и ее популярностью, а к новым проектам относятся к подозрением. Поэтому README.md не только должен описывать назначение проекта, но и всячески подчеркивать преимущества библиотеки, убеждать потенциального пользователя, чтобы он установил именно ее, а не более популярный аналог. 

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

1. Какое назначение проекта? Описание должно быть лаконичным и отражающим суть проекта.

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

3. Как приступить к работе с библиотекой? Этап с установкой и настройкой библиотеки необходимо описать самым детальным образом. Ведь далеко не всегда то, что очевидно вам — очевидно другим. Решением могут пользоваться люди, у которых совершенно другой опыт. Нужно, чтобы любой желающий, кто хочет установить решение, понял, как это сделать.

4. Где можно получить дополнительную помощь, если она мне понадобится? Обязательно оставить свои контакты или другую предпочитаемую форму взаимодействия.

5. Можно использовать свой README для ответа на другие вопросы. Например, дальнейшие цели в развитии проекта, информация о лицензиях, важных изменениях в коде.

Ответив на данные вопросы, набросаем примерный план README:

• Краткое описание, преимущества библиотеки по сравнению с ее аналогами (если возможно, с изображениями и конкретными цифрами).

• Установка и настройка. 

• Ссылка на демо (если есть).

• Примеры кода.

• Описание API.

• Деплой. 

• Как контибьюрить.

• Прочая информация (контакты, информация о лицензии).

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

Рассмотри качественный пример README на библиотеке colord. 

Яркая и привлекающая внимание картинка. Краткое описание проекта, которое дает представление о назначении библиотеки и ее преимуществах.

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

После такой убедительной презентации хочется установить библиотеку, даже если она вам не нужна :)

Следом идет описание API c примерами использования. Просто и понятно, можно сразу копировать в проект :)

Сommunity Standards

Обычно на этом этапе многие создатели думают, что хорошо заполненного README.md достаточно и останавливаются на достигнутом. Но это далеко не так.

GitHub создал раздел Community Standards, чтобы авторы могли оценить, насколько репозиторий соответствует общепринятым стандартам качества. Для этого надо перейти на вкладку Insights и выбрать опцию Community из левой панели. Большинство пунктов остались незаполненным. Давайте разберемся с ними по порядку.

СODE_OF_CONDUCT.md

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

Как и в случае с лицензиями, существуют готовые кодексы поведения. Их можно найти в Contributor Covenant, поэтому вам не придется писать собственные правила. Вставьте текст в файл CODE_OF_CONDUCT.md в корневом разделе репозитория, можно также сделать ссылку на него в README.md.

СONTRIBUTING.md

Этот файл рассказывает о том, как принять участие в проекте. Он может включать следующую информацию:

1. Какие существуют способы внесения вклада в проект.

2. Как сообщить о найденных ошибках.

3. Как установить библиотеку для внесения правок.

4. Какие функции мы планируем запустить в будущем (роадмап).

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

Как и в случае с CODE_OF_CONDUCT.md, можно сделать ссылку на CONTRIBUTING.md в README.md, чтобы больше людей увидели его. Любому, кто откроет issue или создаст PR в репозитории, будет предложено прочитать руководство.

Security Policy

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

После включения файл будет отображаться на вкладке Security и при создании нового issue. Более подробную инструкцию о формировании инструкции можно найти здесь.

ISSUE AND PR TEMPLATES

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

Чтобы создать шаблон, нужно добавить файл config.yml в папку .github/ISSUE_TEMPLATE. Для получения дополнительной информации можно обратиться к статье, которую подготовила команда GitHub.

Для понимания того, как создавать качественный ISSUE TEMPLATE, обратимся к репозиторию библиотеки left-hook.

Мейнтейнер разделил все issue на 6 типов:

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

2. Пул-реквест по введению нового функционала. Есть дополнение, что если нет четкого понимания по новой фиче, можно предложить идею и обсудить ее. Таким образом, мейнтейнер дает понять, что идеи без готовой реализации очень ценны для библиотеки.

3. Политика безопасности. Репорт об обнаружении проколов в безопасности. Этот момент мы разбирали в главе Security Policy. 

4. Обсуждение новой идеи. Де-факто потенциальный склад новых идей для мейнтейнера.

5. Вопрос общего характера без привязки к конкретной реализации или проблеме.

6. Запрос помощи — вопрос по конкретной проблеме.

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

Похожий алгоритм и с PULL_REQUEST_TEMPLATE.md. Гораздо проще понимать пул-реквесты при наличии подробного и формализованного описания. Чтобы сделать такой шаблон, нужно создать файл в папке .github/pull_request_template.md. 

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

После прохождения всех шагов, вы увидите увидеть полностью заполненный раздел Community Standards. А это значит, что вам удалось ПОЧТИ (да, еще не все) подготовить репозиторий.

Status Check

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

Protected branches

Каждое правило защиты веток запрещает принудительное внесение изменений (force push) в соответствующие ветки и предотвращает их удаление. Помимо этого, есть и множество других правил защиты: требования апрува перед мерджем ветки или успешного деплоя ветки в определенной среде перед мерджем.

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

GitHub Labels

С помощью специальных лейблов можно помечать issue или PR для более удобной работы с ними. Такие лейблы как good first issue или help wanted позволяют привлечь дополнительное внимание к той или иной проблеме.

Помимо стандартных лейблов от GitHub, можно создавать свои с произвольными именами и цветами. Более подробную информацию можно найти в разделе Managing labels в документации GitHub.

Изображение для социальных сетей

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

Чтобы добавить изображение, необходимо кликнуть на вкладку Settings, в разделе General можно увидеть надпись Social Preview — это то, что нужно.

Шаблонный репозиторий

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

Перейдем в Settings и установим флажок в чекбоксе Template repository. Теперь все будут видеть кнопку Use this template и смогут создать новый репозиторий с той же структурой каталогов и файлами, что и в шаблонном.

Спонсорство

Наконец, можно включить спонсорство — возможно, кому-то настолько понравится ваша библиотека, что они будут готовы поддержать нас. Перейдем в Settings и установим флажок в чекбоксе Sponsorship. Далее следуем инструкциям, чтобы добавить ссылки на финансирование. 

Чеклист

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

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

P.S. Обязательно посмотрите доклад Андрея Ситника про продвижение опенсорс-проектов. Он рассказывает о текущем состоянии фронтенда и делится советами о том, как правильно делать свои решения более популярными.