Предисловие переводчика

Пару месяцев назад на Гитхабе случайно наткнулся на ссылку «Open source guides» и не мог оторваться. Где-то за неделю я внимательно прочитал все 10 разделов. Конечно, я и раньше знал про open source: читал разные статьи (например, «Понять Open Source»), использовал такие проекты в работе, обращался с вопросами к сообществам, сообщал о багах, рыскал в issues и, даже делал неуклюжие попытки что-то улучшать, хотя бы документацию. И само собой, сердцем я был с этими ребятами, которые делятся софтом и знаниями по его использованию. Тем не менее, понятие об open source у меня было скорее смутное и обрывочное. А эта статья добавила ясности.

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

Вне зависимости от вашего отношения к open source, думаю, вы найдёте в этой серии из 10 статей много интересных идей и фактов: организационных, психологических, юридических, этических и технических.

Я дал прочитать этот текст нескольким непрограммистам, они сказали, что всё поняли. А в заголовке статьи я намеренно поставил «исходник» без «кода», потому что данная тема актуальна не только для программистов, а почти для любой интеллектуальной деятельности в формате открытого проекта.

Само это руководство также является open source и уже переведено на 14 языков. Мне выпала честь добавить русскую ветку и перевод первой статьи. Я планирую и дальше переводить по статье в неделю. Если кто хочет подключиться, вот репозиторий: Open Source Guides.

Если вдруг кому-то понадобиться заставка из шапки статьи (иллюстрации + русские названия), то она есть в сверстанном виде на codesandbox.io.

Подбор терминов

Я заранее извиняюсь за огрехи в переводе. Некоторые, казалось бы банальные термины, не так легко подобрать на русском. Например, to contribute, pull request, issue, я чаще переводил как «участвовать в проекте, предлагать исправления и вопрос». Open source я пока оставил на английском. Мне уже сделали замечание и выслали ссылку на словарь терминов Гитхаба. Мне не понравилось там обилие транслитерация. Если пустить в статью все эти ишью, пулреквест, пуш, пул, форк, то она станет непонятной для всех, кто не работал с Гитхабом.

Да, issue может быть вопросом, задачей, сообщением о баге, предложением и т.д, и трудно подобрать одно русское слово, которое бы передавало все эти смыслы. Но английское слово issue тоже без особо широкого смысла, просто создатели и пользователи Гитхаба наделили его такой широтой. Если мы будем под словами «открыть вопрос на Гитхабе» подразумевать, что этот вопрос может быть очень разным (баг, вопрос, просьба о помощи, задача, ...), то слово «вопрос» гармонично заменит слово «issue». Также — push — отправить, pull — принять, fork — ответвление и т.д. Важно не само слово, а тот смысл, который мы условились вкладывать в него. Англичанам, кто первый раз сталкиваются с термином issue на Гитхабе, также приходится сначала прочитать описание всех его возможных значений в рамках данной системы. Пока же я беру за приоритет понятность для максимального количества людей, не работавших с Гитхабом. В любом случае, подбор терминов в процессе, и весь перевод как и оригинал — open source, поэтому делайте пулреквесты и открывайте ишью.

Оглавление

Открытый исходный код: что это и зачем?
Что означает «open source»?
Почему люди делают свою работу открытой?
Open source — значит бесплатно?

Стоит ли мне запускать свой open source проект?
Постановка целей
Участие в чужих проектах

Запуск собственного open source проекта
Выбор лицензии
Составление README
Написание руководства для участников
Разработка кодекса поведения

Именование и брендирование вашего проекта
Выбор правильного названия
Конфликт имён
То, как вы пишите (и кодите) тоже влияет на ваш бренд!

Проверочный лист перед запуском
Документация
Код
Люди

Открытый исходный код: что это и зачем?

Итак, вы думаете о запуске своего проекта с открытым исходным кодом (open source)? Поздравляем! Мир ценит ваш участие. Давайте поговорим о том, что такое open source и почему люди это делают.

Что означает «open source»?

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

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

Свободное ПО (Free software) ссылается на те же проекты, что и открытое ПО (open source). Иногда вы можете встретить комбинации этих терминов: «Свободное и открытое ПО» (free and open source software FOSS или free, libre, and open source software FLOSS). Слова free и libre здесь означают «свободное», а не «бесплатное».

Почему люди делают свою работу открытой?

Одно из самых больших вознаграждений, которое я получил от open source — это отношения, установившиеся с другими разработчиками, столкнувшимися с такими же проблемами как и я.
@kentcdodds, «Как мне было здорово войти в Open Source»

Есть много причин почему индивид или организация открывают исходники своего проекта. Вот некоторые из них:

• Сотрудничество: Open source проект может получать доработки от любого человека из любой страны мира. Например, платформа для упражнения в программировании Exercism, делается усилиями 350 авторов.
• Адаптация и ремиксы: Open source проект может быть использован кем угодно, почти для чего угодно. Люди могут использовать ваш проект совершенно по-новому. WordPress, например, стартовал как ответвление уже существовавшего проекта b2.
• Прозрачность: Любой может проверять open source проект на ошибки и несоответствия. Прозрачность важна даже на государственном уровне. Например, правительство Болгарии и США законодательно предписали прозрачность для таких отраслей как: банковское дело, здравоохранение, и ПО безопасности, вроде Let's Encrypt.

