1. Предназначение
   1. В чём проблема
   2. Быстрое прототипирование прототипов
   3. Классификатор SoftSpiders
   4. Прототипы SoftSpiders
   5. Классификатор программных решений
   6. Сопутствующие задачи
2. Принципы организации SoftSpiders
   1. С чего начинается разработка
   2. Зачем нужна минималистичность
   3. Иерархия минималистичных прототипов
3. Иерархия прототипов
   1. Свойства и теги
   2. DAG-иерархия
   3. Если кратко
   4. Пример
   5. Текущая реализация
4. Базовые сценарии
   1. Поиск прототипа
   2. Создание прототипа
   3. Декомпозиция сложного прототипа
   4. Создание тега-свойства
5. FAQ
   1. Какие проблемы решает SoftSpiders?
   2. Зачем нужны прототипы?
   3. Почему недостаточно библиотек?
   4. Сохраняется ли авторство у разработчиков прототипов ?
   5. На каких технологиях реализован проект ?
   6. Предполагается ли платное использование сервиса ?
   7. Что делать, если у зависимостей изменяются версии ?
6. Словарь используемых тегов
   1. Правила именования тегов
   2. Теги-синонимы
   3. Зависимости тегов
   4. Эффективные наборы тегов
   5. Пояснения к тегам
7. Текущее состояние проекта
   1. Эволюция и перспективы проекта
   2. Что нужно прямо сейчас
   3. Что потребуется в ближайшее время
8. Приложения
   1. Правила разработки прототипа
   2. Правила оформления README

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

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

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

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

Главная задача проекта SoftSpiders заключается в попытке решения этой проблемы.

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

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

Основой систематизации прототипов служит классификатор SoftSpiders.

Для лучшего понимания механизмов организации классификатора SoftSpiders, сразу стоит отметить, что его содержательными единицами (далее по тексту - элементами) не обязательно должны быть прототипы.

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

Например, элементами классификатора могут быть:

• шаблоны текстовых документов
• кулинарные рецепты (ингредиенты могут выступать свойствами)
• заготовки учебных (и других) планов
• заготовки различных сценариев
• ...

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

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

Какие виды прототипов поддерживает проект ?

В SoftSpiders предполагается поддежка следующих видов программных прототипов:

• проекты-стартеры
• шаблоны (исходники для разнообразных генераторов)
• образовательные проекты - проекты, используемые для обучения/самообучения
• архитектурные решения (шаблоны проектирования, ...)
• алгоритмы
• конфигурации (Webpack, pom, package.json, Travis CI, Docker, ...)
• раскладки (layout) экранов пользовательского интерфейса
• ...

Классификатор SoftSpiders организован как иерархия прототипов, которая снабжена средствами создания, поиска и навигации по иерархии прототипов.

Ниже по тексту иерархию SoftSpiders будем сокращённо называть SS-иерархией, а прототипы SoftSpiders - SS-прототипами.

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

Среди задач, которые призван решать SoftSpiders, можно выделить ещё, как минимум, те, что направлены на обеспечение обмена опытом между разработчиками:

• помощь при самообучении
• фиксация результатов самообучения или результатов разработки в виде новых проектов
• передача знаний при обучении (иерархия качественных программных проектов представляет собой практически готовый учебный материал)

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

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

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

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

В основе SoftSpiders лежит классификатор (далее по тексту - SS-классификатор), элементами которого являются прототипы программ.

При множественном наследовании SS-иерархия может иметь множество корней. В корнях этой иерархии лежат простейшие программы, являющиеся hello-world-программами в самом обычном смысле этого слова: hello-world на Java, hello-world на JavaScript, и т.д.
На следующих уровнях иерархии находятся хоть и более сложные, но, если их рассматривать в контексте свойств своих предков, тоже минималистичные программы.

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

Таким образом в результате выстраивается иерархия минималистичных прототипов с поддержкой множественного наследования свойств (DAG-иерархия).

SS-иерархия выглядит примерно так же, как иерархия классов или интерфейсов в ООП, с поддержкой множественного наследования.

