В свободное и не свободное время[1] я развиваю несколько своих проектов на github, а также, по мере сил, участвую в жизни интересных для меня, как программиста, проектах.
Недавно один из коллег попросил консультацию: как выложить разработанную им библиотеку на github. Библиотека никак не связана с бизнес-логикой приложения компании, по сути это адаптер к некоему API, реализующему определённый стандарт. Помогая ему, я понял что вещи, интуитивно понятные и давно очевидные для меня, в этой области, совершенно неизвестны человеку делающему это впервые и далёкому от Open Source.
Я провел небольшое исследование и обнаружил что большинство публикаций по этой теме на habrahabr освещают тему участия (contributing), либо просто мотивируют каким-нибудь образом примкнуть к Open Source, но не дают исчерпывающей инструкции как правильно оформить свой проект. В целом в рунете, если верить Яндекс, тема освещена со стороны мотивации, этикета контрибуции и основ пользования github. Но не с точки зрения конкретных шагов, которые следует предпринять.
Так что из себя представляет стильный, модный, молодёжный Open Source проект в 201* году?
Данная статья не решает следующие задачи:
- мотивация к участию в Open Source
- PR и продвижение для своих OS-проектов
- обсуждение нюансов программирования
- основы пользования git / github
Для тех кто знает, и является мейнтейнером своего Open Source проекта, или активным контрибьютором в чужих, большинство рассматриваемых в этой статье моментов может быть хорошо знакомым, либо интуитивно понятным. Но, ничто не стоит на месте, и порой я замечаю новые для себя нюансы, которые ещё не использовал, и которые бы повысили удобство пользователей. Поэтому в комментариях буду рад увидеть ваши интересные идеи, дополняющие статью.
Must Have
Сперва хотелось бы рассмотреть "must have" для любого OS-проекта. Минимальный джентльменский набор, без которого ваш проект не будет производить впечатление законченного. Лично я, при выборе библиотеки, считаю каждый из этих пунктов обязательным, для того чтобы добавить новую зависимость в менеджере пакетов.
Github
Очевидно что github лидирует как хостинг OS-проектов, и флагман современной разработки вообще. Так же очевидный выбор СКВ для проекта, которым вы решили поделиться с миром: git. Без вариантов. Все альтернативы — это, де-факто, андеграунд, либо суровая проприетарщина.
В каждом репозитории должен быть .gitignore, соответствующий языку и типу проекта. Выбрать шаблон для вашего случая можно здесь.
Общее правило: код — который генерируется в процессе разработки, тестирования, сборки/компиляции, рантайма — должен находиться в gitignore.
Лицензия
Второй маленький шаг для проекта и огромный для человечества — выбор и создание файла лицензии.
Github, при создании проекта, позволяет выбрать подходящую лицензию. Файл должен называться LICENSE, без расширения.
Очень подробная статья на тему выбора свободной лицензии от marked-one
README.md
Этот файл является лицом вашего проекта. Именно его видит пользователь заходя на главную страницу. Содержимое этого же файла будет показано в большинстве сервисов с которыми вы интегрируетесь (например реестры пакетных менеджеров и т.п.).
Как минимум он должен содержать общее описание по следующим пунктам:
- Назначение библиотеки (проекта, инструмента, фреймворка)
- Системные требования (версия языка, требования к ресурсам, системные зависимости, нужные расширения)
- Шаги по установке, сборке, запуску
- Примеры использования или ссылки на документацию
Версионирование (SemVer) и журнал изменений (CHANGELOG.md)
После публикации кода, вы несёте моральную ответственность перед вашими пользователями за его работоспособность в случае обновлений. Для этого умными людьми были придуманы две отличные штуки. Приведу лишь ссылки, разобраться в них нетрудно, надо лишь прочитать:
Всегда следуйте им, и ваша карма будет безукоризненной.
Тестирование
Если вы ещё не инфицированы TDD, то могу заразить =)
Чем можно доказать, что код вообще работает, если не тестами? Как доказать, что 100% вашего кода работает ожидаемым образом, как не полным покрытием?
Конечно 100% покрытие не даёт 100% гарантии отсутствия багов и верности реализации, но как ничто другое приближает к этому недостижимому идеалу.
Тесты — единственный формальный способ доказать корректность и работоспособность кода потенциальному пользователю-программисту. Обещания оставьте гуманитариям, коллегам из QA и девушкам.
CI
Travis-ci подключается к github в пару кликов. Наличие .travis.yml в репозитории — обязательно, если, конечно, вы не используете что-то более сложное.
Пакетный менеджер
Если для вашей платформы есть пакетный менеджер, потрудитесь чтобы ваш код мог быть получен через него. Composer, npm, maven, etc.
Также важно чтобы актуальная версия (в соответствии с SemVer, ага) автоматически, после прохождения CI (и тестирования, ага), попадала в реестр.
К счастью, для большинства мейнстримовых языков такие менеджеры есть и интегрируются с github / travis в пару кликов / строчек конфига.
Зависимости вашего кода, само собой должны быть надлежащим образом оформлены при помощи файла конфигурации того же менеджера.
Внедрение зависимостей, SOLID, etc
Постарайтесь также взглянуть на свой код со стороны.
Если это библиотека общего назначения или фреймворк: насколько удобно будет его использовать в проекте построенном на совершенно другом фреймворке или без оного? Как насчёт Open/Closed? Можно ли заинжектить по интерфейсу один из компонентов вашей библиотеки, который кому-то потребовалось поменять? Все ли опции поддаются простому программному конфигурированию?
Если это утилита, например командной строки: хорошо ли она подходит для встраивания в имеющиеся скрипты автоматизации? Как насчёт полезных сообщений об ошибках и корректных кодах возврата?
Наиболее жизнеспособные и удачные проекты — это те, которые были рождены в муках, в реальных боевых условиях и извлечены из недр копи-пасты на белый свет.
Не примерив на себя роль пользователя, вы не сможете адекватно спроектировать интерфейс приложения.
Стандарты
Используйте стандарты языка и его сообщества: JSR, PSR, общепринятые code styles. Если вы до этого не вникали в эти дебри, самое время!
Посмотрите на мейнстримовые библиотеки для сходных задач в вашем языке: какие интерфейсы и стандарты реализуют они?
Речь не только про конкретные RFC, но и в целом это касается стандартных подходов к решению типичных задач.
Не критично, но очень желательно
Подробная документация, примеры, FAQ
Минимальные примеры использования вашего кода должны быть в README. Но, надеюсь, вы, как программист, согласитесь насколько приятно быстро находить ответы на свои вопросы.
Есть несколько способов организовать проактивную помощь вашим пользователям. Каждый из них по своему удобен и эффективен в зависимости от специфики проекта и аудитории.
- Wiki-документация. Может быть размещена на том же github, либо в виде набора md файлов в самом репозитории или на github pages, или вообще на отдельном сайте.
- Небольшие проекты-репозитории с типичными примерами использования. Бывает очень полезно для проектов, представляющих собой что-то среднее между фреймворком и библиотекой.
- FAQ — пополняемый из собственного и пользовательского опыта.
Для реактивной поддержки github имеет issues.
Файлы CONTRIBUTING.md, CONTRIBUTORS.md, ISSUE_TEMPLATE.md, PULL_REQUEST_TEMPLATE.md
Если вам повезло, и вы не единственный разработчик, либо настолько амбициозны, что рассчитываете на дикий прилив свежих сил сразу после публикации на github, то этот набор вам поможет.
В первом случае: работать по одним правилам и не холиварить по пустякам.
Во втором: облегчить участие новичков и исключить недопонимание.
Сюда же стоит отнести использование линтеров, статических анализаторов, автоформаттеров и прочего — все это очень облегчает командную разработку.
В настройка github вы можете найти чеклист, который сориентирует вас чего не хватает проекту для полного лоска. Пример чеклиста: https://github.com/github/gitignore/community (аналогичная страница есть у любого репозитория, даже у вашего))
Шик, блеск, красота
И, напоследок, опциональные фишки, которые, тем не менее, производят приятное впечатление и могут существенно помочь пользователям вашего кода.
Бейджи
Отличная штука. Очень удобно с первого взгляда на README получить представление о статусе проекта. Лично я считаю наиболее наглядными следующие характеристики:
- процент покрытия
- актуальная стабильная версия
- статистика скачиваний в реестре / звезд, или другая фаллометрия свидетельствующая о популярности или востребованности
Главное не переусердствовать.
Интеграция с сервисами
Рынок CI последние годы очень активно развивался и существует огромный выбор сервисов по анализу кода, хранению артефатов сборки и тестирования и т.п. Большинство из них, как правило, легко интегрируются с github и бесплатны для открытых проектов.
- https://codecov.io
- https://codeclimate.com/
- https://www.bithound.io
- https://scrutinizer-ci.com/
- https://codeship.com/
- … тысячи их под любой язык и задачу
Делитесь в комментария интересными находками!
Docker?
Казалось бы, при чём тут докер?
А вот: он может быть использован для тестирования, разработки и поставки вашего детища.
Некоторые CI-сервисы используют докер. Некоторые виды тестирования удобно автоматизировать при помощи контейнеризации.
Раньше приходилось использовать vagrant для унификации рабочего окружения. Docker вполне может взять эту задачу на себя. Многие задачи по сборке, которые надо выполнять на машине разработчика могут быть контейнеризированы. Это поможет избежать дополнительных усилий по настройке локальной машины под проект и проблем типа "а у меня все работает...".
Некоторые программные решения удобно поставлять в виде докер-образа, учитывая что многие уже используют docker-compose и stack в своих проектах. В этом случае подключение вашей разработки упрощается до пары строчек в docker-compose.yml.
[1]: я считаю что в рамках работы почти всегда есть место Open Source. Например: на предыдущей работе я использовал одну собственную библиотеку в продакшен, а другой сервис, разработанный на выходных для текущих нужд проекта, также по договорённости с техдиром, оставил на github и docker hub. Если библиотека не связана с бизнес-логикой проекта, и вы готовы уделить ей пару часов на досуге, то адекватное начальство всегда пойдёт вам навстречу. Ведь это взаимовыгодный шаг: компания получает бонусные человекочасы (сейчас, и потенциально даже после вашего ухода), вы — публичное портфолио за рамками NDA.
Комментарии (107)
RomanPokrovskij
30.10.2017 00:02Спасибо за поднятую тему.
А какое соглашение есть на гитхабе при публикации changelog'ов? Как вы их публикуете?
samizdam Автор
30.10.2017 00:13Инициатива по унификации changelog выходит за рамки github
Сайт инициативы keepachangelog.com
Преимущество именно этого формата: использование md и продуманная согласованность с SemVer.
Большинство OS проектов придерживаются описанного там формата. Хотя есть и другие попытки стандартизации, например GNU: www.gnu.org/prep/standards/html_node/Style-of-Change-Logs.html
samizdam Автор
30.10.2017 00:14Публикуется как и всё остальное — коммитом в репозиторий…
Или я не понял вопрос?RomanPokrovskij
30.10.2017 02:38Название и расположение документа в дереве? Возможно вообще есть сторонний сервис, возможно искть надо в «гитхаб релизах» — релиз версию и создает, а там есть поля с описанием релиза, но как потом этот текст сделать доступным как ссылку с readme.md? Я не знаю потому и спрашиваю. Множество проектов вообще не имеет никакого намека на ченжлог в гитхабе.
arheops
30.10.2017 06:30+1Вроде как это еще раньше стандартизировалося. название CHANGELOG.md и в корне.
samizdam Автор
30.10.2017 18:52+1В корне проекта /CHANGELOG.md
В примере на сайте keepachangelog.com есть каноничный пример со ссылками на diff между каждой версией на github.
В гитхаб релизах версии — это теги + UI обвязка, позволяющая вручную заполнить описание релиза.
Есть разные инструменты для генерации CHANGELOG, но предпочтительный вариант — заполнять его вручную по мере внесения изменений. Сама методика заполнения детально рассмотрена на упомянутом сайте.AMDmi3
31.10.2017 15:54+1Добавлю что если хорошо вести CHANGELOG.md по мере разработки, заполнение описания релиза на GH сведётся просто к копированию последнего раздела оттуда.
SirEdvin
30.10.2017 00:14Очевидно что github лидирует как хостинг OS-проектов
Я бы поставил это утверждение под вопрос, на самом деле. Потому что у самого Github в этом плане не все так прозрачно, тот же GNU в своем рейтинге этичности репозиториев выдал ему F. Вы можете сказать, на это в целом плевать и все такое, но мне бы не хотелось выяснить, что мой проект внезапно удалили из github просто потому, что так кто-то захотел.
denismaster
30.10.2017 00:21Зато поставил А для Savannah. Если не хотите, чтобы проект удалили — лучше своего сервера не найти.
SirEdvin
30.10.2017 00:23Если бы они только решились на его редизайн( Но пока нет, но после череды скандалов ряд проектов таки переехали на gitlab или даже bitbucket.
sumanai
30.10.2017 18:32Зато поставил А для Savannah.
Который требует слишком много персональных данных и имеет ручной аппрув репозиториев. Спасибо, не нужно.
AMDmi3
31.10.2017 15:37+1Напротив, как раз хостить проект на своём сервере — лучший способ его потерять через пару лет, поскольку поддержка будет упираться в одного человека, работающего за бесплатно, т.е. вас. Сервер упадёт — вы этого даже не заметите. Случится что-нибудь, не дай бог, с вами, или просто переедете, сервер сломается, надоест поддерживать, кончатся деньги — проект исчезнет. У меня есть кое-какая статистика с https://repology.org: мёртвых ссылок на хостинги намного меньше чем мертвых ссылок на отдельные домены.
AMDmi3
31.10.2017 15:48+1Да, добавлю что хоститься [где и как угодно] никто не запрещает, но зеркало на GitHub — must have и лучший способ обеспечить доступность проекта несмотря ни на что.
samizdam Автор
30.10.2017 00:32Конечно, под «лидерством» я имел в виду качественно-количественные показатели.
git распределённая система, поэтому удаление с github конечно неприятный момент, но, технически, не фатальный.
К стыду своему, я мало работал с другими СКВ, но насколько понимаю, поддерживаемая лидером GNU-рейтинга «Саванной» централизованная CVS не обладает таким преимуществом, тем самым делая его более уязвимым и критическим узлом для проектов, которые там хостятся.SirEdvin
30.10.2017 00:38Ну, "децентрализованность" — это круто, но по факту вы все равно сильно завязываетесь на github из-за CI, ведения багов и прочего. То есть, код то у вас будет, коммитить можно, но все остальное работать без него не будет.
samizdam Автор
30.10.2017 00:44Ну, тут как говорится: Вам шашечки или ехать?
MacIn
30.10.2017 18:37Если ехать, то децентрализация не есть что-то, без чего жить нельзя. Ехать — это хранить код, делать в нем изменения с сохранением истории, принимать запросы на исправление, сообщения об ошибках. Возможность сделать резервную копию, например, по расписанию — в плюс и более-менее устраняет проблему с внезапным удалением. Децентрализация — это не «круто, must have», это лишь инструмент, который не всем и не всегда подходит.
Kanedias
30.10.2017 08:42+2Подождите, тут недопонимание. Savannah поддерживает Git: https://savannah.gnu.org/maintenance/UsingGit/
Другое дело, что пользоваться им непрактично, очень много чего не хватает, так что лучше уж GitLab. Заблокируют что-то — поставлю свой инстанс на своём же сервере и буду дальше раздавать. Да и в рейтинге GNU Gitlab заработал С только потому что не подровнял свой JS и по-умолчанию не создаёт файл LICENSE, что вообще минорщина.
sumanai
30.10.2017 18:41К стыду своему, я мало работал с другими СКВ
Я вот работаю с Mercurial, который ничем не уступает Git, а по мне так и превосходит благодаря хорошим GUI инструментам и настоящим веткам, которые никуда не пропадают. И он достаточно прозрачно зеркалится в Git, так что я размещаю свои проекты сразу в HG на Bitbucket и в Git на GitHub.
aaaler
30.10.2017 00:50мой проект внезапно удалили
Вы не совсем правильно понимаете смысл рейтинга. Основной смысл претензии GNU к github — использование js кода с несвободными лицензями и выполнение требований роскомнадзора.
SirEdvin
30.10.2017 00:55выполнение требований роскомнадзора.
мой проект внезапно удалилиОсновная проблема в этом плане — это подчинение локальному законодательству отдельной страны, которая вообще может не иметь отношения ко мне. Понятное дело, код крупных компаний github трогать не станет, но вот мой пет-проект, в котором, например, будет слово, которое так любит роскомнадзор — вполне.
sumanai
30.10.2017 18:36-1Savannah не удалит проект по требованиям роскомнадзора лишь потому, что удалять там нечего, он слабо наполнен из-за ручной модерации, так же из-за неё там не разместят всеми любимые способы самоубийства. Если бы им пришло письмо от РКН, уверен, они бы удалили проект вмиг.
AMDmi3
31.10.2017 15:49что мой проект внезапно удалили из github просто потому, что так кто-то захотел
Это какая-то страшилка для детей. Просто так проекты не удаляют, а если в вашему проекту могут быть законные претензии, его удалит любой хостинг, а ваш личный сервер заблокируют или его откажется обслуживать хостер.
GitHub же действительно лидер, а скорее даже безальтернативное решение.
SirEdvin
31.10.2017 16:10GitHub же действительно лидер, а скорее даже безальтернативное решение.
Безальтернативное в плане? Я вот сижу на gitlab, мне нормально (разве что он иногда лежит, но так и github умеет).
Поисковые запросы из google и в gitlab ищут. Или вы из тех людей, которые ищут проекты сразу через поиск github?AMDmi3
31.10.2017 17:38+2Безальтернативное в плане?
В том плане, что 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 мне никогда не покажет.
SirEdvin
31.10.2017 23:09+2В том плане, что 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).
AMDmi3
01.11.2017 15:14+2Зашкварится 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, заполнять полтора десятка полей, создавать и прикреплять патч, ещё и уникальное имя ему выбирая.
SirEdvin
01.11.2017 15:30+1А нигде лучше не будет. Так, 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 даже не будут читать, а просто закроют с комментом "не по форме" в почти любом крупном проекте.
AMDmi3
01.11.2017 16:54+1Но ведь я говорил не про 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 всегда оформлены без шаблонов, точно так чтобы максимально точно и ёмко описать конкретную проблему.
SirEdvin
01.11.2017 23:03Вообще-то, в 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.
speshuric
02.11.2017 01:29Крупные проекты ну никак не релевантны "советам как оформлять 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 в одной организации.
KvanTTT
30.10.2017 03:28Файл должен называться LICENSE, без расширения.
Это почему без расширения? Markdown файлы приятней читать.
Tallefer
30.10.2017 04:40Никаких README.md, только README.rst, только
хардкор! Ну ладно, хардкор это README.textile, а лучше README.pod или README.org. %)
KvanTTT
31.10.2017 00:00Не понял, почему минусы? Пункты, заголовки, ссылки и другие вещи приятней читать в отрендеренном виде, особенно если это кастомная лицензия, где такого много.
Ну и почему LICENSE без расширения, а все остальные с расширением, т.е. CONTRIBUTING.md, CONTRIBUTORS.md, ISSUE_TEMPLATE.md, PULL_REQUEST_TEMPLATE.md? Какая логика? GitHub, да и GitLab нормально воспринимает как файлы с расширение, так и без.
Tallefer
31.10.2017 02:59А фиг знает. :) Предположу, что в лицензии оформление вообще не нужно, потому что ее все равно никто не читает. %)
Еще кажется где-то было такое требование, что сам файл лицухи нельзя модифицировать, но может и почудилось, не знаю.KvanTTT
31.10.2017 12:42Даже если и есть правило, что файл лицухи нельзя модифицировать, как это связано с расширением md?
samizdam Автор
31.10.2017 13:01Мне кажется, логичное требование к файлу лицензии — максимальная переносимость и доступность.
Ничего лучше просто текста быть не может — любая система стандартными средствами позволяет без искажений воспроизвести кусок текста. md уже накладывает ограничения для разных там дикторов и глазами для текст с разметкой хуже воспринимать чем без.KvanTTT
31.10.2017 13:21О каком ограничении вы говорите? md — это такой же простой текст, а его рендеринг — это дополнительная возможность сервисов. Если следовать такой логике, то другие файлы также должны быть без расширения для лучшего восприятия людьми с ограниченными возможностями? Иначе получится, что LICENSE будут читать, а все остальное уже не получится.
samizdam Автор
31.10.2017 13:41LICENSE должен быть доступен в любом случае.
md — подразумевает использование разметки, которая затрудняет чтение людьми.
Остальные файлы — после того как пользователь принимает условия лицензии, пожалуйста, он уже заинтересован в них, следовательно готов применить нужные инструменты.
Tallefer
31.10.2017 14:55Важно понимать и помнить, что, навязывая один формат (в данном случае маркдаун), мы автоматически отказываемся от других форматов.
И при этом маркдаун еще и фрагментирован (в отличие от, например, RST, о котором был — только наполовину шутливый! — камент в начале ветки. :)KvanTTT
31.10.2017 15:02Я не навязывваю Markdown, а предлагаю как дополнительную опцию. А вот автор навязывает обычный текст.
Фрагментация имеет значения только для продвинутых фич. Правда это не относится к Markdown хабра, в котором неправильно реализованы переносы строк.
Tallefer
31.10.2017 17:05А я и не имею в виду личное навязывание, просто как факт. :)
Ну и навязывать плейн текст бессмысленно, его и так все используют же. :)
То есть суть проблемы в отходе от глобального стандарта к имеющему меньший охват.
Tallefer
31.10.2017 14:44Опять же, предположу, что раз кто-то назвал файл.мд, то он собирается воспользоваться маркдауном, иначе зачем? :)
AMDmi3
31.10.2017 13:37А зачем лицензию читать? Она типовая. Поэтому markdown тут и не нужен — это просто текстовый файл (с gnu.org, например), без изменений. Так и на глаз проще понять что это, например, GPLv3, и автоматическим системам типа fossology проще.
wholeman
30.10.2017 10:23А если я хочу придерживаться стандартов оформления GNU, придётся дублировать README, COPYING и ChangeLog под другими именами?
samizdam Автор
30.10.2017 12:08Дублировать вряд ли стоит.
Просто на гитхаб сложились свои стандарты. Gnu имеет свои, и как мы выяснили чуть выше, предпочитает жить в саванне.
Выбор, как всегда за вами, какому пути следовать.
eignatik
30.10.2017 12:12Еще из CI могу добавить codeship. Неплохой CI tool тоже, легко прикручивается. Из ограничений — для опен сорс проектов нельзя параллелить тесты, так что все последовательно. Но в целом мне нравится, работает неплохо. Но я обязательно поковыряю другие, например, travis (UI у него классный)
samizdam Автор
30.10.2017 18:41Да, тоже codeship.com когда-то рассматривал.
Добавил ссылку в список.
Self_Perfection
30.10.2017 15:30+2Недавно узнал про набирающий популярность конфигурационный файл
.editorconfig( http://editorconfig.org/ ) — хорошая попытка сделать унифицированный между различными редакторами конфигурационный файл с информацией о принятом в проекте способе оформления файлов (табы/пробелы, кодировка и т.п.). Нравится идея. Я бы добавил в инструкцию.
unclechu
31.10.2017 13:25Я про него узнал уже несколько лет назад, с тех пор всегда кладу в любой проект, удивился почему не упомянут в статье.
KvanTTT
31.10.2017 13:40А еще если в этом файле настроить размер tab равным количеству пробелов принятом в проекте, например 4, то на самом GitHub при пулл-риквесте строки с табами не будут смещены (по-умолчанию tab=8 пробелам). Хотя конечно мешать табы и пробелы в файла самом по себе кощунство.
Tallefer
31.10.2017 14:49И вовсе не кощунство, просто мало кто делает это грамотно. :)
Только прошу, не надо начинать в этой ветке холивар. %)
passanger2012
30.10.2017 22:47+1Спасибо за статью, в общем и целом согласен. Единственное но: за сборку проекта в дереве исходников надо очень больно бить по рукам. Сегодня практически все современные системы поддерживают out-of-source сборку, вследствие чего необходимость .gitignore отпадает.
samizdam Автор
30.10.2017 23:41Хм, интересная концепция, но мало с ней знаком, к сожалению.
Пока, более привычно работать в контексте одной директории со склонированным проектом.passanger2012
31.10.2017 00:25+1Что CMake, что Autotools, давно поддерживают и продвигают эту концепцию сборки. Равно как и современные IDE, например Qt Creator. Действительно очень удобная штука, которая, например, позволяет одновременно иметь несколько сборок различного типа (release/debug) с легкостью переключения между ними.
ozkriff
31.10.2017 09:40По мне это довольно частный совет — далеко не во всех языках и не со всякой системой сборки это имеет смысл или является стандартным подходом. Допустим, проект на Rust с вполне себе современной системой сборки Cargo, хоть и можно при желании собирать вне исходников, все-таки в первую очередь предполагает in-source сборку в директорию
target.
Так что тут скорей нужен совет "ознакомьтесь с лучшими практиками использования ваших инструментов и по возможности следуйте им".
samizdam Автор
31.10.2017 13:06Я бы добавил что out-of-source более актуально для компилируемых языков.
Для интерпретируемых in-source во многих случаях достаточен, т.к. не всегда есть получение артефактов из исходников. Чаще артефаты требующие игнорирования — это логи, репорты и локальные конфиги.
KvanTTT
31.10.2017 13:23+1А можете объяснить что такого ужасного в сборке проекта в дереве исходников и ведении .gitignore?
trawl
31.10.2017 15:48Ужасного ничего в этом нет. Но, зачем вести .gitignore, если его можно не вести?
passanger2012
01.11.2017 11:52Как уже отметили, если язык и средства предоставляют такую возможность, то это как содержать квартиру в чистоте. Можно, конечно, разбрасывать мусор и либо его не замечать (а-ля .gitignore), либо периодически чистить (а-ля make clean). Но лучше, когда мусора нет совсем. Это удобно, например, когда приходят гости (надо отдать архив исходников кому-то или взять с собой). Еще одним плюсом чистоты является возможность одновременной (я имею ввиду быстрое переключение без необходимости пересобирать все) сборки несколькими компиляторами и в нескольких режимах, с разными параметрами сборки. Ну и чистить легко — просто удаляется директория сборки, и это гарантирует, что где-то среди исходников не затерялся какой-то объектник, который потом может быть подхвачен кривым makefile. А вот плюсов собирать прямо в дереве исходников — я лично не вижу.
KvanTTT
01.11.2017 12:27Это удобно, например, когда приходят гости (надо отдать архив исходников кому-то или взять с собой).
Чем команда Clean Working Directory не угодила?
Еще одним плюсом чистоты является возможность одновременной (я имею ввиду быстрое переключение без необходимости пересобирать все) сборки несколькими компиляторами и в нескольких режимах, с разными параметрами сборки.
Какой-то специфичный кейс. Да и можно просто настроить разные папки сборок для разных компиляторов.
А вот плюсов собирать прямо в дереве исходников — я лично не вижу.
Например отсутствие необходимости настройки сборки вне репозитория. Это сложнее, чем просто добавить соответствующий .gitignore, а пути сборки при этом нестандартные. Т.е. новички могут не понять куда собирается проект.
justboris
01.11.2017 16:33Вы слишком демонизируете. Можно собирать все артефакты в отдельную папку "build" внутри проекта. Ничего не будет замусорено, удалением одной папки можно избавиться от всех предыдущих сборок. И в gitignore будет указан один только путь — к папке "build" или как вам ее удобно назвать.
justboris
01.11.2017 16:36+1А еще у сборки in-source есть огромное преимущество — когда я закончил работу, мне не надо выискивать, куда писались артефакты, достаточно удалить корневую папку проекта, все временные файлы удалятся вместе с ней.
AMDmi3
01.11.2017 16:57Сборку можно делать в поддиректории проекта (честно говоря, ни разу не приходило в голову собираться где-то совсем снаружи), она же в глобальном ~/.gitignore.
justboris
01.11.2017 17:08Держать папку сборки в глобальном gitignore не очень хорошо, потому что тогда надо будет как-то отдельно добавлять ее всем членам команды. А так — склонировал репо, и все работает с самого начала.
Глобальный gitingore — только для ваших персональных настройкек. У меня там прописана папка ".idea", которую создают продукты JetBrains и
.DS_Store, которую создает файловый менеджер на MacOS. Это особенности моего рабочего места, захламлять ими файл проекта, которым пользуются другие, не нужно.
Кстати, говоря про .gitignore, здесь есть подборка хороших практик по содержанию этого файла для различных систем сборки.
AMDmi3
01.11.2017 17:18Глобальный gitingore — только для ваших персональных настройкек
А это и есть персональная настройка, такая же как где собирать код. Кто использует поддиректорию в проекте тот и прописывает.
justboris
01.11.2017 17:26+1Если система сборки настолько гибкая, то вы правы. Те, с которыми мне приходилось работать, обычно имели какое-то дефолтное положение "build" или "target", которое никто никогда не менял.
AMDmi3
31.10.2017 13:45Единственное но: за сборку проекта в дереве исходников надо очень больно бить по рукам
Как собирать проект — личное дело пользователя, по рукам надо бить за неполную поддержку любого из способов (а особенно за запрещение одного из них). В CMake, скажем, можно сломать in-source сборку использованием
FILE(GLOB ...), которое подхватит кроме исходников проекта служебные файлы cmake. А out-of-source можно сломать не(правильным) использованием переменных*_SOURCE_DIRи*_BINARY_DIR.
Andronas
31.10.2017 10:30Цитата «Все альтернативы — это, де-факто, андеграунд, либо суровая проприетарщина.»
Меркуриал тоже много где используется и для новичка имхо гораздо проще чем гит.samizdam Автор
31.10.2017 13:12Мы пробовали однажды командой перейти с SVN на hg. При этом в компании все другие команды использовали меркуриал много лет, так что были эксперты у которых мы спрашивали советы и т.п… И все же, после git, для нас он не показался проще или понятнее, и переход не задался. И как показала практика, другие проекты в компании тоже стали постепенно мигрировать и начинать в git чтобы упростить интеграцию с большинством сервисом и инструментов.
Конечно, это лишь ИМХО)
speshuric
01.11.2017 00:53Этот абзац у автора получился самым спорным и заведомо холиварным.
- Холивар 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 самое оно.
KvanTTT
31.10.2017 13:29Файл .gitattributes позволяет настроить переносы строк для любых файлов, чтобы у всех они были одинаковые, и не было беспорядка в дифах. Также если в вашем GitHub репозитории некорректно определяется язык, то часть файлов также можно проигнорировать с помощью аттрибута
linguist-vendored. Вот пример файла .gitattributes с\nразрывами строк и игнорируемыми файлами по фильтру**/examples/*:
*.* eol=lf **/examples/* linguist-vendored
esil
01.11.2017 20:22«Общее правило: код — который генерируется в процессе разработки, тестирования, сборки/компиляции, рантайма — должен находиться в gitignore»
Хорошее общее правило: код, который генерируется в процессе разработки, тестирования, сборки, компиляции и запуска, должен находиться в каталоге сборке, который лежит отдельно от каталога с исходным кодом. Генерировать что-то внутри каталога с исходным кодом, а тем более класть туда результаты сборки — это плохой стиль.
Mendel
01.11.2017 23:49Хорошее общее правило:
Хорошее общее правило — не придумывать общих правил.
У меня результатом make является пачка файликов общим весом в 800кб+ которые являются очень даже читабельными (json, по умолчанию со всеми красивыми отступами) и заглядывать в них в процессе разработки очень даже частенько бывает полезно. И я предпочитаю заглядывать в них в своей любимой IDE.
Ну и автоматическая синхронизация рабочего каталога с дев-сервером освобождает меня от необходимости после каждого изменения лазить на сервер и делать мейк.
DrPass
Я, пожалуй, вам возражу (это, конечно, моё личное ИМХО, а не руководство к действию). Если я делаю проект просто так, «для души», и им собираюсь поделиться с общественностью, если он будет полезным, то… я его буду делать так, как мне нравится. Я буду использовать тот хостинг, который мне нравится (ну ладно, я в этом плане ничуть не оригинален, также использую гитхаб), буду оформлять так, как мне удобнее и т.д. Если я не сделал подробную документацию, это означает, например, что у меня нет времени на это или желания. И «перепрыгнуть через себя», чтобы сделать проект более понятным возможным пользователям — это уже далеко за рамками пет-проекта. Он должен приносить удовольствие разработчику, а не быть рутиной.
samizdam Автор
Конечно, Open Source такой Open Source — никто никому ничего не должен и не обещал. Всё по доброй воле.
Но, полагаю вы согласитесь, с точки зрения пользователя — нормально оформленный проект имеет больше шансов быть использованным чем просто запушенные «пет»-сырцы без каких либо дополнительных усилий.
Моя цель не в том, чтобы кого-то заставить или мотивировать, а в том, чтобы помочь разработчикам _желающим_ помочь потенциальным пользователям.
Ну и обсудить набор полезных практик и приемов по сабжу.
wlbm_onizuka
Гитхабу нужен нормальный визуальный инструмент для управления проектом, чтобы чек-лист был очевиден. Если улучшить восприятие своего проекта пользователями можно будет потратив совсем немного ментальной энергии, мало кто станет этим пренебрегать. На одних «соглашениях» далеко не уедешь.
samizdam Автор
Ну, вообще чеклист как бы есть, если не путаю, то не так давно появился.
Вот например:
github.com/github/gitignore/community
И такая страница в любом репозитории есть.
Добавлю пожалуй в статью.
ls1
По ссылке вижу 404
wlbm_onizuka
просто нужно залогиниться
OlegMax
Ну и как ощущения — сколько звёзд, сколько pull request'ов?
Mendel
С одной стороны я согласен с Вами — мы делаем проект для чего-то, и делаем его свободным тоже с какой-то целью, и цели эти обычно — ЧСВ, портфолио, улучшение кода от пулреквестов и тикетов с проблемами (по сути расширенное/распределенное бесплатное тестирование пользователями). И конечно все наши цели впрямую коррелируют с качеством оформления репозитария.
Но! Есть и другая сторона вопроса — я вот взялся «причесать» свой проект перед выкатыванием в паблик альфы. Работал над проектом два года, переделал несколько раз с нуля… Сейчас жалею что не выкатил полгода назад «как есть», может быть обратная связь дала бы уже свои плоды? Может быть кто-то бы помог с рутиной?.. Да и не доведу я его сам никогда до состояния «конфетки».
Статья безусловно хорошая, в том плане что как минимум дает дорожную карту того что должно быть, а уж на каком этапе все это вводить — дело каждого. Но не стоит настаивать на том что оно должно быть совсем уж обязательно…
OlegMax
Мне просто любопытно, работает ли подход — «Вот, я выложил свой гениальный многолетний труд — пользуйтесь и благодарите! Документирование, поддержка, удобная сборка не приносят удовольствие разработчику, поэтому обойдетесь.»
Mendel
Ну половина популярных библиотек ужасны, но проще с ними разобраться чем запускать свое… Ровно до тех пор пока кто-то не допилит ее до нормального вида, не сделает форк который допилит, или не напишет с нуля аналог который будет человеческим из коробки. Во всем нужен баланс. Разработчик исповедующий принцип «любите меня семеро, я создал» будет неприятно удивлен, что его сырое чудо никто не любит. Но тот кто будет слишком тщательно вылизывать — тоже огорчится от того что не успеет выложить никогда…
MacIn
Хм, интересно, если человек выложит проект вне парадигмы git и github, где нет ни звезд, ни пуллреквестов, как вы будете оценивать его проект и проводить сравнение?
OlegMax
Зачем?
MacIn
Это полу-риторический вопрос, пролог к обсуждению.
Mendel
Если всего этого не будет, то… все это будет, но в личке.
justboris
По моему мнению, необходимый минимум такой
Полировать исходники до блеска и документировать каждый метод не стоит, можно сделать и позже, когда пользователи и контрибуторы появится