Open source (открытый исходник) применимо не только к ПО, но и ко всему остальному: от наборов данных до книг. В Обзоре GitHub вы можете почерпнуть больше идей насчёт того, что можно заопенсорсить.

Open source — значит бесплатно?

Бесплатность open source — это одно из его самых больших преимуществ, но не единственное, а скорее — побочный продукт его совокупной ценности.

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

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

Стоит ли мне запускать свой open source проект?

Краткий ответ — да, потому что независимо от результата, запуск своего проекта — это хороший способ понять, как работает open source.

Если вы никогда прежде не запускали подобных проектов, вы можете переживать: «что скажут люди?», «а вдруг вообще никто его не заметит?». Если вам это знакомо, не беспокойтесь, вы не один такой!

Open source, как и любая творческая работа, будь то писательство или рисование, вызывает волнение прежде чем поделиться ей с миром. Но единственный способ улучшить её — практиковаться, даже если у вас не будет аудитории.

Если вы ещё не решились, найдите время подумать о ваших возможных целях.

Постановка целей

Цели помогут вам определиться, над чем работать, от чего отказаться, и где вам понадобится помощь со стороны. Спросите себя: «зачем я опенсорсю этот проект?».

Единого ответа на этот вопрос не существует. Вы можете иметь много целей для одного проекта, или разные проекты с разными целями.

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

Однажды я сделал настраиваемый UIAlertView для своих нужд… и решил сделать его open source. Я сделал его более динамичным и загрузил на GitHub. Я так же написал свою первую документацию, объясняющую другим разработчикам, как они могут использовать мою работу в своих проектах. Возможно, ей так никто и не воспользовался из-за её простоты. Но зато я испытал хорошее чувство от всего этого процесса.
mavris@mavris, «Программисты самоучки: Почему Open Source важен для нас»

По мере роста проекта ваше сообщество будет нуждаться не только в коде. Ответы на вопросы (issues), проверка кода, распространение информации о себе — всё это важные задачи open source проекта.

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

Если вы — часть компании, запускающей open source проект,, убедитесь заранее, что вы имеете внутренние ресурсы для его развития. Назначьте ответственного за сопровождение после запуска и определите, как будут распределяться задачи внутри сообщества.

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

Когда вы начинаете open source проект, важно, чтобы процессы управления в организации учитывали вклад и возможности сообщества, образовавшегося вокруг проекта. Не бойтесь вовлекать посторонних людей, даже в ключевых аспектах, особенно если они активно участвуют.
@captainsafia, «Чё, хочешь открыть код проекта?»

Участие в чужих проектах

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

Если вы не понимаете, как начать участие в чужом проекте, ознакомьтесь с нашим руководством Как участвовать в open source проекте.

Запуск собственного open source проекта

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

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

Каждый проект вне зависимости от стадии, на которой вы решили открыть исходники, должен иметь следующую документацию:

• Лицензию open source
• README
• Руководство для участников
• Кодекс поведения

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

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

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

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

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

MIT, Apache 2.0, и GPLv3 — это самые популярные лицензии, но есть и другие варианты для выбора.

Когда вы создаёте новый проект на Гитхабе, вам дается на выбор несколько лицензий. Выбрав open source лицензию, вы сделаете свой проект — открытым.



Если у вас есть другие вопросы или беспокойства относительно юридических аспектов open source, мы описали их здесь.

Составление README

Файл README («прочитай меня») не только рассказывает, как использовать ваш проект, но и объясняет, почему он важен, и что пользователи могут с ним делать.

Постарайтесь ответить в README на следующие вопросы:

• Что делает этот проект?
• Чем этот проект полезен?
• Как я могу начать работать с ним?
• Где я могу получить помощь, если понадобится?

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

Хорошая документация — это больше пользователей, меньше просьб о помощи, и больше соавторов. (...) Помните, что ваши пользователи — не вы. Это могут быть люди с опытом — сильно отличным от вашего.
@tracymakes, «Писать так, чтобы ваши слова читали (видео)»

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

Для вдохновения, можете почитать «Сделай README» — руководство или Шаблон README.

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

Написание руководства для участников

Файл CONTRIBUTING говорит вашей аудитории, как стать участником вашего проекта. Например:

• Как сообщить об ошибке (попробуйте использовать шаблоны для issue и pull request)
• Как предложить новую функцию
• Как настроить среду выполнения и запустить тесты

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

• Какого рода участие вы ждёте?
• Ваши планы и видение развития проекта
• Как участники могут (и не могут) связываться с вами

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

Например, Active Admin начинает своё руководство по участию с таких слов:

В первую очередь хотим выразить вам благодарность за то, что подумываете об участии в развитии Active Admin. Именно такие люди как вы делают Active Admin прекрасным инструментом.

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

Со временем вы можете дополнить его ответами на часто задаваемые вопросы. Благодаря этому меньше людей будут спрашивать вас об одном и том же снова и снова.