Ключевым понятием SS-классификатора является понятие свойства.

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

Каждому свойству ставится в соответствие уникальный тег (или множество тегов-синонимов), идентифицирующий это свойство.

В контексте SoftSpiders понятия тег и свойство часто взаимозаменяемы. Но есть разница.
В отличие от именования тегов для именования свойств не существует каких-то строгих правил - могут использоваться разные языки, алфавиты, и т.п.

Каждый SS-прототип имеет какой-то определённый набор свойств и помечается соответствующим набором тегов.

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

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

Лучше один раз увидеть, чем сто раз услышать.

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

Пусть прототип A представлен hello-world-программой на Java. Поскольку других свойств прототип A не имеет, то он помечается только тегом java (набором тегов {java}):

Пусть прототип B отличается от прототипа A только тем, что он реализован по стандартам Maven. В соответствии с этим он помечается набором тегов {java, maven}:

Поскольку множество тегов прототипа A ({java}) принадлежит множеству тегов прототипа B ({java, maven}), прототип B является потомком прототипа A.

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

Пусть ещё один прототип C отличается от прототипа A только тем, что вывод сообщений выполняется в нём с помощью библиотеки log4j, и в соответствии с этим он помечается набором тегов {java, log4j}:

Поскольку множество тегов прототипа A ({java}) принадлежит множеству тегов прототипа C ({java, log4j}), прототип C также, как и B, является потомком прототипа A.

Пусть реализован ещё один hello-world-прототип на Java, назовём его D.
Пусть он так же, как B, организован по стандарту Maven и, так же, как C, выводит сообщения с помощью библиотеки log4j.
Тогда в соответствии со своим набором свойств прототип D помечается набором тегов {java, log4j, maven} и согласно вышеуказанным правилам наследования будет одновременно являться непосредственным потомком как прототипа B, так и прототипа C.

В результате прототипы A, B, C и D образуют небольшую DAG-иерархию, в которой прототип D является множественным наследником свойств прототипов B и C.

На данный момент SS-иерархия предварительно реализована при помощи http-ссылок, размещающихся в файлах README.md соответствующих git-репозиториев.

По факту все git-репозитории находятся на GitHub. Пока это рекомендуемая практика, хотя она и не является обязательной.

Рассмотрим базовые сценарии работы с прототипами. К ним относятся:

• Поиск прототипа
• Создание прототипа
• Декомпозиция сложного прототипа
• Создание свойства

Поиск нужного прототипа происходит путём комбинирования фильтрации по тегам и дальнейшей навигации по SS-иерархии.

Замечание: в текущей предварительной реализации используется нестрогая фильтрация на основе тегов GitHub.

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

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

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

В целевой реализации навигация по SS-иерархии предполагает поддержку со стороны соответствующей клиентской программы.
Но в сегодняшней предварительной реализации навигация выполняется при помощи браузера посредством переходов по http-ссылкам Readme-документов прототипов, размещённых на GitHub.

Создание прототипа предполагает следующие этапы:

1. Создание для прототипа git-репозитория (на данный момент рекомендуется использовать GitHub)
2. Разработка прототипа в созданном репозитории согласно несложным правилам
3. Документирование прототипа в файле README.md согласно соответствующим правилам

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

1. Перед тем, как создавать новый тег-свойство, необходимо убедиться, что этот тег отсутствует в словаре.
   При этом необходимо понять, действительно ли речь идёт о добавлении нового свойства или требуется добавить просто новый синоним к одному из существующих тегов-свойств.
2. После того, как необходимость создания нового тега/синонима подтвердилась, нужно подать заявку на расширение словаря тегов простым письмом на адрес [email protected] в письменно-свободной форме (пока так).
3. Дождаться необходимых изменений в словаре тегов или отказа с объяснением причин, если заявку невозможно удовлетворить.

SoftSpiders не решает каких-то фундаментальных проблем, но он упрощает жизнь разработчиков в таких аспектах, как:

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

В первую очередь прототипы нужны для разработки.

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

