Comments 124
Документация, по моему опыту, это прям беда беда. Крайне редко видел open source проекты с адекватной документацией.
Вторая частая беда - невозможность найти уже собранную библиотеку/модуль/программу. Часто разработчики думают (да?), что все пользователи должны скачать исходники, скачать билд-систему, скачать все зависимости, всё настроить и только потом построить проект. Приходится гуглить в поисках других сайтов, предоставляющих бинарники этого проекта, конечно же, с вероятностью напороться на устаревшую версию или зловреда.
Честно говоря, я и не опен-сорс проекты с приличной документацией не видел. Вот, например, искал недавно возможность работать с вебсокетами, так ничего приличнее буста не нашел, а на мелкомягком сайте не документация, а даже не знаю и что - полный бардак. Но это в части разработки ПО, конечно. А в части его использования, предположу, что-то может быть иначе.
Я видел. Только это было ещё в начале нулевых. Тогда было принято вместе со средой программирования поставлять исчерпывающую документацию. Например, Delphi был документирован так, как ни одному современному проекту даже не снилось, вплоть до мелочей. И к каждой функции каждого компонента - обязательно примеры использования с указанием того, что получается в результате. Причём справку по нужной команде или API можно было вызвать прямо из IDE, наведя курсор на эту команду прямо в редакторе кода.
И исходники значительной части фреймворка прилагались, причём откомментированные, а не как сейчас, когда в проекте из всех комментариев - шапка лицензии.
Это было принято до прихода в массы интернета в широком смысле этого слова, и сайтов типа SO, поскольку без такой документации использовать Delphi в те времена было бы просто невозможно. Это касалось и проектов на том же sourceforge.
И исходники значительной части фреймворка прилагались, причём откомментированные, а не как сейчас, когда в проекте из всех комментариев - шапка лицензии.
Комментарии в исходниках - зло. Из файлов получаются простыни - палец от скрола начинает болеть. Код меняется, а комменты остаются старые - потом пойди разбери.
Код должен быть самодокументируемый. Писать таковой - искусство.
А вот краткий readme к проекту необходим.
В любой нормальной IDE есть возможность скрыть все комментарии, если вдруг они вам мешают или скроллить лень.
Самодокументируемый код для любого более-менее нетривиального алгоритма написать не получится. Попробуйте без комментариев разобраться, скажем, в коде xz-архиватора. Вот есть данные, над ними проводится куча каких-то странных преобразований. Код вроде не лапша, но ни хрена не понятно: что это за математика, в чём суть алгоритма и как вообще в этом искать ошибку?
Это же касается внутренностей фреймворков. Там очень часто делаются сильно нетривиальные вещи, и без комментариев можно долго гадать: то ли этот кусок написан какими-то индусами, которые сами не ведали, что творили, то ли тут какая-то хитрая оптимизация, то ли багфикс для каких-то экзотических условий...
Вот устаревание комментариев, когда их забывают обновлять вместе с кодом - это да, проблема. Но если проект Open Source, то разве расхождение между кодом и комментариями не будет рано или поздно замечено кем-либо из пользователей и исправлено первым же пулл-реквестом?
В любой нормальной IDE есть возможность скрыть все комментарии, если вдруг они вам мешают
Отключить и разбираться в коде, который писался с прицелом на комментирование, а не на самодокументированине? Безрассудно.
скроллить лень
Боль в суставе указательного пальца это не лень, а проф. заболеаание.
Попробуйте без комментариев разобраться, скажем, в коде xz-архиватора.
Приводите пример того как не надо писать код?)) https://git.tukaani.org/?p=xz.git;a=blob;f=src/xz/hardware.c;h=c6948821862ae4803100cf1081698630dad61057;hb=refs/heads/master Но согласен, абсолюта не существует. Допускаю, что имеет право на жизнь одна строка комментария на тысячу строк кода. Иначе это превращается в то, что по ссылке.))
без комментариев можно долго гадать: то ли этот кусок написан какими-то
индусами, которые сами не ведали, что творили, то ли тут какая-то хитрая
оптимизация, то ли багфикс для каких-то экзотических условий...
И это ваш аргумент за то, чтобы не писать самодокументирующийся код, а слиться и писать говнокод повсеместно? Т.е. ленью и некомпетентностью других готовы оправдать и свой говнокод. Браво!
исправлено первым же пулл-реквестом
Не первым. У него свои задачи и дедлайны. А до той поры пусть сотня человек потеряет кучу времени пока не найдётся тот замечательный человек, который исправит за автором - нехорошим человеком. Неэффективно это.
Неприемлю вашу позицию. Пишем самодокументирующийся код, товарищи!
Ну, мелкие проекты на гитхабе чаще всё же идут с бинарниками. Кто поглупее - хранит их прямо в гите, кто поумнее - выкладывает релизы.
А вот проекты GNU это да, анекдот. Особенно под винду.
Последняя моя попытка скачать банальный gcc привела меня к pacman, у которого я так и не нашёл команды "установить пакет". В итоге выручил какой-то ноунейм (для меня), выложивший свою свежую сборку на своём сайте, что родом из того первого веба....
pacman, у которого я так и не нашёл команды "установить пакет"
Вы сейчас серьезно?
https://wiki.archlinux.org/title/pacman
o install a single package or list of packages, including dependencies, issue the following command:
# pacman -S package_name1 package_name2 ...Ну, я дошёл до того сайта с бинарниками раньше чем заглянул на вики Archlinux.
Я просто не так давно bash в винде разворачивал, как раз столкнулся, но нашел за минуту.
Да, я не сказать, что вот прям горой за свободное ПО, но без него было бы грустно. Сам я на линух переходил с 2005-го по 2007-й, и очень много по первому времени плевался. Сейчас вот плююсь на оутлук со скайпом для бизнеса от мелкомягких - на мой взгляд, хуже систему вряд ли можно придумать. Скайп даже картинки открывает через стандартный просматривальщик, хотя та же телега и воцап даже в веб-версии делают это самостоятельно. И это только малая часть неудобств. А почему колюсь, плачу и продолжаю есть кактус? Так корпоративный скайп - это то немногое, что наши админы научились разворачивать локально (большая контора в Мск с населением 2к+ человеков). На прошлой работе был майчат (банковская группа в ТОП 3), он был еще хуже скайпа. При видеозвонке постоянно рубился и 10-минутный диалог превращался в 20-минутный, 10 минут которого уходило на переподключения. И ведь все пропиетарное..
ЗЫ: https://archlinux.org/pacman/pacman.8.html - вот просто "man pacman" уже дает ответы на все вопросы. Сравните с хелпом для мелкомягких утилит - небо и земля.
Ещё обычно не стОит устанавливать докер командой sudo apt install docker :)
Потому что скорее всего он установит немного не то, что требовалось.
("Docker is a docking application (WindowMaker dock app) which acts as a system
tray for any desktop environment, ...")
Полностью согласен с тем, что с документацией у многих опенсорс проектов большая проблема. Тут сразу вспоминается частое заблуждение про "чистый код == понятный проект", но, к сожалению, это далеко не так, и без хорошего описания любая разработка будет мало полезна. При этом я могу понять разработчиков, которые не любят писать документацию - очень уж это трудоёмкий процесс, который отнимает много времени. Но я надеюсь, что после прочтения статьи, кто-нибудь из создателей плохо задокументированного open-source проекта лишний раз задумается о её необходимости...
Пользователь пакета/продукта не должен смотреть исходники, неужели это непонятно? Весь любой продукт делается для пользователей, а не для участников собственно проекта.
Open source проектами занимаются либо большие компании, которые получают непрямой доход от проекта (например, поддерживают ядро Linux, чтобы был софт для железа, которое они продают, или делают платное IDE для языка, компилятор которого опенсорс) - и тогда всё с документацией как правило нормально, потому что большая компания может позволить себе нанять на зарплату помимо армии разработчиков, ещё технических писателей, developer advocate и т.д; либо одиночки-энтузиасты, которым просто по кайфу запрограммировать что-то вечером после работы. Во втором случае странно призывать их писать документацию - они делают то, что им нравится, т.е. пишут код, решая некоторую техническую задачу.
Кстати, вчера вечером в целях прочитать gz-файл в своем небольшем С++ проекте натолкнулся на либу zlib. У нее сайтик с 90-х годов обновлялся только информационно, никаких SSL нет. Но чел, который это написал, работал тимлидом в гугле. И не сказать, что документация плохая, только я из заголовочных файлов больше понял, чем из текста. Хотя потом и на сайте нашел, где это все написано. Но да, не стековерфлоу...
Тут скорее вопрос в том, хочет ли энтузиаст-одиночка, чтобы его проект использовали.
Лично я, когда ищу какую-нибудь странную либу на github, смотрю хотя бы на наличие readme и в идеале примеров использования.
Когда сам написал пару openSource библиотек, посмотрел на них и: "эх, ну ладно, надо теперь завернуть в nuget и написать минимальный readme"
GNU подобные лицензии требуют выкладывать код, а не писать документацию. Возможно, отсутствие документации - задел на дальнейшую манетизацию через техподдержку и консультации
Есть такой интересный проект - ory kratos/keto, это внешняя аутентификация. То есть, пишешь свой проектик и не надо писать для него аутентификацию (а написать ее правильно - задачка не простая, много мест для опасных ошибок) - очень удобно! Причем это отдельный сервис - можешь прямо сам у себя его хотить. А можешь пользоваться их сервисом.
Но зачем пользоваться их сервисом, если проект опенсорсный, с гитхабом и они даже докер образы раздают и туториалы имеют? проще у себя хостить!
Вот только их же туториал не срабатывает на уровне первой же задачки уровня hello world. Почему-то сервис отвечает 404. Хз почему. Есть тикет в их проекте examples от 30 августа ПРОШЛОГО года. Легкая активность в тикете (новые пользователи приходят, ноют) но никакого ответа от разработчиков уже больше года. И это на этапе первого знакомства с проектом, на этапе hello world.
То есть, если ты хочешь сервис и платить за него - пожалуйста! И в отличие от конкурентов - тут вроде бы есть преимущество, опенсорс (ай какие молодцы). Если ты колеблешься - то начинаешь пробовать, пытаться, у тебя не получается, и ты такой "ай нафиг, оплачу их сервис!". Тоже хорошо. Но если ты хочешь пользоваться их продуктом и не платить им - хренушки (ну или преодолевай трудности самостоятельно). И есть подозрение, что возможно их отдел маркетинга как-то причастен к этому. Потому что из 10 человек, кто хотели халявы и обломались на хелловорлде, сколько-то купят услугу.
Эдакий фейк-оперсорс.
Эта стандартная проблема опенсорса. Лицо библиотеки раздел "get started" в 99% случаев не работает уже на 1 команде, макс на 2.
Сейчас в опенсорсе много урезанных вещей, где авторы параллельно предлагают собственный SaaS с доработками за деньги.
Тут версия с открытыми исходниками даёт возможность в полной мере познакомиться с функциональностью. Но использовать продукт внутри компании скорее всего не выйдет. Классика - отсутствие какой-либо авторизации в многопользовательских продуктах, аудита, ограничения по типу хранилищ данных и т.п.
Собрать все зависимости бывает тот еще квест. А еще зависимости к зависимостям))))
Не сыпь мне соль на рану! Она ещё болит.
Буквально на последнем проекте потратил на это пару дней. Еще та боль. А если еще принять во внимание, что многие публичные сайты с софтом и open source были заблокированы корпоративным фаерволом....
Это основная причина, по которой от C++ сейчас бегут как от чумы: бывает проще написать проект с нуля, чем заставить уже написанное собраться на своей машине. По уму бы плюсовикам прикладывать к исходникам docker-контейнер с полностью настроенной средой сборки, иначе большинство потенциальных участников просто пройдёт мимо: кому охота неделями решать проблемы со сборкой?
Невоспроизводимый docker-контейнер слабо отличается от невоспроизводимого бинарника, а если нужен воспроизводимый контейнер - проблемы с зависимостями возникают снова, помноженные на проблемы докера.
Не понимаю, как джокер файл может быть не воспроизводимым. Он или собирается или нет
Для начала, он в принципе нужен, в комментарии выше предлагалось прикладывать именно контейнер (точнее, образ), а не dockerfile.
Ну а дальше всё просто. Во-первых, в докере до сих пор нет лок-файлов, а значит ссылка на любой образ с плавающим тэгом может внезапно перестать работать.
Идём дальше. Откуда вообще dockerfile может получить бинарные зависимости? Либо из репозитория с исходниками, либо из реестра образов, либо из репозиториев пакетов, либо скачать. В репозитории хранить бинарные зависимости - дурной тон, в реестре нужного нет (иначе зачем нам вообще собирать образ?), остаются пакеты и скачивание.
Пакеты - вещь хорошая, но если все бинарные зависимости есть в пакетах - зачем вам вообще контейнер для сборки?
Вот и остаётся единственной штукой, с которой действительно помогает докер, скачивание бинарников из интернета. Но нужно ли объяснять, что в интернете периодически случается с прямыми ссылками на скачивание бинарников?
Опишу свой опыт с другой стороны. Я вот поддерживаю свой компилятор Java/Kotlin/Scala в JavaScript. Какая-то документация есть. Но документация в стиле "вот так вы можете сгенерировать JS". При этом документация не раскрывает, например, следующие моменты:
Как подключить JS к HTML-файлу (потому что это элементарная культура, про это вообще в интернете куча всего)
Как завести gradle или Maven проект
Как обеспечить копирование какого-то файлика в директории сборки в WAR-файл
Как поднять HTTP-сервер и задеплоить в нём, например, WAR-файл
Как работают те или иные JS API (например, тот же DOM) - есть только документация о том, как их вызывать из Java кода
Как отлаживать JS в браузере
Как настроить webpack и чем ES2015 modules отличаются от CommonJS
И вот не поверите, всё это у меня постоянно спрашивают пользователи, недовольные тем, что "у проекта нет документации". Когда я кому-то из них по какой-то причине всё-таки помогаю (т.е. по сути помогаю с ИХ проблемой, а не с пониманием, как пользоваться МОИМ компилятором), то угадайте, сколько таких несчастных в ответ написали хоть один туториал в репозиторий с документацией по проекту?
Ещё часто пользователи просто не могут глазами спарсить сообщение об ошибке, где им чёрным по белому расписано, почему что-то не работает. При этом есть ещё небольшая прослойка адекватных пользователей, которым, как оказывается, документация вообще не нужна, потому что они давно склонировали репозиторий и нашли в нём папку samples, где уже есть готовые примеры - изучай нехочу, да папку tests, где, не поверите, лежат тесты, которые являются по совместительству ещё и примерами использования проекта.
Что касается бинарников - обычно для всяких кросплатформенных сред с этим всё сильно лучше. И тут я вам открою страшную тайну: собрать дистрибутив на Rust или C++ под все платформы - это то ещё приключение (хотя бы в силу отсутствия того или иного железа в наличии у мейнтейнера). В случае той же Java это не проблема - собирай себе на любой машине и это запуститсяу кого угодно.
В догонку вспомнился один случай - как-то про мой проект кто-то упомянул в комментариях к посту в hacker news. И несколько пользователей сразу пожаловались - а по документации проекта не понятно, как вообще начать его использовать. При том, что документация getting started была - как с помощью строчки в CLI создать пустой проект hello world. Естественно, в шаблоне я добавил комментариев, чтобы человек мог создать проект, посмотреть код и увидеть тут же объяснение. Но видимо, они не осилили скопировать текст в консоль, или просто не знали, что в IDEA есть поддержка архетипов в UI - и сразу сделали вывод.
Ещё момент: многие разработчики open source проектов попросту не являются native english speaker и писать документацию с условным B2 (а именно на нём часто люди застревают в плато, с которого в C1 непонятно как попасть, не посвящая вообще всё свободное время планомерному изучению - где же тогда взять время на кодинг) довольно-таки сложно и медленно. И, наконец, разработчику не всегда очевидно, что может вызвать затруднения у других.
Пишите на своём родном языке. Именно так поступают китайцы с японцами: делают на английском одну только заглушку, а все доки - на их родном языке.
И такая документация не в пример лучше её отсутствия или скудных пяти строчек на английском. Потому что, во-первых, автоматические переводчики уже достаточно развиты, чтобы любой иностранец более-менее понял переведённое, и во-вторых, переводить доки намного проще, чем писать их с нуля. И если проект популярен, то шанс, что кто-то из англоязычных сделает перевод, близок к 100%. А вот шанс, что кто-то напишет за вас документацию - напротив невысок, даже для очень популярного проекта.
писать документацию с условным B2
Этого уровня более чем хватает для написания технической документации, C1 здесь не нужен. Скорей проблема будте в том, что разработчик в принципе не особо умеет ее писать.
B2 хватает, это факт. Другое дело - это скорость и нагрузка. По-русски я пишу быстрее и лучше, при этом прикладывая меньше усилий. И да, я "-тся" и "-ться" не путаю, "не" знаю когда писать раздельно или слитно, но вот те же артикли так и не осилил во всех нюансах.
артикли так и не осилил во всех нюансах
Это и не нужно, их неправильное использование почти никогда не влияет на смысл, а нейтивы сами в них ошибаются (как и в других вещах, например, делают вопрос интонацией, а не изменением порядка слов). Собствено то же самое относится и к "-тся", "-ться", "не" - эти мелочи не влияют на донесение информации, а разработчик не является лингвистом, чтобы безукоризненно писать тексты.
Вам В2 хватит написать разве что очень дохлую документацию. Вообще документацию должен писать носитель языка, иначе получается шляпа как ты её не пиши.
угадайте, сколько таких несчастных в ответ написали хоть один туториал
Может и слава Богу? Я в интернете уже устал от туториалов на medium.com от индусов которые вчера сами прошли туториал по какой-то теме, а сегодня написали его своими словами.
Вообще, это отдельная проблема, нужна какая-то многослойная документация. Потому что кому-то да, нужно все буквально и "как для чайников" объяснять, потому что он и есть чайник. И часто для них (по популярным проектам) есть миллион чайницкой документации.
Но когда человек перерос этот уровень, и уже делает что-то изращенное, через задницу, какое-то очень нетиповое решение (которое наверняка кто-то тоже делал и описал, но делали 100 человек, а не 100 000 человек) - очень сложно нагуглить статью-гайд-туториал, потому что они теряются в огромном множестве залайканных и залинкованых статей для чайников.
В идеале бы какой-то режим в бразуере, мол "сейчас я чайник в проекте X" и ищи мне ответы на мой чайницкий вопрос. Остальное даже не показывать. А потом поменял, и ты уже сам гуру, и все чайницкие страницы не видишь, зато видишь страницы с более глубоким рассмотрением темы.
мне нравится вот этот проект как пример многослойной документации. Но писать такое, конечно, упухнуть можно.
туториалов на medium.com от индусов которые вчера сами прошли туториал по какой-то теме, а сегодня написали его своими словами
Ребята просто набивают публикации для рейтинга. В некоторых странах это помогает потом получить визу с правом на работу. Обычно рерайтят базовые вещи, либо делают компиляции произвольно надерганных абзацев из популярных статей. 5 минут работы и на выходе очередной шедевр в духе "7 функций, о которых вы не подозревали". Через месяц в портфолио десятки публикаций.
Дарёному коню в зубы не смотрят. Опенсурс-разрабы даже "спасибо" за свой труд не получают. Ну и в лицензиях тоже прописано, мол, никаких гарантий и ответственности
Конечно, я абсолютно согласен, что опенсурс-разработчики никому ничем не обязаны, но хотел бы отметить то, что все-таки некоторые из них могут получать оплату в виде небольших пожертвований. Кроме того, на мой взгляд, и сами создатели проекта могут быть заинтересованы в том, чтобы их детище пользовалось спросом и было популярным, а для этого и нужно писать документацию, улучшать кодовую базу, развивать сообщество вокруг своей разработки. У разработчиков тут нет никаких обязательств, только глубоко искреннее и доброе желание помочь другим, поэтому в шагах, позволяющих это сделать быстрее и эффективнее, я не вижу серьёзных минусов.
Я видел одного чела, который был опенсурс-прогером и имел Patreon. Но платили ему там за вещи, которые уже выходят за рамки именно открытого кода
Ещё некоторые взимают плату за облачные версии своих опенсурсных СУБД (CockroachDB, MongoDB). Но не все проекты в сущности подходят под такое. Если ваш проект - это библиотека, которая тем или иным способом прилинковывается, то тут вообще очень мало вариантов монетизации. Авторы core-js и faker-js по итогу пососали
Ну и на пожертвования тоже не рассчитывайте =3
Люди не хотят особо давать деньги просто так. Платить будут только за что-то. За хоть что-нибудь. А код опенсурс-проекта мало того, что открыт - его ещё можно и свободно форкнуть. Если автор начнёт хотеть за свой труд денег, то просто останется ни с чем, потому что количество лохов, которые готовы поддерживать любой сложности проект за бесплатно, любой при чём сложности, стремится к бесконечности. В академической среде вы стремитесь как можно скорее раскрыть знание, но в бизнесе вы стремитесь закрыть его и извлечь прибыль
Используя в своём коммерческом коде опенсурс-проекты, вы пользуетесь чужой добротой и простодушием и ничего не отдаёте взамен, но при этом берёте на себя все риски и иногда даже ответственность по допиливанию-перепиливанию под себя. В этой схеме всё абсолютно справедливо. А если вы видите, что в проекте есть документация и всё такое, то тут я бы даже напрягся и задумался, с чего такая щедрость
все-таки некоторые из них могут получать оплату в виде небольших пожертвований.
Есть опыт - 1000 р. в месяц набегает целых ))) у OpenSSL недавно был скандал, что над этой либой, на которой держится по факту весь SSL работает 3 человека не на ставке...
сами создатели проекта могут быть заинтересованы в том, чтобы их детище пользовалось спросом и было популярным,
Очень хороший вопрос "зачем?", который должен себе задать каждый разработчик опенсорса и действовать в соответствии с ним.
И часто этот ответ не сводится к тому, "я делаю проект, чтобы Вася из Челябинска мог не читать документацию, нажать одну кнопку и у него всё заработало". Такая мотивация крайне редка.
Добавлю, что в релизах вообще большинство любят выкладывать zip-архив исходника и все. Зачем мне исходники, очевидно, что я иду в релизы, чтобы скачать нужный бинарь под свою платформу, а не собирать его?
Zip-архив исходников там появляется автоматически, его не выкладывают.
Я вот хочу попробовать стартануть проект на qt (iOS/android/desktop) и объектные файлы клиента выложить в репозиторий, таким образом не раскрывая исходники и не нарушая LGPL под iOS. Честно, пока просто жаба душит отдавать 500$ в год за хобби.
Инстинктивно хотел порекомендовать gtk toolkit, но потом вспомнил что он в основном только для линуха...
Я кроме кутэ и флаттера не вижу достойных альтернатив. Использовать (и учить) хтмл вёрстку ради десктопных и мобильных приложений считаю ненужным оверхедом.
Флаттер я почти не знаю, с кутэ уже лет 12. Во флаттере так и не нашел тривиальной интеграции с с++ кодом.
Lazarus в помощь. Вот без шуток: нужно было быстро сделать утилитку для мониторинга CAN-шины, выбор стоял -- qt или лазарус. Выбрал лазарус и не пожалел: по времени ушло примерно столько же, сколько ушло бы на qt при том, что с паскалем лет 10 не сталкивался. И с либами на C достаточно легко интегрировать, и по производительности не потерял, и возможности отстрелить себе ноги поменьше. Разработка под мобилки (андроид, про яблоки не в курсе) тоже, кстати, есть, но с небольшими танцами с бубном. Ну и полностью бесплатно.
Не, для современных мобилок точно мимо. Анимации интерфейса на gpu не умеет, как я понял.
Посмотрите Kotlin Compose Multiplatform
Дока https://www.jetbrains.com/lp/compose-multiplatform/
Генератор проектов https://kmp.jetbrains.com/
Комьюнити https://t.me/kotlin_lang/293612 (внутри группы есть отдельный раздел про Compose)
несмотрия на то что между gtk и qt я всегда встаю на сторону qt я бы таки поспорил с утверждением
он в основном только для линуха
несомненно gtk чаще всего применяется именно в linux, но в целом ничто не мешает собрать под винду (такое я встречал) и macos (не встречал, но слышал что и такое есть). не уверен насчёт ведроида и ios, но уверен что возможность есть.
хотя qt в этом плане конечно на голову выше, там и embedded можно.. а недавно появившийся kirigami вообще аннигилирует необходимость клепать разницу между десктопом и мобилкой.
Какие-то уж слишком банальные и очевидные рекомендации. На уровне: если вы хотите яблок, сходите за ними в магазин. Не забудьте взять с собой деньги и надеть штаны. Но на самом деле, за развитием и поддержанием своего открытого проекта лежит поистине титаническая работа, и те, кто действительно, в принципе, способны ее осилить, в банальных советах вряд-ли нуждаются.
Но напомнить лишний раз про документацию не повредит.
Спасибо за ваше замечание. Советы действительно могут показаться простыми, но в реальности у многих опенсорс разработок существует ряд проблем, связанных с ними. Вот например результаты исследования по используемым лицензиям в открытых проектах: https://blog.opensource.org/the-most-popular-licenses-for-each-language-2023/ - как видно из результатов, огромная часть разработок её и вовсе не имеет. Это очень большая проблема, а ведь разработчики данных решений может и не задумывались ни разу о том, почему она важна. Про повально плохое качество документации в комментариях уже многие отметили. По остальным пунктам то же самое, и я уверен что стоит об этом рассказывать больше и чаще, тогда и многие проекты, которые нас окружают, будут становиться лучше.
я кстати начинаю думать, что "без лицензии" - не такая уж плохая лицензия. По сути эта "лицензия" гласит - кодом могут пользоваться только олдскульные хакеры, сидящие на ломаной винде и игнорирующие все эти авторские права и лицензии в принципе. Если вы хотите чтоб таких стало больше - выкладывайте код под nolicense. Хотя gpl в этом случае слегка предпочтительнее, ведь добавляет к потенциальной аудитории фанатов линуса и столлмана, но допускаю что есть те кому они не нравятся.
Большая часть этих проектов и не слишком настроена на успех и вообще чья-то школьная лаба или самодельный велосипед из говна и палок или хобби проект, написанный за неделю и заброшенный. Да и пофиг, что там нет лицензии, документации.
С одной стороны - да, с другой - а что небанального и обобщенного можно вообще посоветовать?
Советы неплохие, но начинаются с середины, и еще сильно до того, как идти выбирать лицензию и т.д. по тексту, нужно для себя прояснить очень хорошо примерно следующее:
- какую именно проблему решает проект, является ли эта проблема реальной, нужно ли решение лично вам как автору, и кому еще это решение может пригодиться
- какие имеются альтернативы и в чем их фатальные недостатки, из за которых именно вам нужно решать проблему заново, и не будет ли лучше присоединиться к разработке уже существующего проекта, а не садиться за написание нового
- сколько у вас ресурсов и сможете ли вы тратить главный невосполнимый ресурс (время вашей жизни) не только на fun-части проекта (написание кода, решение проблемы, прием благодарностей и донатов), но и на slog-части (настройка и отладка сборочной системы, тестирование, создание и поддержка CI/CD-пайплайна, общение с пользователями, разгребание сообщений об ошибках, фич- и пулл-реквестов и т.п.).
- ожидаете ли вы роста пользовательской базы, и если да, то готовы ли к тому, что проект станет отнимать значительно больше ресурсов, чем в начале?
- готовы ли вы к конфликтам, форкам, драме, оскорблениям, необоснованным требованиям по немедленной доставке фич, немедленному исправлению багов, немедленной реакции на инциденты, потенциальным проблемам с патентами, адвокатами, письмами cease and desist, DMCA-тейкдаунами, GDPR-совместимостью, бану вашей юрисдикции гитхабом, неадекватам всех сортов и мастей, и прочим прелестям взаимодействия с большой группой бездельников в интернете?
Если ко всему готовы и все для себя решили - могу только порадоваться за вас, добро пожаловать, коллега. Постараюсь воспользоваться результатами вашего альтруизма и вашим весомым вкладом в будущее человеческой цивилизации. Искреннее больше спасибо.
Если не готовы и не решили - тоже спасибо, меньше разочарованных авторов и мейнтейнеров. Попробуйте себя в чем-нибудь другом.
- готовы ли вы к конфликтам, форкам, драме, оскорблениям, необоснованным требованиям по немедленной доставке фич, немедленному исправлению багов, немедленной реакции на инциденты, потенциальным проблемам с патентами, адвокатами, письмами cease and desist, DMCA-тейкдаунами, GDPR-совместимостью, бану вашей юрисдикции гитхабом, неадекватами всех сортов и мастей, и прочим прелестям взаимодействия с большой группой бездельников в интернете?
Кстати, да, в статью нужно добавить предупреждение, что среди пользователей статистически предопределённо обязательно найдутся неадекваты, которые будут предъявлять совершенно необоснованные претензии и портить атмосферу в сообществе.
Это нужно иметь в виду и быть морально готовым к этому (а ещё лучше выработать соответствующую политику и административные меры). И это одна из причин по которой закрываются многие ОС проекты.
Очень верное замечание. Очень часто бывает,что ищешь пакет или библиотеку под определенную задачу, а находишь сразу несколько, но все сырые, устаревшие и брошенные. Если бы авторы этих библиотек не делали свои библиотеки, а потратили это время на то, чтобы добавить пару коммитов в уже существующие, всем было бы только лучше.
Был у меня опыт с openhardware, понадобился closed loop контролер шаговых двигателей, который крепится непосредственно на шд от nema17 и крупнее. Таких проектов много, в том числе активных. Но вот смотрю я на проект: это бы я сделал иначе, тут защиты не хватает, эта функция вообще полезная, но мне лишняя, а вот этой не хватает... Если я полезу с коммитами, то это будет уже другой проект, поскольку он противоречит целям и идеологии исходного проекта.
В вашем случае, естественно, не было смысла менять существующие библиотеки. Но опять де надо понимать, если пишешь какой-то код для своего проекта, это не значит, что его тут же нужно оформить, как общедоступную библиотеку. Сделать открытый репозиторий на гитхабе - пожалуйста. Но не нужно тянуть весь свой кастомный код в репозитории типа npm, packagist, maven и т.д.
добавить пару коммитов в уже существующие
Как вы себе это представляете? Плодить форки? Если нет, то добиться того, чтобы твои коммиты приняли в официальный репозиторий - возможно непростая, а иногда и невозможная задача.
Делаешь форк, решаешь в нём проблему, ставишь в свой проект пакет из форка. В официальном репозитории создаёшь issue и pull request. Ждёшь пока примут. Потом переустанавливаешь уже исправленную версию из официального репозитория.
У меня так уже несколько раз получалось. Именно так весь опенсорс работает вообще-то.
Так в теории должен работать опенсорс, но на практике часто получается так, что проект заброшен/коммиты могут что-то ломать и другие причины, почему твои изменения не принимаются.
Предлагаете всем перестать коммитить в чужие проекты из-за боязни, что коммит могут не принять? Что вообще за глупость? Если коммит что-то ломает, об этом напишут в issue и это будет повод доработать свой код. Если будут другие причины не принять - да пожалуйста, какие проблемы, если пакет уже установлен из форка и выполняет свои функции?
Опять же, прежде чем делать свой проект на замену заброшенного, нужно всё оценить и подумать, а не приведёт это к тому, что через довольно короткий промежуток это будет уже два заброшенных проекта?
Прежде, чем публиковать свой код в виде общедоступного пакета/модуля/библиотеки, стоит также оценить, действительно ли это кому-то нужно, а во вторую очередь оценить свои силы, потянешь ли бесконечное сопровождение проекта. Потому что во всех репозиториях вроде npm, packagist, drupal.org и прочих, большая часть проектов - это либо что-то очень редко используемое, либо что-то контекстозависимое, либо банально некачественное, либо настолько простое, что 3-5 строк своего кода полностью заменяют сторонний пакет. В этих репозиториях можно смело дропнуть от 50 до 90% проектов, и мир от этого станет только лучше.
Предлагаете всем перестать коммитить в чужие проекты из-за боязни, что коммит могут не принять? Что вообще за глупость?
Нет, я раскрываю мысль, почему нижеследующее далеко не всегда возможно:
Если бы авторы этих библиотек не делали свои библиотеки, а потратили это время на то, чтобы добавить пару коммитов в уже существующие, всем было бы только лучше.
Если будут другие причины не принять - да пожалуйста, какие проблемы, если пакет уже установлен из форка и выполняет свои функции?
Если ошибка простая а фикс очевидно верный то да. Но я часто видел "фиксы" вида "я не разобрался почему ошибка, но если закомментить эту проверку то всё работает, всем рекомендую" когда от патча который затыкает проблему до нормального фикса море работы и непонятно кто эту работу должен делать если у автора проблемы всё и так работает с закомменченной строчкой, а у автора библиотеки и других дел хватает.
По сути вы перечислили проблемы любого начинающего бизнеса )
Ага, только разница в том что бизнес всё-таки потенциально приносит прибыль, а тут надо всё это делать бесплатно
Расширьте прибыль дальше прямого получения денег:
Можно делать open source чтобы вырасти профессионально и монетизировать потом это более высокооплачиваемой работой
Можно делать open source ради гитхаб звезд и указания таких проектов в резюме, чтобы монетизировать потом это более высокооплачиваемой работой
Можно делать open source, чтобы монетизировать потом поддержку продукта
Ну и:Можно делать open source, чтобы получать внутреннее удовлетворение от того, что ты сделал что-то полезное для людей, и твоя жизнь была не зря
И тогда open source можно рассматривать стратегически как бизнес
И тогда open source можно рассматривать стратегически как бизнес
Можно, но все-таки это редкость. Когда так получается, часто получается как в другой статье "я её написал для пользователей, но как маркетолог не могу не написать кликбейт сделать так, чтобы у неё было больше прочтений"
Опенсорс как бизнес - скорее западная история (традиции оплаты команд с опенсорсом, а затем монетизация; или опенсорс как стратегия раскрутки).
Буду говорить за себя - это скорее больше фан и вижн, самореализация, нежели продуманная стратегия. Поэтому играть в поддержку, которая нужна людям, но слабо нужна лично тебе, тяжеловато.
Я неточно наверное выразился. Open source можно рассматривать как бизнес с точки зрения науки, то есть использование тактик, стратегий, маркетинга ещё чего-то. Но конечная цель его будет в отличие от бизнеса не прибыль денежная, а что-то другое. Но чтобы достичь этого чего-то другого, можно использовать вполне изученную методологию бизнеса
Спасибо за ваши дополнения, полностью согласен что заданные вами вопросы очень важны!
Конечно, существует много факторов, которые следует осознавать при начале своей деятельности в роли лидера опенсорс проекта, но я хотел бы отметить, что правильная работа с сообществом поможет закрыть многие из этих пунктов. Находя помощников и заинтересованных в развитии вашей разработки, вы уже гораздо легче сможете справиться с ростом пользовательской базы проекта. Повышая ответственность коллег, вы снимете нагрузку с себя.
Про цели проекта я также отметил в статье, но тут важно подчеркнуть, что следует обладать гибкостью, и быть готовым к тому, что цели могут измениться в любой момент, иначе будет тяжело выживать при сильной конкуренции. А вот что касается альтернатив и повторения существующего функционала... не могу сказать, что это плохо, всегда полезно, когда есть большой выбор разработок, решающих одну задачу, но по-разному. Элемент конкуренции является драйвером развития любых проектов, а монополии — это всегда плохо, даже в open-source разработке.
Да, это хорошие и полезные предостережения. Нужно еще быть готовым к переговорам, компромиссам, прокачке soft скиллов, чтобы проект развивался эффективно.
Спасибо за статью, у меня есть небольшой open source проект. И по вашей статье, у проекта проблемы. Буду устранять.
Я автор опенсорс голосового помощника Ирины: и вот что я скажу
Лицензия да - надо знать. Также лицензия влияет на ваши выборы и выборы людей, использующих ваш труд. Мой выбор - MIT, потому что так мои результаты можно использовать и в коммерческих целях, а там люди трудятся, и это ок.
Тесты и линтеры - спорно. Я скипнул, и скажу почему: опенсорс определяется НЕ тем, есть ли у вас тесты и линтеры. Он определяется тем, сможете ли вы заниматься своим проектом больше года, если он будет кому-то интересен. Если тесты вам в этом помогут - используйте их; если нет - не используйте. С линтерами - аналогично. Я лично лучше потрачу время на архитектуру, функциональность и доки, чем на это (хотя тесты я писать умею)
Насчет доков и бинарников - тут были вопросы выше. Проблема вот в чем - разработчика НЕ хватает на поддержание всего выше. Хотите улучшить - надо помогать с этим. Лично у меня, я считаю, еще достаточно неплохие доки - но это я над ними парюсь, и то, большинство не могут в них разобраться. Когнитивная прозрачность описаний - это отдельный кейс, не всегда подходящий программистам (кстати, как и хороший UX-дизайн).
Сообщество. Тут все мега-сложно, только опытом нарабатывается. Коротко - оставляйте место для плагинов, которыми люди могут расширять вашу систему. Принимайте патчи, если они не нарушают ваш вижн и мотивацию (да-да, ваша задача - поддерживать систему больше года)
Признайтесь, вам хотелось бы, чтобы вашей библиотекой пользовался весь мир?
Мне бы хотелось, чтобы из введения в статью было понятно, о чём она.
Очень интересная статья, мне понравилось!
Особенно, понравилась часть про сообщество. Это большая боль, когда не уделяют внимания взаимодействию с коллегами или делают это в токсичной/грубой форме.
Ожидал увидеть и такой совет.
Если параллельно с OSS работаете по найму, то внимательно прочитайте трудовой договор и проконсультируйтесь с работодателем. Это сильно зависит от страны, территории и договора, но возможно, что весь код, который вы пишете, даже в свободное от работы время и на собственном оборудовании, является интеллектуальной собственностью компании. Соответственно публиковать такой код под свободной лицензией вы не можете.
Можно узнать, были ли прецеденты заявления прав работодателем на код написанный в свободное время на личном компьютере?
Помню претензии Рамблера на nginx, но это оказалось смешно всем
Смешно, но интересно.
Все-таки, претензии на nginX имели какое-то обоснование, какую-то логику. "Сидел себе сто лет назад за нашим столом, на нашем компьютере в рабочее время писал продукт".
А вот если бы он назвал его nginY и честно написал - я работал в рамблере, писал там для забавы мертворожденного уродца nginX, а вот сейчас у меня продукт nginY, совершенно другой, хотя в той же сфере и использует мои скиллы, которые я получил во время работы над nginX. И это было бы уже совершенно другая ситуация. Просто чуть переклеив ярлычки можно изменить то, как люди видят ситуацию. Пришлось бы обвинителям доказывать, что "а вот этот код разбивания HTTP запроса на строчки у вас до сих пор из рамблеровских времен" и максимум предметом спора бы пару кусков кода. И использовав одинаковые имена - сразу весь проект подставляем.
Отсылаю к статье Джоэла. Но если вкратце, дело даже не в том, писали ли это в свободное время на личном компьютере, а в том, не пересекается ли это с продуктами и деятельностью компании? Если да, то вас вполне могут засудить. Обычно руководство компаний не пытается такого делать, и в суде шансы так себе, но если вы при увольнении, например, реально знатно поругаетесь с руководством, то могут попробовать.
Ну с этим я соглашусь - если пересекается, то конечно всё неочевидно уже. Это как конфликт интересов - ты должен предупредить компанию, что занимаешься аналогичным продуктом. Если она с этим ок - то значит претензии в будущем отметаются.
Обычно руководство компаний не пытается такого делать, и в суде шансы так себе, но если вы при увольнении, например, реально знатно поругаетесь с руководством, то могут попробовать.
Судится с работниками у корпорации обычно нет экономического смысла - что с них взять? Другое дело, если ваш продукт выстрелит, либо возникнут вопросы со стороны заказчиков. Здесь же мутный случай, когда работник контрибьютатет в сторонний проект от своего имени, но фактически права на созданный им код принадлежат компании.
Вы сейчас говорите - зачем быть бескорыстными, будьте жадными
Зачем быть добрыми, будьте злыми
И да, к коммунизму и альтруизму добавьте христианство. Тоже не победило.
На работе я работаю за деньги. Опен сорсом занимаюсь в свободное от работы время.
И мне неприятно, что подходите вы и начинаете мне указывать, что я - халявщик, что должен перестать заниматься своим любимым делом бесплатно и попытаться втюхать его кому-то.
Радость от программирования (а оно реально в радость, это акт творения, причем один из самых простых в реализации, потому что бороться с ограничениями физического мира для него не нужно), радость от решения проблемы (офигеть, теперь вместо 20 минут в хекс-редакторе можно сделать то же самое за 20 секунд, и оно работает или также, или лучше, потому что программа меньше ошибается), радость от благодарности пользователей и повышения репутации и создания доброго имени ("ага, знаю этого чувака, он вообще крутой") - достаточные мотиваторы для многих людей, чтобы не требовать еще и денег.
Я не согласен с тем, что эти мы "плодим халявщиков", или "отнимаем поляну у кустарей", потому что халявщики таким же способом спиратили бы платное ПО, и при этом не вернули бы разработчикам вообще ничего (кроме, может быть, общедоступного кряка, чтобы остальным халявщикам удобнее стало). В опенсорсе же пользователи - это не только обуза, но и благо, потому что они предоставляют бесплатное тестирование, бесплатный фидбэк, а некоторые даже код сами правят и фичи сами реализовывают, становясь полноценными участниками проекта.
Короче, хотите денег - занимайтесь их зарабатыванием. Мне за опенсорс деньги не нужны, я им решаю для себя совсем другие задачи и массирую им совсем другую часть системы поощрения внутри головы. За деньги я работаю на корпорацию, которая намного лучше меня самого умеет монетизировать мой труд, а мне оставляет ту часть работы, от которой я получаю какое-то удовольствие (потому что это тоже акт творения, и тоже помогает пользователям), а всю остальную работу полностью берет на себя. Сделка вполне честная, на мой взгляд, а то, что она вредит "кустарям" - это так работает капитализм, разделение труда, специализация, найм профессионалов и так далее. Кустарям же от себя посоветую не на опенсорс злиться, а объединяться в собственные корпорации и конкурировать уже с другими такими же, на своей поляне. Там и денег сильно больше заработаете, если работать умеете, и опенсорс будет с вами на одной стороне баррикад, а не на разных.
Если лицензировать под AGPL, то корпорациям будет нелегко его использовать. А если это, к тому же, не продукт уровня ядра линукса а маленькая библиотека, то они его не будут использовать почти наверняка. При этом ты по-прежнему можешь наслаждаться своим альтруизмом и тем как приносишь пользу людям своим проектом (более того, каждый успешный проект под gpl приближает победу некой вариации коммунизма).
Однако у условных "корпораций" есть эффективное оружие и против закрытых проектов и против gpl - гитхаб (в меньшей степени и другие сети). Выложив туда проект под лицензией типа mit программисты получают звездочки, подписчиков, обратную связь, которые мотивируют их продолжать работу. Выложив под gpl получают меньше обратной связи (исключаются почти все кто хотел бы зарабатывать на твоем проекте), а не выложив не получают ничего. В таких условиях у закрытых продуктов очень мало шансов.
Just for fun, конечно.
Я когда свой проект стартовал в 2013 году, был на последнем курсе магистратуры, и деньги мне тогда были не нужны, нужны были прикладные знания и навыки в области Software Engineering и Software Development, которые я и пошел получать и тренировать наилучшим, на мой тогдашний взгляд, способом. При этом и процесс, и результат этого труда были нужны именно мне (я тогда занимался модификацией UEFI-совместимых прошивок в качестве хобби), а альтернатив хороших, кросс-платформенных, с открытым кодом и графическим интерфейсом тогда не было.
В итоге получилось и свой C и C++/Qt улучшить заметно, и проблему достаточно эффективно решить, и научиться не только программированию, но и сопровождению, и заиметь определенную репутацию в своих узких кругах, благодаря которой получилось устроиться и на первую серьезную работу (разработчиком прошивок), а затем и в мегакорпорацию (специалистом по безопасности эти самых).
Если бы я заранее рассчитывал на монетизацию этого проекта, то не стал бы за него садиться, потому что у среднего пользователя нет денег на такую ерунду, а имеющиеся альтернативы (PhoenixTool, например) уже тогда были и бесплатными, и работоспособными, а из недостатков имели только закрытый код и привязанность к .Net 3 (т.е. к Windows).
Более того, товарно-денежные отношения для подавляющего большинства людей подразумевают (хотя бы частичную) передачу контроля на проектными решениями и приоритетами, т.е. задачей разработчика становится "делать пользователю зашибись". У меня такой задачи нет, и я делаю зашибись в первую очередь себе самому, а пользователям хотя и очень рад (они, например, тестируют твой софт на конфигурациях, которые ты сам у себя в подвале гарантированно собирать не станешь), но ничего не должен. И донаты не беру по этой же примерно причине.
Корпорации, кстати, это тоже хорошие пользователи, и то, что они каким-то образом делают на моем коде деньги - да на здоровье, я бы эти деньги все равно не сделал, потому что не желаю смешивать работу за деньги с работой для души. Уважение коллег заработал - отлично, пользователи сказали "спасибо" - замечательно, попал в десятку лучших в мире специалистов по разбору UEFI-совместимых прошивок на составные части, потому что за 10 лет работы над их разбором насмотрелся на любые и всякие - тоже хорошо, теперь эту специализацию можно продать тем, кому она для чего-то нужна.
Абсолютно уверен, что если бы я вместо опенсорса и работы с сообществом написал бы какой-нибудь UEFITool PRO и попытался его продать, заработал бы сейчас значительно меньше, если что-либо вообще. А так и с деньгами проблем больше нет, и проект стал стандартом де-факто в своей микроскопической нише. Понятно, что это все результат скорее случайных процессов и удачных таймингов, и потому может быть проигнорировано как "ошибка выжившего", но получилось как получилось, и мне нравится этот результат.
Скорее всего, пытаются успеть занять освободившуюся нишу как можно быстрее, а затем уже думать, как монетизировать доработки под конкретных корпоративных пользователей, продавать плагины, поддержку и т.п. Если сразу делать фремиум - пользователи могут уйти к опенсорсным конкурентам, и потому занять нишу не получится.
Для начала покажите платёжную систему, которая бы работала во всём мире. Или биткоинами оплачивать?
Мне, как маленькому и глупому, не совсем понятно, КАК присвоить лицензию продукту.
Просто кинуть в корень Readme, в котором большими буквами написать, что код находится под лицензией GPL, и горе тому, кто станет утверждать обратное? А как защитить исполнение лицензии, например, в суде, если этот файл можно заменить в любой момент? И примет ли вообще российский, например, суд во внимание лицензию GPL или любую другую? Вот бы статейку на эту тему
Были статьи на хабре, например 769892. Если вкратце - всё плохо с GPL. Точнее, всё хорошо, пока все ведут себя по-джентльменски. Как только появляются ушлые люди, убирающие упоминания о лицензиях в заимствованном коде или отказывающиеся выполнять другие положения лицензии, как в упомянутом примере, то выясняется, что никаких правовых механизмов восстановить статус-кво нет.
Как только появляются ушлые люди, убирающие упоминания о лицензиях в заимствованном коде
Инструменты композиционного анализа (SCA) такие трюки неплохо определяют. У меня было на практике несколько случаев, когда ребята заимствовали фрагменты открытого кода, и нужно было решать вопросы с лицензиями. А это код обнаруживался потом в разных уголках Интернета.
Например был случай, когда притащили несколько строк со Stack Overflow. Наш SCA обнаружил этот фрагмент на GitHub в проекте под AGPL и создал инцидент. При детальном рассмотрении выяснили, что код в том проекте появился годом позже, чем пост на SO. А потом нашли ещё один проект на BitBucket, который был на десять лет старше, с тем же точно фрагментом, но уже под MIT.
А вот бы эту статью опубликовать под открытой лицензией и со всеми (применимыми к тексту) инструментами и фишками )
А авторов хороших жополняющих комментов отправлять коммитить их в статью ))
Про лицензии, думаю, надо оставитьэто здесь https://lukesmith.xyz/articles/why-i-use-the-gpl-and-not-cuck-licenses/
Хотя я лично ими пользовался, но всё-же public domain покруче всяких BSD будет. Для истинных альтруистов.
Хорошая статья. Прошу по возможности больше статей на эту тему.
Спасибо за статью, уважаемый!
Изначально воткнул MIT-лицензию для пет-проекта, не разбираясь что да как.
Что за проект, спросишь ты? (даже если и не спросишь)
Flabr - читалка для хабра ;)
Цели комментария
следую совету из статьи (см. маркетинг) и пиарюсь как могу ?
понять, по какому адресу и в каком формате выполняется запрос, чтобы добавить возможность добавить комментарии в приложение
Никогда не забывай об этом, когда делаешь open-source проект