Чтобы вам было проще составить файл CONTRIBUTING, ознакомьтесь с @nayafia's шаблоном руководства по сотрудничеству или mozilla's «Как составить файл CONTRIBUTING.md».

Поставьте ссылку на файл CONTRIBUTING внутри README, так больше людей увидят его. Если вы разместите файл CONTRIBUTING.md в корне вашего проекта, то Гитхаб будет автоматически ссылаться на него, когда кто-то открывает новый вопрос (issue) или добавляет правку в проект (pull request).

Разработка кодекса поведения

Все мы сталкивались с неприятными ситуациями, когда хозяин проекта грубо объяснял что-то или пользователи задавали элементарные вопросы. (...) Кодекс поведения становится документом, на который легко ссылаться, и который говорит, что ваша команда очень серьезно относится к конструктивному диалогу.
@mlynch, Делаем open source более счастливым местом

В итоге, кодекс поведения задаёт базовые правила поведения для участников вашего проекта. Это особенно важно, если вы запускаете проект для компании или сообщества. Кодекс поведения способствует установлению здорового, конструктивного поведения в сообществе, что снижает стресс для вас, как для ответственного за проект.

Подробнее смотрите: Кодекс поведения — руководство.

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

По аналогии с лицензией, вам не обязательно писать кодекс самим, а можно скопировать один из существующих вариантов. Соглашение участника используется в более 40,000 open source проектах, включая Kubernetes, Rails, и Swift. Какой бы кодекс вы не использовали, вы должны быть готовы применить его при необходимости.

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

Именование и брендирование вашего проекта

Брендирование — это не только броский логотип и запоминающееся название, но и то, как вы говорите о своём проекте и до кого доходит ваше послание.

Выбор правильного названия

Выберите название, которое легко запомнить и, в идеале, даёт представление о сути проекта. Например:

• Караул оповещает о падении приложения.
• Дрищ быстрый и простой веб-сервер на Ruby.

Если ваш проект — это дополнение к существующему проекту, то используйте его название как префикс, это поможет понять, что делает ваш проект. Например node-fetch привносит `window.fetch` в Node.js).

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

Конфликт имён

Проверьте наличие open source проектов с таким же названием, особенно если вы используете один и тот же язык или экосистему. Если ваше название совпадёт с популярным существующим проектом, вы можете запутать свою аудиторию.

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

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

Вы можете проверить конфликт брендов по всемирной базе брендов WIPO. Если вы делаете проект от лица компании, то юридический отдел может помочь вам с этим.

Напоследок, сделайте быстрый поиск в Google по названию вашего проекта. Смогут ли люди по нему легко найти ваш проект? А может быть, по этому запросу появляется что-то нежелательное?

То, как вы пишите (и кодите) тоже влияет на ваш бренд!

За всю жизнь проекта вы будете много писать: README, руководства, документы сообщества, ответы на вопросы, возможно даже информационные бюллетени и списки рассылки.

Будь то официальная документация или обычное сообщение, ваш стиль письма — это часть бренда проекта. Подумайте о том, в каком свете вы выглядите перед аудиторией, и правильный ли подобрали тон.

Я старался участвовать в каждой теме в списке рассылки и показывать образцовое поведение, быть доброжелательным к людям, серьезно относиться к их проблемам и быть полезным в общем. Через некоторое время люди стали не только задавать вопросы, но и помогать с ответами, и, к моему полному восторгу, они подражали моему стилю.
@janl, CouchDB, «Устойчивый Open Source»

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

Не только слова, что вы пишете, но и стиль кода может стать частью бренда вашего проекта. Angular и jQuery два примера проектов со строгими стилями и рекомендациями.

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

Проверочный лист перед запуском

Вы готовы открыть свой проект? Вот вам проверочный лист в помощь. Когда отметите все пункты, нажмите «опубликовать» и похвалите себя.

Документация

• В проекте есть файл LICENSE с лицензией open source
• В проекте есть базовая документация (README, CONTRIBUTING, CODE_OF_CONDUCT)
• Название легко запоминается, даёт представление о сути проекта, не конфликтует с существующими проектами и не посягает на торговые марки.
• Список задач (issues) актуальный, хорошо организованный и помечен ярлыками

Код

• Проект использует согласованные договорённости по коду и понятные названия функций/методов/переменных
• Код понятно комментируется, документируются замыслы и особые случаи.
• Нигде нет чувствительных данных вроде паролей или другой не публичной информации — в истории ревизий, вопросах (issues) и запросах на правки (pull requests).

Люди

Если вы частное лицо:

• Вы поговорили с юридическим отделом и/или поняли правила интеллектуальной собственности и политику open source вашей компании (если вы где-то трудоустроены)

Если вы юридическое лицо:

• Вы поговорили с юридическим отделом
• У вас есть маркетинговый план для запуска и продвижения проекта
• Кто-то назначен ответственным за взаимодействие с сообществом: отвечать на вопросы (issues), проверять запросы на правки (pull requests) и присоединять их к проекту
• Как минимум два человека имеют административный доступ к проекту

Вы сделали это!

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