Но помимо помощи разработчику прототипы SoftSpiders играют также и образовательную роль (см. выше).

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

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

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

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

Да, в разделах описания прототипа присутствует поле Authors.

В данный момент SS-иерархия реализована на основе git-репозиториев, размещаемых на GitHub. Каждый репозиторий содержит ровно один SS-прототип. Ирархические отношения прототипов реализованы при помощи http-ссылок, размещаемых в их readme-документах.

Сам по себе сервис SoftSpider предполагает бесплатное использование.

Существующие на данный момент прототипы разработаны под лицензией MIT и находятся в открытом доступе.

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

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

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

Закрытие репозиториев приватных прототипов не обязательно относится к ссылкам на эти прототипы из других репозиториев.
Так например, если открытый прототип имеет ссылку на закрытый прототип-потомок, то эта ссылка может оставаться видимой.

Каждый прототип создаётся на каком-то определённом наборе библиотек, фреймворков и прочих зависимостей, версии которых так или иначе фиксируются в его исходных конфигурационных файлах (pom.xml, package.json, ...). Если у зависимостей прототипа появляются новые версии, то необязательно что-то предпринимать, поскольку прототип и на старых версиях продолжает сохранять своё главное качество - служить основой для других разработок.
В то же время актуализация прототипа путём поддержки новых версий, конечно, приветствуется.

В случае, если при появлении новых версий у прототипа появляются новые свойства, возможны дополнительные варианты:

• поддержка новых версий с расширением набора свойств прототипа
• создание прототипа-потомка, поддерживающего новый расширенный набор свойств

Проект SoftSpiders имеет собственный словарь тегов, используемых при разметке прототипов.

Ниже приводятся основные правила организации работы с тегами.

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

В дальнейшем возможны некоторые из этих правил могут быть ослаблены.

В скобках словаря тегов указаны теги-синонимы, которые являются его полноценными элементами.

Стрелками '->' в словаре тегов обозначаются теги-зависимости. Использование зависимостей позволяет сокращать разметку прототипов.
То есть, если, например есть в словаре тегов есть зависимости

jersey -> java, rest
rest -> api, http

, то наличие в разметке узла SS-иерархии тега rest означает одновременное наличие там тегов api, http, а наличие тега jersey означает одновременное наличие там тегов java, rest, api, http.
Поэтому вместо подразумеваемого полного - эффективного набора тегов (см. ниже) jersey, java, rest, api, http при разметке прототипов можно и даже рекомендуется использовать только jersey.

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

Граф зависимостей тегов не должен иметь циклов. Поэтому иерархия зависимостей тегов, также как и SS-иерархия, является DAG-иерархией.

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

Например, смысл тега hapi в контексте словаря тегов поясняется таким образом:

hapi -> api, backend, node: небольшой фреймворк, использующийся для разработки web-приложений на NodeJS 

Стоит отметить, что здесь поясняется именно hapi, а не его теги-зависимости: api, backend, node.

Словарь тегов SoftSpiders является изменяемым, как правило, в сторону расширения. Изменения словаря выполняются участниками проекта.

В настоящее время SoftSpiders находится в переходном состоянии от прототипа к MVP.

SoftSpiders имеет несколько проектов-стартеров, некоторые из которых уже сейчас используются сторонними разработчиками. То, что их пока немного, объясняется тем, что до сих пор рост SS-иерархии за редкими исключениями происходил в режиме proof-of-concept, снизу-вверх, что, разумеется, приводило к преимущественному росту её нижних, базовых уровней.

Программная поддержка, автоматизирующая процессы работы с прототипами планируется, но её пока нет, если к таковой не относить используемые возможности GitHub: хостинг SS-репозиториев, поисковик GitHub, организацию связей между прототипами через ссылки README.md и т.п.

Наполнение базы знаний проекта продолжается.
Очевидно, что чем выше будет уровень SS-иерархии, тем большим набором свойств и большей сложностью будут обладать прототипы, тем большей будет стоимость добавления новых свойств, поскольку с ростом числа используемых инструментов будет расти и стоимость решения проблем их совместимости. А значит - тем большую ценность решения SoftSpiders будут иметь для разработчиков.

