Эта статья - мое абсолютно субъективное мнение с прицелом на людей, которые уже сейчас занимаются или близки к тому, чтобы начать заниматься своими open-source проектами в сфере 1С. Оно может показаться вам неправильным или неоправданно назидательным. Я это понимаю - возражения в комментариях приветствуются
Open-source медленно, но верно входит в повседневную жизнь 1С-сообщества. И это здорово! Специфика у него, конечно, как обычно, своя: обработки на Инфостарт это тоже некоторого рода Open-source, и вот они-то уже точно в обиходе очень давно, но мы поговорим про другой вид открытого кода - более классический, основанный на репозиториях, распределенной разработке и свободных лицензиях. Т.е. о том, что обычно под этим понятием подразумевается
Обладая статистикой OpenYellow и желтым поясом по Консоли запросов УФ 8.3.7.1., могу поделиться следующей информацией: В 2024 году в 1С-сообществе на Github
- Появилось 86 новых репозиториев (>=1 звезды)
- Активно обновляется 330 репозиториев (>=1 звезды)
- Всего существует 1781 репозиторий (>=1 звезды)
Это не очень много, но они есть и, как отмечено выше, это репозитории >=1 звезды. Получить 1 звезду это не какое-то убердостижение: в конце концов ее можно поставить себе самому, но выходит так, что подавляющее большинство репозиториев не имеют даже ее, а те, которые имеют, в большинстве своем на ней и заканчиваются. Когда-то я уже анализировал состояние "желтого" Github и там была вот такая статистика:
Сделаем простой запрос с отбором по языку
https://api.github.com/search/repositories?q=language:"1C+Enterprise"
И получим ответ: 3367 репозитория. Ну, можно сказать, что они есть. Однако едва ли нас сможет заинтересовать каждый из этих проектов. Предлагаю исключить из выборки те, которые собрали к текущему моменту меньше 5 звезд
https://api.github.com/search/repositories?q=stars:>=5+language:"1C+Enterprise"
Это был отбор только по языку, в статистике OpenYellow же собираются данные про все репозитории, так или иначе связанные с 1С, вне зависимости от языка. К чему я веду? К тому, что ситуация такова: репозитории есть, но о большинстве из них никто не знает и они не собирают ни поддержки, ни обратной связи. От чего скоропостижно и загибаются
Немного про звезды
"Чего ты докопался до этих звезд, ты что - астроном?"
Действительно, нужно обозначить значимость показателя, на который я опираюсь и поговорить о мотивационной составляющей занятия открытыми проектами в целом
Звезда на Github (также как и на Gitlab), в практическом понимании, это закладка - подписка пользователя на получение новостей о вашем репозитории в дальнейшем, в частности о новых релизах. Из этого, в свою очередь, напрямую выходит другое, более человечное понимание: количество звезд - это количество людей, которые заинтересованы в вашем проекте
Шило в мешке не утаишь: материальных благ подобные проекты не приносят, а следовательно мотивация держится только на этом - "Мой проект полезен и это здорово". В дальнейшем это может перерасти и в коллективную разработку, когда разрабатывается проект, объемы которого не по силам одному человеку, может перерасти и в буст карьеры - но когда мы говорим про старт, речи о таком, на мой взгляд, идти не может. В любом случае:
Звезды есть, значит проект кому-то понравился и пригодился = Мотивация растет
Звезд нет, значит проект никому не нужен = Мотивация падает
Это, в целом, довольно интуитивно: на Инфостарте есть плюсы, на Хабре есть карма, а у уличного музыканта есть аплодисменты. И ожидать, что кто-то будет делать нечто за просто так, да еще и без "Спасибо", довольно странно - дело не в звездах и не в карме, но в том, что они собой олицетворяют
Почему репозитории не находят пользователей?
Из прошлого пункта могло показаться, что я качу бочку на сообщество: мол вы не поддерживаете, вот и не растет. Да, так и есть, до свидания. Нет, на самом деле, огромная часть проблемы находится на стороне разработчиков - это вопрос оформления и продвижения своих разработок
Когда находишь на Github свежие проекты, снова и снова, невольно складывается впечатление, что большинство разработчиков видят себе ведение репозитория примерно вот так ->
Кто-то даже может сказать, что это правильно: большая часть трудозатрат уходит на код, а не на "всякую фигню". Главное же, чтобы софт был хороший, а пользователь, восхищенный задумкой и реализацией, сам должен искать пути, чтобы заполучить столь ценный продукт. Так вот - Нет!
Есть ли в целом право на жизнь у разработки по такой схеме? Вы знаете, да, такое возможно в двух случаях:
- Если вы не хотите, чтобы вашим кодом кто-то пользовался и готовы добиваться этого любой ценой
но бесплатно - Если вы Линус Торвальдс и настолько могучи, что даже имея описание из txt-файла на 300 символов, способны собрать на своем Linux Kernel 150 тыс. +
Если вы кто-то из этих людей, то данная статья не для вас. Я же по умолчанию буду опираться на то, что речь идет о создании проект с нуля и с большой заинтересованностью в его распространении. 1Сный Github - это дикая земля, но благодатная почва, готовая поддержать ваш труд, если приложить к этому достаточно рациональных усилий
Что есть ведение репозитория?
Первое, что надо понять, если вы решили вести свой проект
Посредственный проект, будучи правильно обставленным и обоснованным, станет в сто раз успешнее идеального продукта, разработчик которого так и не удосужился нормально объяснить, кому и зачем он нужен
Можно считать это неправильным, нехорошим или несправедливым - особенно часто встречается аргумент вроде "Я что бесплатно раздаю, чтобы потом еще и пользователей самому искать?". Это ничего не меняет. Создание проекта это даже не в половину про сам исходный код продукта и с этим ничего не поделаешь. Для наглядности, по моему субъективному мнению, правильная диаграмма распределения трудозатрат должна выглядеть примерно вот так ->
Если по пунктам:
- Написание кода, конечно, все еще основной вид деятельности, но точно не "абсолютно превалирующий"
- DevOps - под ним я здесь имею ввиду написание скриптов и другую работу, нацеленную на автоматизацию и упрощение разработки/выпуска релизов
- Под материалами имеется ввиду, в первую очередь, документация. Ну и другие тематические материалы, которые вы под свой проект сможете придумать
- Со статьями и публикациями, думаю, понятно: это всевозможные способы продвижения проекта на различных ресурсах
Если еще проще: половина работы разработка, вторая половина - освещение. Сторону разработки я здесь разбирать не буду - рассматривать мы будем именно освещение, так как репозиторий без кода найти невозможно, а вот без нормального Readme и статей - еще как да. Все стороны данного процесса, конечно, в одну статью не поместятся - сегодня мы разберем лишь подготовку проекта к выходу в свет и его оформление
Readme
Начать стоит с основного описания репозитория и, в частности, Readme файла
Readme файл - это файл, чаще всего формата MD с ограниченной поддержкой HTML, который отображается на главной странице репозитория (любой платформы для хостинга репозиториев, будь то Github, GitLab, Gitflic и пр.) и служит для того, чтобы рассказать пользователю о проекте, на который он только что наткнулся
Существуют разные подходы к созданию подобного файла. Но прежде чем мы перейдем к непосредственному его написанию, нужно обозначить два основных момента, достаточно очевидных, при ближайшем рассмотрении, но не всегда очевидных с самого начала:
- У вас есть очень мало времени, чтобы рассказать пользователю о чем ваш проект. Это не длина всего файла: если пользователь не сможет понять, о чем пойдет речь далее, с первых нескольких строк (либо все описание будет свалено в один громадный пласт текста, который вызывает скуку и отторжение), то с большой долей вероятности он уйдет
Опять же, можно по разному к этому относится: "Ведь это пользователю нужен мой продукт, он бесплатный - я его не продаю". Проблема заключается в том, что большинство пользователей, попадающих в ваш репозиторий, еще не знают, нужен им этот продукт или нет. Тут и обсуждать особо нечего: часто ли вы сами от корки до корки штудируете полное описание всего что есть на портале/лендинге/файле-описании, когда случайно на них попадаете? Репозиторий, в данном случае, ничем не отличается от коммерческого продукта
- Нехватка или плохая подача информации может оттолкнуть даже уже заинтересованного пользователя. Если он не найдет на странице простого и доступного объяснения, что ему прямо сейчас нужно сделать для начала работы, то не будет пользоваться вашим проектом. А возможно не будет, даже если это объяснение есть - просто потому, что оно слишком сложное или неуклюжее
Вы, возможно, захотите сейчас возразить кучей примеров успешных, но абсолютно недружелюбных проектов - эти примеры на фоне нашего (потенциального) проекта будут ошибочны и несправедливы. Apache может в каждом своем новом продукте заставлять меня учить приемы разработки чуждых мне языков программирования, чтобы собирать их релизы из исходников - меня это бесит, но я понимаю, что это огромные проекты с сильным сообществом, именем большой конторы и, зачастую, не имеющие других бесплатных аналогов сопоставимого масштаба. Случайный no-name репозиторий, вышедший позавчера, меня таким заниматься не заставит
Это может показаться несколько однобоко: вот может у вас действительно невероятно амбициозный проект, закрывающий настолько животрепещущую проблему, что пользователи, распихивая друг друга локтями, будут ложить сервера, в попытках заполучить себе его копию. На самом деле, я даже знаю один такой. С той лишь разницей, что он так и не взлетел: при всем уважении к автору и его огромной многолетней работе - работе, задачу которой я из материалов репозитория так и не смог понять, хотя очень хотел. С другой стороны есть, например, OneScript. ИМХО: Попробовал бы ли я его, если бы мне для пробы, в бытии 1С-нику, вместо "Скачайте и установите .msi" предложили бы разбираться в MSBuild и собирать из исходников? Думаю нет
Обвинять же "поколение казуальных недопрограммистов" не желающих ни в чем разбираться и не понимающих "всю прелесть сборки из исходников" можно потом сколько угодно - жаль только, что в одиночестве
Теперь разберем непосредственно создание приветственного файла. Для этого я сделал пример описания некого условного расширения - самой на мой взгляд очевидной формой ведения проекта на 1С, разве что после внешней обработки
По классике, Readme файл разбит на различные блоки: они могут быть разные и в разном порядке, в зависимости от проекта, но костяк должен состоять как минимум из:
- Краткого описания проекта - его сути и решаемых им проблем. Тот самый блок, который должен зацепить пользователя, чтобы он читал дальше
- Развернутого описания, желательно по пунктам, возможностей расширения
- Примеров работы, чтобы дать хотя бы приблизительное понимание пользователю о том, что он будет с вашим продуктом делать после установки
- Варианты поставки (релизов) и способ установки. Желательно с картинками/командами консоли
- Дополнительные блоки о наличии документации, использовании наработок других проектов и пр.
Рассмотрим эти пункты по порядку, а заодно взглянем на некоторые интересные возможности расширенной MD разметки, которые нам доступны:
Краткое описание проекта, как понятно из названия, должно давать пользователю некоторую начальную информацию, чтобы он понял - нужен ему, хотя бы в теории, представленный функционал или нет. Роковая ошибка при написании Readme думать, что при отсутствии краткой и понятной формулировки сути проекта, пользователь полезет глубже дабы узнать, что же там в этом проекте все таки скрывается. Нет, он не полезет. Поэтому, в данном блоке, в одном или нескольких предложениях, обязательно должны быть а) суть реализации б) решаемая проблема или описание функционала, из которого эта проблема и так понятна
# Экспансия
[](https://api.athenaeum.digital/Sonar/dashboard?id=OpenIntegrations)
Расширение для работы с расширениями. Позволяет программно управлять вашими расширениями: получать список расширений, обновлять их и многое другое
Но, как видно, в моем примере есть не только это: еще тут есть лого и значки
Лого - это необязательная, но очень желательная часть описания. Оно создает некоторый брендинг, который мало того, что придает ему профессионального шарма и серьезности, но и создает у пользователя образ вашего проекта не как какого-то "кода на коленке, который выполняет вот эту функцию" но отдельного законченного продукта, к которому доверия и симпатии всегда больше. Короче, основы маркетинга для технарей
Сделать лого и красивый текст не так сложно, как может показаться: я, лично, в работе с графикой сам полный профан, но простого и понятного Paint.NET или Gimp вполне достаточно, чтобы сделать прилично и аккуратно. Для текста я использую сайт textstudio - там вообще ничего даже знать не надо, оно само все сделает
Сюда же можно отнести и название: вы можете назвать свой проект "Расширение для работы с расширениями", но нетрудно представить, как пользователь вашего проекта будет рассказывать о нем другому человеку, и с каким шансом последний после этого его найдет
Значки (бэйджи) - хороший способ дать краткую информацию о вашем проекте, не выделяя для этого очередной блок с длинным нудным текстом. При помощи значков обычно определяют такую информацию как: используемые в проекте технологии, версии этих технологий, ссылки на Telegram-каналы или сайты, ссылки на сторонние ресурсы, где проект представлен. Это функционально, при этом просто, красиво и элегантно
Самый простой способ создания значков - shields.io. Там можно легко создать любые статические значки просто из текста, а также получить различные бэйджи по динамическим данным, например о скачиваниях или последнем релизе в репозитории
После краткой формулировки, обычно идет более широкое описание возможностей проекта. Тут уже можно развернуться и по пунктам расписать какие доступны функции, привести примеры решенных задач и все в этом духе. Это, конечно, не значит, что нужно графоманить 10 экранов сплошного текста - сохранять интерес пользователя необходимо и тут, например используя списки, таблицы или диаграммы
## Возможности расширения
Данное расширение призвано упростить работу с расширениями, управляя процессами их управления прямо из кода 1С, а именно:
- Программно создавать расширения
- Программно удалять расширения
- Программно обновлять расширения
- Программно получать информацию о подключенных расширениях
>[!Important]
> Данное расширение не может работать с данными самого себя
Для красоты тут используется блок с примечанием - Important (важно). Тоже отличный способ разбавлять текст. Помимо самого Important, есть еще примечания типов Note (заметка), Tip (совет), Warning (внимание) и Caution (осторожно). Все они отличаются цветовым выделением
> [!NOTE] > Highlights information that users should take into account, even when skimming. > [!TIP] > Optional information to help a user be more successful. > [!IMPORTANT] > Crucial information necessary for users to succeed. > [!WARNING] > Critical content demanding immediate user attention due to potential risks. > [!CAUTION] > Negative potential consequences of an action.
Далее порядок уже может отличаться: в моем случае следующим идет блок с примерами, но довольно часто его выносят в конец, уже за блок со способом установки. Также данный блок может полностью отсутствовать, если у проекта есть отдельная документация
Применительно к 1С тут намечается два пути: скриншоты, если ваш проект - внешняя обработка или целая конфигурация, нацеленная на работу через интерфейс, и примеры кода, если это расширение с общими модулями, один общий модуль и тому подобное. В моем случае это примеры кода:
## Примеры работы с расширением
Поиск расширения по имени
```bsl
// Возвращает структуру с полями: Имя, Версия, ДатаПодключения, Описание
ДанныеРасширения = ЭКСП_РаботаСРасширениями.ПолучитьРасширение(ИмяРасширения);
```
Получение массив расширений
```bsl
// Возвращает массив структур с полями: Имя, Версия, ДатаПодключения, Описание
РасширенияБазы = ЭКСП_РаботаСРасширениями.ПолучитьРасширенияБазы(ИмяРасширения);
```
Подключение расширения
```bsl
// Возвращает Истина, если расширение было подключено
Подключено = ЭКСП_РаботаСРасширениями.ПодключитьРасширение("C:/Расширение.cfe");
```
Для выделения кода в MD используются блоки, определяемые косыми кавычками - по 3 в начале и в конце. Дополнительно, после начальных кавычек, можно указать режим подсветки синатксиса. В данном случае это bsl, что означает подсветку синтаксиса 1С. С полным списком доступных языков можно ознакомится тут
Способ получения и установки - самый важный, после краткого описания, раздел. Идет в конце только потому, что сначала надо объяснить, зачем что-то вообще получать и устанавливать
Если проект написан на самом 1С, то описывается данный блок максимально просто: практически каждый 1Сник по умолчанию знает, как подключить обработку и расширение, а пользователям других языков данные проект не будет интересен в любом случае. Единственное, что необходимо отметить - получение файлов из релиза, если он есть, или каталог, где начинаются уже непосредственно исходники рабочей части вашего проекта - все таки далеко не все 1С-разработчики уверенные пользователи Git-хостингов и если ваш репозиторий - первый подобный проект в их жизни, то "где скачать" может стать серьезным вопросом
## Релизы и установка
<img src="https://github.com/Bayselonarrend/WorkFlowTest/assets/105596284/2df78e38-10c2-4019-a5e2-1bdb2d7b5e21" align=left width=400>
<br>
Для установки данного расширения достаточно получить `.cfe` файл из последнего релиза, после чего добавить его в список расширений вашей конфигурации. **Минимальная версия 1С - 8.3.9**
<br>
<br>
Абсолютно обратная сторона - это проект для 1С, но не являющийся его реализацией: внешние компоненты, консольные утилиты и пр. Тут наоборот необходима максимальная подробность инструкции, особенно если собирать проект надо из исходников. Хотя вообще лучше позаботиться о бинарниках/установщиках в релизах
Про оформление: картинки можно располагать слева и справа от текста, а также менять их ширину и высоту, если вместо стандартного MD варианта их вставки использовать HTML, как на примере выше. Align (выравнивание) может принимать значения left и right, а width и height - число пикселей ширины и высоты соответственно
В принципе, этого уже будет достаточно, чтобы страница проекта не была закрыта в момент открытия в тех случаях, когда на ваш репозиторий натыкаются не при поиске решения конкретной проблемы, а из общего любопытства, которое источником большинства пользователей и является. В качестве же дополнительных блоков, шире раскрывающих ваш проект, могут выступать:
- Блок с описанием сайта или документации - внешнего источника информации о проекте
- Блок с информацией об использовании разработок из других проектов - как правило хорошего тона
- Список статей и заметок на других ресурсах
- В конце Readme также принято указывать список разработчиков, которые участвуют в проекте, но это не обязательно
И также несколько общих советов:
- Используйте больше картинок и скриншотов
- Разделяйте блоки с текстом, если они слишком больше - больше чем нормальный абзац в 3-4 предложения
- Используйте таблицы и списки там, где идет перечисление однотипных данных
- Следите за обще эстетикой: описание должно быть подробным, но не должно быть похожим на свалку
Полезные ссылки для создания Readme:
- Большой гайд от самого Github на русском
- Простая краткая шпаргалка от Jekins
- Руководство по добавлению интерактивных схем: mermaid, geoJSON и topoJSON
Про общее описание репозитория
Кроме Readme файла, который пользователь видит при заходе в репозиторий, есть еще общее краткое описание проекта, которое используется как на его странице, так и при показе репозитория в каких-либо общих списках, новостных лентах и пр. Оно невелико, но важно, поэтому кратко на нем тоже остановимся
Изменить данное описание можно нажав на шестеренку (видно на скриншоте в правом верхнем углу). В открывшейся форме мы можем заполнить следующие данные:
- Краткое описание - сюда отлично подойдет краткое описание из начала Readme, но желательно добавить еще указание технологии, для которой проект разрабатывается
- Сайт - URL портала или документации, если они есть
- Темы - это набор тэгов, которые позволяют определить проект в различные наборы вместе с другими репозиториями схожей тематики. Выхлопа из этого не очень много - примерно как у использования хэштегов в социальных сетях, но заполнить совсем нетрудно и занимает от силы пару минут, так что лучше все таки этим озаботиться
Также в настройках описания можно включить и отключить различные разделы репозитория: Deployments, Packages, Releases. Они включены по-умолчанию, но если вы их не используете, то лучше отключить, дабы не загромождать боковую панель
Для полноты картины остается только сделать и включить обложку. Она скрыта чуть глубже, уже в основных настройках репозитория (кнопка Settings на верхней панели) на главной их странице:
На примере OpenIntegrations
Обложка, также как и описание, отображается при показе репозитория в различных списках на Github...
...а также как картинка оформления ссылки репозитория, когда ей делятся во всяких социальных сетях или мессендежрах. Как минимум, это красиво и привлекает к себе внимание, что важно
Примеры хороших Readme из мира 1С
Напоследок - примеры хороших Readme из 1С-проектов. Не все они прямо ложатся на шаблон представленного выше примера - но они и не должны. Единственный настоящий критерий качества - красота и понятность. Все остальное лишь методы их достижения
- BITERP/PinkRabbitMQ - как пример не-1С проекта для 1С
- Bayselonarrend/OpenIntegrations - ну еще бы нет :)
- vbondarevsky/Connector - просто добротный человеческий Readme, хотя примеры я бы уже вынес в доки
- vanessa-opensource/add - немного грузный, но и инструмент непростой
- liteappsru/liteExchange - тоже неплохой
В заключение
Публичные репозитории создаются по разным причинам: иногда часть основного проекта в компании решается выложить в открытый доступ, кто-то просто хочет сохранить свой старый код и не против, чтобы им пользовались другие разработчики - к таким случаям вопросов нет
Но я все же склонен считать, что большинство репозиториев, которые мне встречаются, все же являются чей-то персональной инициативой, начиная с "просто хобби", заканчивая неким видом жизненного magnum opus. И в таких случаях для меня очень странно, насколько мало усилий прилагается для того, чтобы эти проекты не просто существовали, но ими еще и кто-то пользовался
Шаги, описанные выше, если и не помогут вам напрямую найти новых "попутчиков" для своего проекта, то, как минимум, очень сильно увеличат шансы заинтересовать тех людей, которые на него уже попали. Не пренебрегайте ими: если цель заключается в том, чтобы сделать "крутой" проект, то игнорирование создания моста между разработчиком и пользователем приведет лишь к грусти и печали, когда написанный код, на который и было потрачено все время работы, окажется никем не востребован и, как следствие, неизбежно брошен
Ну а если вы не мэйнтэйнер, а тот самый пользователь, то не забывайте поддерживать понравившиеся проекты - это очень важно!
Спасибо за внимание!
Если эта статья оказалась полезной, то вас также могут заинтересовать:
Обновляемый список последних статей Инфостарт для профиля Github
Особенности национального Workflow: Github Actions и OneScript
Мой GitHub: https://gitub.com/Bayselonarrend OpenYellow: https://openyellow.notion.site Лицензия MIT: https://mit-license.org
