Comments 135
Но, полагаю вы согласитесь, с точки зрения пользователя — нормально оформленный проект имеет больше шансов быть использованным чем просто запушенные «пет»-сырцы без каких либо дополнительных усилий.
Моя цель не в том, чтобы кого-то заставить или мотивировать, а в том, чтобы помочь разработчикам _желающим_ помочь потенциальным пользователям.
Ну и обсудить набор полезных практик и приемов по сабжу.
Вот например:
github.com/github/gitignore/community
И такая страница в любом репозитории есть.
Добавлю пожалуй в статью.
Но! Есть и другая сторона вопроса — я вот взялся «причесать» свой проект перед выкатыванием в паблик альфы. Работал над проектом два года, переделал несколько раз с нуля… Сейчас жалею что не выкатил полгода назад «как есть», может быть обратная связь дала бы уже свои плоды? Может быть кто-то бы помог с рутиной?.. Да и не доведу я его сам никогда до состояния «конфетки».
Статья безусловно хорошая, в том плане что как минимум дает дорожную карту того что должно быть, а уж на каком этапе все это вводить — дело каждого. Но не стоит настаивать на том что оно должно быть совсем уж обязательно…
По моему мнению, необходимый минимум такой
- Readme, чтобы было понятно, что это вообще за код. Если это библиотека, то желательно фрагмент кода, чтобы было понятно, как подключить, что вызывать
- Некоторое количество тестов (необязательно 100% покрытия), и настройка CI, чтобы все входящие пулл-реквесты сразу билдились.
Полировать исходники до блеска и документировать каждый метод не стоит, можно сделать и позже, когда пользователи и контрибуторы появится
А какое соглашение есть на гитхабе при публикации changelog'ов? Как вы их публикуете?
Сайт инициативы keepachangelog.com
Преимущество именно этого формата: использование md и продуманная согласованность с SemVer.
Большинство OS проектов придерживаются описанного там формата. Хотя есть и другие попытки стандартизации, например GNU: www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html
Или я не понял вопрос?
В примере на сайте keepachangelog.com есть каноничный пример со ссылками на diff между каждой версией на github.
В гитхаб релизах версии — это теги + UI обвязка, позволяющая вручную заполнить описание релиза.
Есть разные инструменты для генерации CHANGELOG, но предпочтительный вариант — заполнять его вручную по мере внесения изменений. Сама методика заполнения детально рассмотрена на упомянутом сайте.
Очевидно что github лидирует как хостинг OS-проектов
Я бы поставил это утверждение под вопрос, на самом деле. Потому что у самого Github в этом плане не все так прозрачно, тот же GNU в своем рейтинге этичности репозиториев выдал ему F. Вы можете сказать, на это в целом плевать и все такое, но мне бы не хотелось выяснить, что мой проект внезапно удалили из github просто потому, что так кто-то захотел.
Напротив, как раз хостить проект на своём сервере — лучший способ его потерять через пару лет, поскольку поддержка будет упираться в одного человека, работающего за бесплатно, т.е. вас. Сервер упадёт — вы этого даже не заметите. Случится что-нибудь, не дай бог, с вами, или просто переедете, сервер сломается, надоест поддерживать, кончатся деньги — проект исчезнет. У меня есть кое-какая статистика с https://repology.org: мёртвых ссылок на хостинги намного меньше чем мертвых ссылок на отдельные домены.
git распределённая система, поэтому удаление с github конечно неприятный момент, но, технически, не фатальный.
К стыду своему, я мало работал с другими СКВ, но насколько понимаю, поддерживаемая лидером GNU-рейтинга «Саванной» централизованная CVS не обладает таким преимуществом, тем самым делая его более уязвимым и критическим узлом для проектов, которые там хостятся.
Ну, "децентрализованность" — это круто, но по факту вы все равно сильно завязываетесь на github из-за CI, ведения багов и прочего. То есть, код то у вас будет, коммитить можно, но все остальное работать без него не будет.
Подождите, тут недопонимание. Savannah поддерживает Git: https://savannah.gnu.org/maintenance/UsingGit/
Другое дело, что пользоваться им непрактично, очень много чего не хватает, так что лучше уж GitLab. Заблокируют что-то — поставлю свой инстанс на своём же сервере и буду дальше раздавать. Да и в рейтинге GNU Gitlab заработал С только потому что не подровнял свой JS и по-умолчанию не создаёт файл LICENSE, что вообще минорщина.
мой проект внезапно удалили
Вы не совсем правильно понимаете смысл рейтинга. Основной смысл претензии GNU к github — использование js кода с несвободными лицензями и выполнение требований роскомнадзора.
выполнение требований роскомнадзора.
мой проект внезапно удалили
Основная проблема в этом плане — это подчинение локальному законодательству отдельной страны, которая вообще может не иметь отношения ко мне. Понятное дело, код крупных компаний github трогать не станет, но вот мой пет-проект, в котором, например, будет слово, которое так любит роскомнадзор — вполне.
Обычно просто блокируют доступ к репозиторию с ip соответствующей страны. Никто ничего не удаляет.
что мой проект внезапно удалили из github просто потому, что так кто-то захотел
Это какая-то страшилка для детей. Просто так проекты не удаляют, а если в вашему проекту могут быть законные претензии, его удалит любой хостинг, а ваш личный сервер заблокируют или его откажется обслуживать хостер.
GitHub же действительно лидер, а скорее даже безальтернативное решение.
GitHub же действительно лидер, а скорее даже безальтернативное решение.
Безальтернативное в плане? Я вот сижу на gitlab, мне нормально (разве что он иногда лежит, но так и github умеет).
Поисковые запросы из google и в gitlab ищут. Или вы из тех людей, которые ищут проекты сразу через поиск github?
Безальтернативное в плане?
В том плане, что F/OSS разработка — это прежде всего сообщество, а сообщество — на GitHub. Игнорируя GH, вы теряете значительную часть аудитории, а оставшейся части усложняете взаимодействие с проектом, потому что люди привыкли что у них всё в одном месте — свои проекты, проекты за которыми они следят и в которые контрибутят, входящие и исходящие PR и issue, одна лента новостей, одно мобильное приложение, если оно нужно, и патч отправляется одной кнопкой без изучения нового инструмента и регистрации. И это место — GitHub, просто потому что он самый большой. Любой другой хостинг, понятно, из этой схемы вылетает: кто-то ради одного проекта не будет даже регистрироваться, кто-то отправит issue и забудет про него навсегда (и вы никогда не получите ответа на запрос дополнительных сведений о проблеме). Также вы теряете кучу интеграций, которые ориентируются, естественно, прежде всего на GH.
Поисковые запросы из google и в gitlab ищут.
В большинстве моих проектов в статистике трафика в Referring sites первой строчкой идёт сам github, с отрывом от google в разы.
Или вы из тех людей, которые ищут проекты сразу через поиск github?
Последнее время всё больше да, и не вижу в этом ничего плохого. Во-первых, там почти всё находится. Во-вторых, обычно я "ищу проекты" с целью заслать патч, а их у меня после 15 лет в СПО порой появляется десятками в день, и мне банально жалко тратить больше времени на регистрацию на очередном "не как у всех" хостинге, разбирательство в очередном "привет из 90-х" self-hosted багтрекере, ожидание писем подтверждения регистрации (когда-то иного выхода не было, и с тех пор у меня остался текстовый файл с 500+ таких учёток — половина сайтов уже мертва, к слову о self-hosted — но эта эпоха, к великому счастью, ушла навсегда) и заполнение issue формы из десятка обязательных полей, чем на собственно подготовку патча, поэтому проекты не представленные на GH мне не особо и интересны. В-третьих, в ленте и рекомендациях на GH, которые строятся на основе звёзд и follower'ов, порой проскакивают интересные проекты которые google мне никогда не покажет.
В том плане, что F/OSS разработка — это прежде всего сообщество, а сообщество — на GitHub. Игнорируя GH, вы теряете значительную часть аудитории, а оставшейся части усложняете взаимодействие с проектом, потому что люди привыкли что у них всё в одном месте — свои проекты, проекты за которыми они следят и в которые контрибутят, входящие и исходящие PR и issue, одна лента новостей, одно мобильное приложение, если оно нужно, и патч отправляется одной кнопкой без изучения нового инструмента и регистрации. И это место — GitHub, просто потому что он самый большой. Любой другой хостинг, понятно, из этой схемы вылетает: кто-то ради одного проекта не будет даже регистрироваться, кто-то отправит issue и забудет про него навсегда (и вы никогда не получите ответа на запрос дополнительных сведений о проблеме). Также вы теряете кучу интеграций, которые ориентируются, естественно, прежде всего на GH.
Вот что касается Free, то после скандалов с popcorn time и роскомнадзором, довольно таки неплохая часть проектов свалила на тот же gitlab. Так сделали Inkspace, F-droid, m2crypt, например. Потому что github не для свободного кода. Зашкварится gitlab, люди еще куда-то свалят.
Касательно коммьюнити:
- Проблема решаема. Все абсолютно так же, как в случае github, потому что наличие аккаунта не решает. На github полно реп с issue, где человеку все расписали в ответ на его вопрос, а он не заходит туда месяцами. А если вам настолько не интересен проект, что даже лень создать аккаунт, ну… issue вы бы тоже не заполняли.
- Это довольно сложно сделать, так как gitlab внезапно стал одним из самых популярных self-hosted решений для тырпрайза, а за ним и интеграции подтянулись.
В основном я теряю все "бесплатные" интеграции с CI, которые легко заменяются gitlab ci.
Во-вторых, обычно я "ищу проекты" с целью заслать патч, а их у меня после 15 лет в СПО порой появляется десятками в день, и мне банально жалко тратить больше времени на регистрацию на очередном "не как у всех" хостинге, разбирательство в очередном "привет из 90-х" self-hosted багтрекере, ожидание писем подтверждения регистрации (когда-то иного выхода не было, и с тех пор у меня остался текстовый файл с 500+ таких учёток — половина сайтов уже мертва, к слову о self-hosted — но эта эпоха, к великому счастью, ушла навсегда) и заполнение issue формы из десятка обязательных полей, чем на собственно подготовку патча, поэтому проекты не представленные на GH мне не особо и интересны.
Как это работает? Вы заходите в github и ищете репозиторий с проектом? А те проекты, у которого bug tracker в другом месте, как с ними поступаете? Опять же, а перед заполнением issue вы читаете issue template или просто как-то что-то напишите и все? А если читаете, то чем это отличается от 10 полей, которые вы упомянули, так как очень часто у репозиториев свои и странные правила заполнения issue (например, очень странно все у errbot, они используют todo списки для указания типа issue).
Зашкварится gitlab, люди еще куда-то свалят.
А нигде лучше не будет. Так, GitLab прямо заявляют что с радостью удалят ваш проект: https://about.gitlab.com/dmca/. Что до "зашквара", так у вас нерепрезентативная выборка, так как про GitHub вы слышали звон, а про GitLab ещё нет. При этом GitHub придерживается прозрачности (https://github.com/github/dmca), чётко определяет политику (https://help.github.com/articles/dmca-takedown-policy/), отфутболивает невалидные претензии (https://github.com/github/dmca/blob/master/2014/2014-05-01-Pushwoosh-SDK-counternotice.md) и не удаляет форки. По мне так это выглядит куда более адекватно и надёжно чем писулька от GitLab, который даже не показывает ЧТО уже наудалял.
Истеричек же которые вместо разработки прыгают между хостингами из-за проблем других проектов, которые их никогда не коснутся (а тем более даже не разобравшись в сути проблем, и не осознавая что на другом хостинге ситуация не изменится), я просто не понимаю.
Проблема решаема. Все абсолютно так же, как в случае github
Не решаема, и не так же, просто потому что аудитория на два порядка меньше. Для большинства пользователей GitLab останется хостингом одного проекта (при этом на GitHub), ничего даже близко похожего на то что я описал не получится, пока существует GitHub.
А если вам настолько не интересен проект, что даже лень создать аккаунт
Вы невнимательно прочитали мой комментарий, если всё ещё пишете "даже лень создать аккаунт", как будто это пренебрежимо быстрое и лёгкое действие. Я повторюсь. Во-первых, оно само по себе необосновано тяжело, поскольку в общем случае это изучение нового интерфейса, заполнение формы регистрации, ожидание подтверждения и заполнение формы issue. Это минут 10 времени, за которое можно было сделать множество куда более полезных вещей плюс выпадение из потока. Во-вторых, если вы делаете это один раз, можете и не заметить, но представьте каково делать это десятки раз в день.
Как это работает? Вы заходите в github и ищете репозиторий с проектом? А те проекты, у которого bug tracker в другом месте, как с ними поступаете?
Я же написал: никак, мне жалко тратить на них время.
Опять же, а перед заполнением issue вы читаете issue template или просто как-то что-то напишите и все? А если читаете, то чем это отличается от 10 полей
Читаю. Даже не пытайтесь сравнивать issue template и монструозными формами всяких мантисов. Во-первых, template используются крайне редко, и это правильно, потому что для большинства issue не нужно ничего кроме заголовка и описания. Во-вторых, если template есть, в них будет только то что нужно конкретному проекту. Скажем, если это 3D движок, то будет поле с моделью GPU (что не все гордые самостоятельные трекеры позволяют), и по-прежнему ничего лишнего. В-третьих, issue в любом случае можно заполнить как хочется, и я не при каких обстоятельствах не буду, исправляя опечатку в README, заполнять полтора десятка полей, создавать и прикреплять патч, ещё и уникальное имя ему выбирая.
А нигде лучше не будет. Так, GitLab прямо заявляют что с радостью удалят ваш проект: https://about.gitlab.com/dmca/. Что до "зашквара", так у вас нерепрезентативная выборка, так как про GitHub вы слышали звон, а про GitLab ещё нет. При этом GitHub придерживается прозрачности (https://github.com/github/dmca), чётко определяет политику (https://help.github.com/articles/dmca-takedown-policy/), отфутболивает невалидные претензии (https://github.com/github/dmca/blob/master/2014/2014-05-01-Pushwoosh-SDK-counternotice.md) и не удаляет форки. По мне так это выглядит куда более адекватно и надёжно чем писулька от GitLab, который даже не показывает ЧТО уже наудалял.
Но ведь я говорил не про dmca, а про https://github.com/github/gov-takedowns.
Не решаема, и не так же, просто потому что аудитория на два порядка меньше. Для большинства пользователей GitLab останется хостингом одного проекта (при этом на GitHub), ничего даже близко похожего на то что я описал не получится, пока существует GitHub.
Не на два порядка. Максимум в 10 раз, но скорее всего, и то меньше. Но правды мы не узнаем, так как про количество пользователей никто не говорит. И как указали ниже, еще есть как минимум bitbucket и gitlab, которые в целом довольно популярны. А еще так же указали на то, что для крупных проектов скорее исключение, чем правило хостится на github.
Вы невнимательно прочитали мой комментарий, если всё ещё пишете "даже лень создать аккаунт", как будто это пренебрежимо быстрое и лёгкое действие. Я повторюсь. Во-первых, оно само по себе необосновано тяжело, поскольку в общем случае это изучение нового интерфейса, заполнение формы регистрации, ожидание подтверждения и заполнение формы issue. Это минут 10 времени, за которое можно было сделать множество куда более полезных вещей плюс выпадение из потока. Во-вторых, если вы делаете это один раз, можете и не заметить, но представьте каково делать это десятки раз в день.
Ну так мы же говорим про регистрацию на крупном хостинге проектов. В наше время стоит завести аккаунты хотя бы на github, gitlab и bitbucket.
Я же написал: никак, мне жалко тратить на них время.
Это работает как-то так: "есть очень большая библиотека на моем языка, которая решает мою проблему. Сам я буду ее писать недели три. Ой нет, она хоститься не на github, пойду пилить свою версию"?
Во-первых, template используются крайне редко, и это правильно, потому что для большинства issue не нужно ничего кроме заголовка и описания.
И в github template используются для того, что бы описание было структурировано.
В-третьих, issue в любом случае можно заполнить как хочется, и я не при каких обстоятельствах не буду, исправляя опечатку в README, заполнять полтора десятка полей, создавать и прикреплять патч, ещё и уникальное имя ему выбирая.
Мы говорим про gitlab/bitbucket или про интерфейсы из девяностых? Опять же, issue для исправления опечатки не нужен, достаточно только pull/merge request. А в любых других случаях очень хорошим тоном является указывать ту самую кучу полей, как версия программы, ваша ОС, какие-то шаги, что бы получить такой результат и так далее просто в содержимом issue.
Конечно, вы можете заполнять это все так, как вы хотите, но тогда ваш issue даже не будут читать, а просто закроют с комментом "не по форме" в почти любом крупном проекте.
Но ведь я говорил не про dmca, а про https://github.com/github/gov-takedowns.
Не вижу разницы.
Не на два порядка. Максимум в 10 раз, но скорее всего, и то меньше
Вообще-то, в 250 раз: https://en.wikipedia.org/wiki/Comparison_of_source_code_hosting_facilities#Popularity (и это при том что данные по gitlab там свежее почти на год).
А еще так же указали на то, что для крупных проектов скорее исключение, чем правило хостится на github.
Крупные проекты ну никак не релевантны "советам как оформлять open source проект". Они скорее антипример: во-первых, они вынуждены использовать более сложную инфраструктуру просто из-за объёма фидбэка от пользователей. Во-вторых, они неповоротливы и отягощены тоннами легаси, из-за чего могут до сих пор использовать и CVS, и свои кривые системы сборки, и устаревший стандарт C++, и что угодно. В-третьих, у них свои заморочки с инвесторами. И да, от этого страдают и разработчики, и контрибуторы, и пользователи, и аудиторию они теряют — контрибутить в таких монстров хочет и может далеко не всякий. И тем не менее, зеркало на GH среди них — скорее правило, чем исключение. И почти все (их тех у кого апстрим в git) таки принимают PR.
Ну так мы же говорим про регистрацию на крупном хостинге проектов. В наше время стоит завести аккаунты хотя бы на github, gitlab и bitbucket.
Ещё раз: gitlab и bitbucket это НЕ крупные хостинги. Человек, работающий с сотнями репозиториев на GH имеет шанс встретиться разве что с единицами проектов на GL/BB, так что на практике они ничем не отличаются от self-hosted решений — тот же оверхед, те же неудобства, та же пустота.
Мы говорим про gitlab/bitbucket или про интерфейсы из девяностых?
Мы говорим про не-GitHub в общем, а это суть одни и те же трущёбы, не очень подходящие для разработки F/OSS. Да, в GitLab нет кошмарных форм мантиса, зато есть регистрация, непривычный интерфейс и нет аудитории — не далеко ушёл. А self-hosted "крупные проекты" которые вы притянули — это как раз ещё и интерфейсы из девяностых во все поля: мантисы, багзиллы, траки и жиры.
И в github template используются для того, что бы описание было структурировано.
Нет, они нужны чтобы описание было полным и чтобы люди создающие первый в своей жизни PR не писали "у меня всё сломалось".
Конечно, вы можете заполнять это все так, как вы хотите, но тогда ваш issue даже не будут читать, а просто закроют с комментом "не по форме" в почти любом крупном проекте.
Спасибо за мнение, но я достаточно контрибутил и принимал патчи в крупные проекты чтобы утверждать что это неправда. Бюрократия в равной степени мешает как авторам проекта, так и контрибуторам, и от неё избавляются при малейшей возможности. Закрыть с комментом "не по форме" — это дикость и самодурство, я такого не встречал ни разу. Самые грамотные issue всегда оформлены без шаблонов, точно так чтобы максимально точно и ёмко описать конкретную проблему.
Вообще-то, в 250 раз: https://en.wikipedia.org/wiki/Comparison_of_source_code_hosting_facilities#Popularity (и это при том что данные по gitlab там свежее почти на год).
Вот теперь я и убедился в проблемах википедии. Мало того, что данные у github на самом деле взяты за самые что ни есть актуальные (там и сейчас так написано), мало того, что они обе указаны в расплывчатой формулировке more… так они еще и взяли число с gitlab, которые не менялось с 15(!) года (пруф). Если вы считаете, что gitlab не вырос с того времени в размерах, учитывая, что как раз на это время пришли все основные его плюшки (в виде удобного CI, переделки интерфейса и прочего) и миграция с github, в то время как github вырос в два раза (с more 15, до more 25), то вы, скорее всего, очень ошибаетесь.
Не вижу разницы.
Если уж вы за free source, то вряд ли будете нарушать международное патентное законодательство. А локальные запреты стран, которые делают непонятно что — вполне можете. Вот запретят в одной северной страные технологию vpn и github быстренько заблокирует доступ ко всем ее реализациям с этой страны. Очень похоже на free source.
Нет, они нужны чтобы описание было полным и чтобы люди создающие первый в своей жизни PR не писали "у меня всё сломалось".
Спасибо за мнение, но я достаточно контрибутил и принимал патчи в крупные проекты чтобы утверждать что это неправда. Бюрократия в равной степени мешает как авторам проекта, так и контрибуторам, и от неё избавляются при малейшей возможности.
Я очень стесняюсь спросить, а в какие крупные проекты вы так контрьбьютили и что вы понимаете под "крупным проектом"? Как-то мой опыт крупных проектов слабо коррелирует с вашим, потому что я видел только два варианта. Или отклонять все не по форме (и более того не по теме), как это делает, например, ansible (хотя это и ему не помогает) или тонуть в issue, когда ты просто перестаешь в них заходить. Потому что значительное количество issue пустые и не информативные.
Да, в GitLab нет кошмарных форм мантиса, зато есть регистрация, непривычный интерфейс и нет аудитории — не далеко ушёл.
Создание аккаунта — это не проблема. Мне сложно представить, зачем вы в состоянии потока серфите по github, но я обычно захожу все-таки в процессе поиска. И с современными технологиями, с браузерами, которые запоминают пароли, с менеджерами паролей, если не доверяете браузерам, говорить про то, что "не хочу создавать аккаунт — это сложно", это прямо подчеркивать, что вам проект не интересен.
Это, конечно, не очень релеватный пример, но почти все мои знакомые перешли с github на gitlab, потому что он удобный, там есть приватные репозитории, а еще и CI.
Если вы считаете, что gitlab не вырос с того времени в размерах, учитывая, что как раз на это время пришли все основные его плюшки
вы, скорее всего, очень ошибаетесь
Считаю, поскольку, как я уже неоднократно говорил, на VCS хостинг идут к аудитории, а её на GL не было, нет и пока не предвидится. И проектов на GL я как не видел, так и не вижу. Что до плюшек, то никаких киллер фич там не появилось — он всего лишь немного причесался и приблизился по возможностям к лидерам рынка.
А актуальную разницу, если угодно, можно посчитать самому: посмотрим, например, на число репозиториев, в которые коммитили за последний месяц там и там. Берём список реп на GL, с сортировкой по last updated и промотаем все репозитории до "updated 1 month ago". Я получил 1460 страницу, это 1460 * 20 = 29k репозиториев. То же самое на GH делается (к слову о плюшках) простым поиском. 2.25M реп. Разница в 77 раз, два порядка.
К слову, если корректно сравнить данные из википедии, а именно отчёт GL на начало 2016 года и press страница GH на то же время, получим точную разницу в общем количестве реп, и это 546k vs. 31M = 56 раз (2 года назад). Выводы делайте сами.
Вот запретят в одной северной страные технологию vpn и github быстренько заблокирует доступ ко всем ее реализациям с этой страны
Это правда, и известно что всего лишь заблокирует, и при этом даже не тронет форки. Известно также что GitLab никуда не денется, иначе одна северная страна заблокирует его целиком. А что он сделает — заблокирует, удалит, или удалит сразу все копии — неизвестно. Зато известно что аналогов *-takedowns он не ведёт, так что что именно и с чем он сделал вы даже не узнаете. Итого, он в этом объективно строго хуже GH.
Я очень стесняюсь спросить, а в какие крупные проекты вы так контрьбьютили и что вы понимаете под "крупным проектом"?
А вы не стесняйтесь, мои аккаунты на github и openhub всем доступны.
Или отклонять все не по форме (и более того не по теме), как это делает, например, ansible (хотя это и ему не помогает)
Неправда. Специально для вас провёл эксперимент: https://github.com/ansible/ansible/pull/32473 — наступил себе на горло, поскольку у ansible как раз абсолютно адекватный шаблон, которым хочется пользоваться, и понятно зачем он нужен (робот по нему сортирует PR, которых тысячи), и сделал "не по форме". Приняли без вопросов менее чем за сутки, всего лишь с просьбой пользоваться шаблоном.
Создание аккаунта — это не проблема
Я доходчиво объяснил что (и почему именно) это проблема.
Мне сложно представить, зачем вы в состоянии потока серфите по github
Очень просто — обновляю пачку FreeBSD портов которые поддерживаю, получаю пачку патчей (где-то что-то сломали), засылаю в апстримы. Обновился clang во FreeBSD — ещё пачка, перешли на lld — пачка, добавили поддержку новой архитектуры — пачка, ужесточили требования к сборке — пачка. Это — будни, и я даже не говорю о таких квестах как прошерстить все накопившиеся в дереве патчи (28k штук) и заслать в апстрим всё до чего руки дойдут, или взять какой-нибудь распространённый антипаттерн и исправить его вообще везде.
это прямо подчеркивать, что вам проект не интересен
Странно как-то получается, на GH интересны, а на GL нет, по вашему так по какой угодно причине только не объективной. Я же подчёркиваю что не предоставление возможности контрибутить через GH — неуважение к контрибуторам.
А актуальную разницу, если угодно, можно посчитать самому: посмотрим, например, на число репозиториев, в которые коммитили за последний месяц там и там. Берём список реп на GL, с сортировкой по last updated и промотаем все репозитории до "updated 1 month ago". Я получил 1460 страницу, это 1460 * 20 = 29k репозиториев. То же самое на GH делается (к слову о плюшках) простым поиском. 2.25M реп. Разница в 77 раз, два порядка.
Одна только проблема — вы не учли приватные репы. Учитывая, что gitlab по умолчанию предлагает делать приватные репозитории, то есть вся фигня, которую люди выкладывают на github чисто, что бы она где-то была, остается скрытой. Магическим условием "stars:>1" я превращаю ваши 2.25м реп в… 200к. А если вкрутить до двух звездочек (ведь одну можно и себе самому поставить), получится 163к. Уже не так много.
Ну и у меня получилось почему-то 1660 страниц, ну это, думаю, не важно.
Поиск у него хромает, конечно, но gitlab в первую очередь все-таки пытается быть удобным хостингом проектом.
Неправда. Специально для вас провёл эксперимент: https://github.com/ansible/ansible/pull/32473 — наступил себе на горло, поскольку у ansible как раз абсолютно адекватный шаблон, которым хочется пользоваться, и понятно зачем он нужен (робот по нему сортирует PR, которых тысячи), и сделал "не по форме". Приняли без вопросов менее чем за сутки, всего лишь с просьбой пользоваться шаблоном.
Мы же говорили про issue, нет?
Я доходчиво объяснил что (и почему именно) это проблема.
Приведя в пример ситуацию из 90-х годов. Сейчас большинство вещей, что вы описали не нужно и не работает. Интерфейсы изучать не нужно, все запихнули в "настроки", ввести нужно только набор стандартных полей, например.
Известно также что GitLab никуда не денется, иначе одна северная страна заблокирует его целиком.
Для него это как бы… не проблема. У него другая политика монетизации, а значит, его блокировка в одной северной стране ему в целом может быть даже по барабану. Почему github не может себе такого позволить то понятно.
Я же подчёркиваю что не предоставление возможности контрибутить через GH — неуважение к контрибуторам.
Мне кажется, проявление позиции "сделайте для меня максимально удобно" — это неуважение к проекту, собственно. Ради условных контрибьюторов, которые не понятно, сделают что-то полезное или нет, но которые не могут освоить новый интерфейс, ведь это так сложно, нужно или поддерживать одновременно два репозитория с разным набором тулзов.
Что до плюшек, то никаких киллер фич там не появилось
Самая главная киллер-фича — халявные приватные репы и ci.
Потом идет более удобный менеджер issue, халявный docker registery и подгруппы.
Странно как-то получается, на GH интересны, а на GL нет, по вашему так по какой угодно причине только не объективной.
Для меня так есть как минимум два интересных проекта — F-Driod и Inkscape. Но если у вас в интересах freebsd и работа с нее, то в целом ничего удивительно.
Одна только проблема — вы не учли приватные репы
Приватные репы к опенсорсу не имеют никакого отношения.
Мы же говорили про issue, нет?
Нет. PR и issue отличаются только наличием патча.
Приведя в пример ситуацию из 90-х годов. Сейчас большинство вещей, что вы описали не нужно и не работает. Интерфейсы изучать не нужно, все запихнули в "настроки", ввести нужно только набор стандартных полей, например.
Вы невнимательно или избирательно читаете. Не собираюсь повторяться.
Для него это как бы… не проблема
Это проблема для его пользователей в этой стране. И что вы сейчас пытаетесь доказать я не понимаю — начиналось с того что "GH плохой, блокирует для России по требованию РКН", а закончилось тем что блокирование всего хостинга — не проблема.
Мне кажется, проявление позиции "сделайте для меня максимально удобно"
Не "для меня", а "для всех". Напомнить про цифры?
Самая главная киллер-фича — халявные приватные репы и ci
Ничего из этого не является киллер фичей.
Но если у вас в интересах freebsd и работа с нее, то в целом ничего удивительно.
Вроде количество интересных мне проектов хорошо видно и оно сильно больше одного, или у вас опять избирательное зрение?
Приватные репы к опенсорсу не имеют никакого отношения.
Чисто внутряковая шара текстовой информации с версионностью. Просто в gitlab такие вещи скрыть можно, а в github они лежат открытыми.
Нет. PR и issue отличаются только наличием патча.
Звучит так, как "каша и суп отличаются только ингредиентами". В наличии патча то и весь смысл. Если вы просто оставили невнятный баг репорт, причем еще и не по шаблону — его закрыть можно и нужно, потому что он будет только тратить ваше время, если у вас крупный проект. А если это быстрый фикс документации, то просто смотрите одну строчку изменений и все ок.
Это проблема для его пользователей в этой стране.
А что является большей проблемой, подчинение неадекватным законам или условная "блокировка", которую можно обойти, если нужно?
Не "для меня", а "для всех". Напомнить про цифры?
Для "всех" это для кого? Вот у меня целых два аккуанта на github, и если кто-то заведет нужный мне проект на gitlab, то я спокойно напишу ему там bug report. Мои коллеги по работе, когда я завел на gitlab своего open source бота тоже смогли зарегистрировать там аккаунты и написать свои предложения или баги. Тем, кому было лень я выдал email адрес, который любезно предоставляет gitlab. Это еще два человека с аккаунтами в github.
Я указал, что имел ввиду не персонально вас, а похожих на вас людей, которые считают сложным завести аккаунт на еще одной платформе. Вы же тоже не можете говорить за всех людей, которые пользуются github. Вот мне интерфейс gitlab нравится больше, но если нужно, я спокойно захожу на github или bitbacket что бы оставить issue.
Ничего из этого не является киллер фичей.
Для меня приватные репы — очень большая киллер фича, из-за которой я переехал на gitlab и теперь могу не светить свои днищепроекты совсем даже без README и рабочего состояния.
Крупные проекты ну никак не релевантны "советам как оформлять open source проект". Они скорее антипример: во-первых, они вынуждены использовать более сложную инфраструктуру просто из-за объёма фидбэка от пользователей. Во-вторых, они неповоротливы и отягощены тоннами легаси, из-за чего могут до сих пор использовать и CVS, и свои кривые системы сборки, и устаревший стандарт C++, и что угодно. В-третьих, у них свои заморочки с инвесторами. И да, от этого страдают и разработчики, и контрибуторы, и пользователи, и аудиторию они теряют — контрибутить в таких монстров хочет и может далеко не всякий. И тем не менее, зеркало на GH среди них — скорее правило, чем исключение. И почти все (их тех у кого апстрим в git) таки принимают PR.
Не совсем.
Да, есть кейсы, как с ядром линуха, но много труъ опенсорса не хостится на гитхабе вовсе не из-за объёма фидбэка от пользователей, тонн легаси и прочего. Ну в самом деле, какая очередь фидбэка в v8 или Ardour?
Из того, что я вижу основные причины в issue. Issue в github это удобно, пока busfactor==1 и не надо передавать мейнтейнерство. Вторая причина — если проект является частью большой инициативы (chromium, kde, gnu, apache и проч), тогда зеркало обычно есть, но контрибутинг через свою площадку.
И обратите внимание, что каждый отдельный реп обычно не гигантский, примеры: mousepad или gparted — небольшие, а коммитов немного (да и что там докоммичивать?). А в гигантский corefx контрибутят изо всех сил (при том, что там надо соглашение с MS подписать и требования по качеству нормальные). К слову в структуре corefx очень легко разобраться и найти нужное.
Я это всё к тому, что мир FOSS не заканчивается на github trends. Рекомендация для начала своего проекта попробовать github — отличная рекомендация (хотя, как я писал ниже gitlab мне и больше по душе). А безаппеляционное "только github, остальные маргиналы и проприерасты" — уже не отличная, потому что "остальные" себя вполне обосновано могут и мейнстримом считать.
В плане "разобраться с интерфейсом" github, gitlab и bitbucket различаются подчас меньше, чем соседние похожие проекты в jira или youtrack в одной организации.
А скоро github планирует добавить механизм рекомендаций на основе ваших «звездочек».
Так вроде уже?
Файл должен называться LICENSE, без расширения.
Это почему без расширения? Markdown файлы приятней читать.
Не понял, почему минусы? Пункты, заголовки, ссылки и другие вещи приятней читать в отрендеренном виде, особенно если это кастомная лицензия, где такого много.
Ну и почему LICENSE без расширения, а все остальные с расширением, т.е. CONTRIBUTING.md, CONTRIBUTORS.md, ISSUE_TEMPLATE.md, PULL_REQUEST_TEMPLATE.md? Какая логика? GitHub, да и GitLab нормально воспринимает как файлы с расширение, так и без.
Еще кажется где-то было такое требование, что сам файл лицухи нельзя модифицировать, но может и почудилось, не знаю.
Даже если и есть правило, что файл лицухи нельзя модифицировать, как это связано с расширением md?
Ничего лучше просто текста быть не может — любая система стандартными средствами позволяет без искажений воспроизвести кусок текста. md уже накладывает ограничения для разных там дикторов и глазами для текст с разметкой хуже воспринимать чем без.
О каком ограничении вы говорите? md — это такой же простой текст, а его рендеринг — это дополнительная возможность сервисов. Если следовать такой логике, то другие файлы также должны быть без расширения для лучшего восприятия людьми с ограниченными возможностями? Иначе получится, что LICENSE будут читать, а все остальное уже не получится.
md — подразумевает использование разметки, которая затрудняет чтение людьми.
Остальные файлы — после того как пользователь принимает условия лицензии, пожалуйста, он уже заинтересован в них, следовательно готов применить нужные инструменты.
И при этом маркдаун еще и фрагментирован (в отличие от, например, RST, о котором был — только наполовину шутливый! — камент в начале ветки. :)
Я не навязывваю Markdown, а предлагаю как дополнительную опцию. А вот автор навязывает обычный текст.
Фрагментация имеет значения только для продвинутых фич. Правда это не относится к Markdown хабра, в котором неправильно реализованы переносы строк.
А зачем лицензию читать? Она типовая. Поэтому markdown тут и не нужен — это просто текстовый файл (с gnu.org, например), без изменений. Так и на глаз проще понять что это, например, GPLv3, и автоматическим системам типа fossology проще.
Наличие .travic.yml
.travis.yml может?
Я в середине июля свой первый опыт с opensource-проектом попытался зафиксировать в статейке, что-то похожее вышло. Разве что ещё немного затронул еще пиар проекта. Может кому пригодится.
Просто на гитхаб сложились свои стандарты. Gnu имеет свои, и как мы выяснили чуть выше, предпочитает жить в саванне.
Выбор, как всегда за вами, какому пути следовать.
Нет, вам ничего не потребуется дублировать: GitHub поддерживает отображение README без расширений; файл COPYING тоже поддерживается.
Вообще говоря, до недавнего времени никакой особой «поддержки» для файлов с лицензиями не было и не требовалось. Но с некоторых пор GitHub пытается анализировать эти файлы и высвечивать лицензии (если их удалось определить) на страничке репозитория.
Для CHANGELOG, NEWS и т.п. файлов никакой особенной поддержки нет. Если они у вас есть в GNU-структуре проекта — можете их просто закоммитить, и пользователи смогут эти файлы почитать.
Добавил ссылку в список.
Недавно узнал про набирающий популярность конфигурационный файл .editorconfig ( http://editorconfig.org/ ) — хорошая попытка сделать унифицированный между различными редакторами конфигурационный файл с информацией о принятом в проекте способе оформления файлов (табы/пробелы, кодировка и т.п.). Нравится идея. Я бы добавил в инструкцию.
А еще если в этом файле настроить размер tab равным количеству пробелов принятом в проекте, например 4, то на самом GitHub при пулл-риквесте строки с табами не будут смещены (по-умолчанию tab=8 пробелам). Хотя конечно мешать табы и пробелы в файла самом по себе кощунство.
Пока, более привычно работать в контексте одной директории со склонированным проектом.
По мне это довольно частный совет — далеко не во всех языках и не со всякой системой сборки это имеет смысл или является стандартным подходом. Допустим, проект на Rust с вполне себе современной системой сборки Cargo, хоть и можно при желании собирать вне исходников, все-таки в первую очередь предполагает in-source сборку в директорию target.
Так что тут скорей нужен совет "ознакомьтесь с лучшими практиками использования ваших инструментов и по возможности следуйте им".
А можете объяснить что такого ужасного в сборке проекта в дереве исходников и ведении .gitignore?
Это удобно, например, когда приходят гости (надо отдать архив исходников кому-то или взять с собой).
Чем команда Clean Working Directory не угодила?
Еще одним плюсом чистоты является возможность одновременной (я имею ввиду быстрое переключение без необходимости пересобирать все) сборки несколькими компиляторами и в нескольких режимах, с разными параметрами сборки.
Какой-то специфичный кейс. Да и можно просто настроить разные папки сборок для разных компиляторов.
А вот плюсов собирать прямо в дереве исходников — я лично не вижу.
Например отсутствие необходимости настройки сборки вне репозитория. Это сложнее, чем просто добавить соответствующий .gitignore, а пути сборки при этом нестандартные. Т.е. новички могут не понять куда собирается проект.
Чем команда Clean Working Directory не угодила?
Наверно тем, что при использовании отдельной сборочной binary dir она не нужна, от слова совсем? В голове можно держать другие вещи, помимо того, надо ли сделать чистку исходников или нет.
Какой-то специфичный кейс. Да и можно просто настроить разные папки сборок для разных компиляторов.
Вы в Visual Studio работали, например? Там есть переключение между сборками Release/Debug, а также между x86/x64. И что, мне теперь 4 копии исходников держать, чтобы в разных режимах собирать? Это самый обычный use case.
Например отсутствие необходимости настройки сборки вне репозитория. Это сложнее, чем просто добавить соответствующий .gitignore, а пути сборки при этом нестандартные. Т.е. новички могут не понять куда собирается проект.
О какой сложности вы говорите, если в том же CMake это из коробки есть? Я никогда ничего в CMake-проектах не настраиваю, чтобы собрать в отдельной папке.
Вы в Visual Studio работали, например?
Постоянно :) Зачем 4 копии? Там можно создавать кастомные конфигурации билда по аналогии с Debug и Release.
О какой сложности вы говорите, если в том же CMake это из коробки есть?
В той же Visual Studio не надо дополнительно ничего настраивать, чтобы сборка была вне исходников. По умолчанию сборка в bin/Debug, т.е. внутри репа.
Вы слишком демонизируете. Можно собирать все артефакты в отдельную папку "build" внутри проекта. Ничего не будет замусорено, удалением одной папки можно избавиться от всех предыдущих сборок. И в gitignore будет указан один только путь — к папке "build" или как вам ее удобно назвать.
В качестве примера неправильного поведения — XCode, который по умолчанию собирает проекты куда-то в глубины домашней директории пользователя, тем самым забивая системный диск, так что постоянно приходится искать и чистить эти кеши.
Если у вас действительно какой-то экстремальный случай (исходники расшарены в директории «только для чтения» или вы хотите собираться на другой раздел, где больше свободного места или еще что-то), то дело ваше — настраивайте out-of-the-source.
Но "очень больно бить по рукам", как вы выразились в первом комментарии, тех, кто так не делает — это слишком. У вашего подхода есть как плюсы (не нужно держать .gitihnore, чистая папка с проектом), так и минусы (захламление home-директории, сложнее отыскать директорию сборки).
А еще у сборки in-source есть огромное преимущество — когда я закончил работу, мне не надо выискивать, куда писались артефакты, достаточно удалить корневую папку проекта, все временные файлы удалятся вместе с ней.
Сборку можно делать в поддиректории проекта (честно говоря, ни разу не приходило в голову собираться где-то совсем снаружи), она же в глобальном ~/.gitignore.
Держать папку сборки в глобальном gitignore не очень хорошо, потому что тогда надо будет как-то отдельно добавлять ее всем членам команды. А так — склонировал репо, и все работает с самого начала.
Глобальный gitingore — только для ваших персональных настройкек. У меня там прописана папка ".idea", которую создают продукты JetBrains и .DS_Store, которую создает файловый менеджер на MacOS. Это особенности моего рабочего места, захламлять ими файл проекта, которым пользуются другие, не нужно.
Кстати, говоря про .gitignore, здесь есть подборка хороших практик по содержанию этого файла для различных систем сборки.
Единственное но: за сборку проекта в дереве исходников надо очень больно бить по рукам
Как собирать проект — личное дело пользователя, по рукам надо бить за неполную поддержку любого из способов (а особенно за запрещение одного из них). В CMake, скажем, можно сломать in-source сборку использованием FILE(GLOB ...), которое подхватит кроме исходников проекта служебные файлы cmake. А out-of-source можно сломать не(правильным) использованием переменных *_SOURCE_DIR и *_BINARY_DIR.
А сгенерированные файлы куда при такой сборке куда должны попадать? Т.е. файлы, которые генерируются перед компиляцией, но которые при этом должны быть проигнорированы при коммите. Они считаются исходным кодом или бинариком?
Меркуриал тоже много где используется и для новичка имхо гораздо проще чем гит.
Конечно, это лишь ИМХО)
Этот абзац у автора получился самым спорным и заведомо холиварным.
- Холивар svn/git/hg. При всей популярности git, на hg сидят крупные и важные проекты (JDK, Firefox), да и некоторые с svn не торопятся уйти. У hg и svn с выбором хостинга посложнее, но бросаться фразами "андеграунд, либо суровая проприетарщина" точно не стоило.
- Безальтернативно "только github" тоже опрометчиво. Во-первых, есть bitbucket и gitlab, причем последний семимильными шагами наращивает функциональность. У gitlab есть в общем-то всё что и у github, но есть еще закрытые репозитории, есть встроенный CI (не wow, но для микропроектов вполне), есть возможность экспортировать проект с обвязкой типа issue и т.п. в файл и потом развернуть локально — не так страшно всё потерять.
- Более того огромное количество OS-проектов НЕ хостится на гитхабе. Среди достаточно крупных и серьёзных проектов основной репозиторий на гитхабе скорее исключение, чем норма (linux kernel, kde, gnome, xfce и прочие). Скорее норма какой-нибудь gitorious локальный и списки рассылки. И, да, благодаря архитектуре git у большинства таких проектов есть R/O зеркало на github — просто потому что это легко и незатратно. Но завязывать workflow разработки на github весьма спорная идея даже для pet project.
Хотя если у разработчика есть сомнения, где же выложить свою нетленку, то github самое оно.
Файл .gitattributes позволяет настроить переносы строк для любых файлов, чтобы у всех они были одинаковые, и не было беспорядка в дифах. Также если в вашем GitHub репозитории некорректно определяется язык, то часть файлов также можно проигнорировать с помощью аттрибута linguist-vendored. Вот пример файла .gitattributes с \n разрывами строк и игнорируемыми файлами по фильтру **/examples/*:
*.* eol=lf
**/examples/* linguist-vendored
Хорошее общее правило: код, который генерируется в процессе разработки, тестирования, сборки, компиляции и запуска, должен находиться в каталоге сборке, который лежит отдельно от каталога с исходным кодом. Генерировать что-то внутри каталога с исходным кодом, а тем более класть туда результаты сборки — это плохой стиль.
Здесь уже есть тред про это.
Хорошее общее правило:
Хорошее общее правило — не придумывать общих правил.
У меня результатом make является пачка файликов общим весом в 800кб+ которые являются очень даже читабельными (json, по умолчанию со всеми красивыми отступами) и заглядывать в них в процессе разработки очень даже частенько бывает полезно. И я предпочитаю заглядывать в них в своей любимой IDE.
Ну и автоматическая синхронизация рабочего каталога с дев-сервером освобождает меня от необходимости после каждого изменения лазить на сервер и делать мейк.
Надо заметить, что out-of-source сборки, похоже, в основном используются только у разработчиков на C и C++. Я не видел ни одного проекта на C#, Java, Python или JavaScript, которые бы использовали out-of-source сборки.
Ну то есть ваш совет полезен только применительно к конкретным системам сборки и конкретным языкам.
Как правильно оформить Open Source проект