• Разработка правил для участников проекта - раздела типа How to Contribute, но пока попроще
• Разработка манифеста проекта

• Разработка json-представления для прототипов
• Сайт проекта (в основе статический), который бы включал, как минимум:
  • Систему навигации по SS-иерархии
• Система мотивации участников
  • геймификация
  • рейтинги разработчиков
  • рейтинги прототипов
  • ...

Наполнение базы знаний прототипами - её главным содержанием

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

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

Главный документ SS-прототипа находится в файле README.md, правила оформления которого описаны здесь.

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

Потребность в наличии автотестов обусловлена перспективами развития проекта SoftSpiders. Чем дальше он будет развиваться, тем сложнее будут становиться прототипы, тем труднее будет вручную проверять их работоспособность, особенно, если поток запросов на включение прототипа в SS-классификатор будет большим.

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

Ещё более ценным свойством проекта является ci - подключение средств Continuous Integration для автоматического запуска тестов при поступлении изменений (коммитов) в репозиторий проекта.

На GitHub Continuous Integration поддерживается средствами Travis CI и GitHub Actions.

Файл README.md, находящийся в корневой директории репозитория, является его главным документом.
Он оформляется в синтаксисе markdown (желательно на диалекте GitHub).

Ниже перечисляются правила оформления наиболее часто использующихся разделов README в синтаксисе markdown - в том порядке, в каком они должны следовать в самом документе.

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

Признаком принадлежности репозитория к проекту SoftSpiders является наличие строки 'SOFTSPIDERS' в начале первой строки файла README.md, как здесь:

SOFTSPIDERS
...

Название проекта указывается в заголовоке markdown первого уровня:

# rest-api-java-jersey

Описывает набор тегов-свойств прототипа, например:

## Feature tags

- hooks
- react
- test

В разделе перечисляются авторы прототипа с указанием распределения ролей, если это нужно, например:

## Authors

* [Dennis Kortsch](https://github.com/DennisKo) - original code
* [Alexander Lapygin](https://github.com/AlexanderLapygin) - catching in [Soft Spiders Net](https://github.com/softspider)

При желании автор может перечислить источники, вдохновившие его на создание проекта. Например:

## Inspired by

[An Apollo Server & Client in a yarn Workspace deployed with Zeit 2.0](https://github.com/DennisKo/zeit-now-next-apollo-typescript-example)

В разделе перечисляются, если они есть, ссылки на непосредственные проекты-предки SS-иерархии. Например:

## Direct ancestors

- [Minimal Next in TypeScript](https://github.com/softspider/next-typescript)
- [Zeit Now "HelloWorld" example](https://github.com/softspider/now)

Если у проекта нет предков, раздел не включается в документ.

В разделе перечисляются, если они есть, ссылки на непосредственные проекты-потомки SS-иерархии. Например:

## Direct descendants

- [Minimal Next in TypeScript](https://github.com/softspider/next-typescript)
- [Zeit Now "HelloWorld" example](https://github.com/softspider/now)

Если у проекта нет потомков, раздел не включается в документ.

В разделе перечисляются программные инструменты, которые должны быть установлены на компьютере разработчика, для того, чтобы с проектом можно было работать. При этом указываются только те зависимости, которые не подключаются средствами сборки самого проекта (npm, maven, gradle, ...). Например:

## Requirements

* [*Java 7*](https://www.oracle.com/technetwork/java/javase/downloads/java-archive-downloads-javase7-521261.html)
* [*Apache Maven*](https://maven.apache.org/)
* Some servlet container for deploying and running: [*Apache Tomcat*](http:https://tomcat.apache.org/), [*Jetty*](https://www.eclipse.org/jetty/), ...

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

## Install

'''
yarn
'''

При наличии в прототипе автотестов, в нём указывается команда, которую необходимо выполнить для их запуска. Например:

## Run test

'''
yarn test
'''

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

## Run

'''
yarn start
'''

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

Licensed under the MIT license.