feature-sliced / documentation Goto Github PK

#81 (comment)

@sergeysova
Думаю, каждая задача должна описывать одну конкретную проблему или предложение.
Сейчас здесь куча всего:

• критерии приемки pull requests
• рекомендации по code review
• именование коммитов
• отладка решений по итогам дискуссий
• Предлагаю под каждую такую проблему заводить отдельную задачу.

См. дискуссии: #27, #43

Скорее всего раздел about, но можно и в рут положить

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

— Не можешь сформулировать цель которую будет решать новая фича? А может проблема в том, что сама задача не сформулирована?

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

@sergeysova
Мне хотелось бы добавить это куда-то, но я чёт не представляю в какой раздел это добавить

• feature
• process
• entity
• shared/*

#41

Issue создано для отслеживание процесса написания документации

В #61 - будет описано базово, но нужно расписать подетальней (пока отдельным доком, там потом решим)

См. #14 #31

Директория shared описывает переиспользуемые и разделяемые сущности

В корне проекта создается директория shared, в ней располагаются самые низкоуровневые сущности: api, ui, lib, config.

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

Стоит учитывать, что приложение косвенно полагается на внутреннюю реализацию shared модулей, так как расчитывает на конкретное поведение

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

См. дискуссии: #16

Сократить доку и вынести в src/blog и т.п.

• убираем спойлеры (по максимуму, где можем),
• личный опыт и лишние моменты в отдельную директорию (скорее всего src/blogs),
• убираем чрезмерную вложенность,
• по-возможности - упрощаем структуру
• [optional] Если успеешь - "подчистить" от лишних эмоц. оттенков, просторечий доку (как и хотела)

  И в целом по "негативно-цепляющим" формулировкам можешь пройтись если успеешь, но некритично

UPD: Подзадачи

@karina-drummer

Возможно все покрыть в рамках спринта не удастся

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

Чтобы можно было перераспределить ресурсы на след. неделе

Проработать директории:

• about

  Без /old/feature-driven

• concepts
• intro

Т.е. крайне важно достичь двух целей этой задачей:

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

Пример: /src/blog/readme.md

 ## Абстракции
(инфа из спойлера раз)

(инфа из спойлера два)

...

---

 ## Разбиение приложения

прочая инфа раз

...

• Нужно определиться с составом core-members
• Нужно понять как внедрить команду и реализовать ее

Пофиксить доку: нужно убрать по-максимуму innerHTML врезки в md-файлах

• Если будут где-то затыки - можно написать в чат
  Если же и так не разберемся - оставим как "эдж-кейс"

• При этом игнорируем пока спойлеры (<details>...</details>), т.к. @karina-drummer их и так уберет по своей задаче (#103)

• Можно воспользоваться плагинами из списка для удобства
  (для линтинга и отображения доки в github превью)
  (там как раз подсвечивается innerHTML)

UPD: Подзадачи

@OlegBrony

Возможно все покрыть в рамках спринта не удастся

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

Чтобы можно было перераспределить ресурсы на след. неделе

Проработать директории:

• about

  Без /old/feature-driven

• concepts
• intro

Было бы вообще, если бы настроил в CI или eslint линтование markdown, но пофиг - пусть пока будет как будет

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

Возможно в РИДМИ, или какую-то доку

• "feature-sliced architecture" (тг чат по обсуждению методологии)
• YouTube канал (который либо создать бы, либо переименовать старый
• Возможно, упоминание основных мейнтейнеров в эту же доку (чтоб можно было в PR упоминать да и в целом знать)
  • Сюда же можно наверн блог @sergeysova в тг (хотя мб уже лишнее будет)

Пришла мысль - сформировать облако слов

• Из недавних сообщений в core-team

  @karina-drummer
  @sovasergey можно ли processes назвать сервисами? 🤔
  Как в systemd, раз уж сравнения с ОС

  @sergeysova
  нет
  я заметил тенденцию, что сервисом называет сущность
  которая может быть прибита к апи
  вот скорее entities можно назвать сервисом
  чем processes

• А также исходя из бурных дискуссий по неймингу абстракций

Зачем?

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

• Чтобы более явно видеть наиболее популярные варианты для сопоставлений:

  Например

  • API requests: api, services, requests, queries, ...
  • UI logic: ui, components, ...
  • Business logic: models, store, state, ...
  • Infrastructure common used logic: shared, common, lib, core, general, ...
  • App init logic: app, core, ...
  • (и т.д.)

• Мы видим нашу цель, как баланс между идеологией и простотой
• Мы не сможем сделать серебряную пулю, которая подходит всем

Не выйдет

• Очень просто
• Очень понятно
• Для всех

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

Возможны

• Простота
• Расширяемость

Цели

• Широкий круг разработчиков
• Понятность

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

Наша цель это найти способ доступно объяснить причины наших решений и выдать инструментарий (документация, cli, линтеры) разработчикам, чтобы они избегали проблем, с которыми ещё не сталкивались

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

https://www.notion.so/Frontend-Architecture-2aee8b123a2540958526419267cf7b32

Зачем?

• По многочисленным заявкам...
• Да и в целом, чтоб было понятно на чем зиждется наш подход, и как в нем применяются те или иные паттерны

Какие связи, GRASP применение и т.д.

А тут можно вообще MVC притянуть

Overview - секция с базовым прогоном по методологии и описанием "а что здесь есть"

Overview/Concepts - подсекция, объясняющая ключевые концепции методологии, о которых точно надо знать "при первом приближении", и которые больше раскроют философию методологии

Content

На свой вкус, но описал здесь свое мнение

Имхо должно быть про Public API, Isolation - и возможно что-то еще

Но не слишком подробно - ибо у нас отдельные статьи есть на это (а некоторые "в планах")

Дополнительно

• Максимально заинтересовать целевого читателя, чтобы он пошел дальше

  • Он должен понять - что методология решает его проблему
  • Т.е. мы должны нашим ридми - "продать методологию", а потом уже погружаться в детали

• По возможности - переиспользовать/доработать то что уже есть

• По возможности и необходимости - референсится на имеющиеся статьи в доке

Материалы для задачи

• Глянь текущие дискуссии (мб что выцепишь)
• Глянь папку /concepts/ в нашей текущей доке (многое оттуда пойдет, но можешь и отсеять, оставив "ключевое"
• Можешь глянуть "Требования к архитектуре" - мб там тоже что-то выцепить можно

• Документация по неймингу сущностей
• Документация по философии нарезки

Старое описание

Нужно базово расписать

• какие абстракции должны быть в методологии
• нейминг
  См. дискуссии: #31, #20

Оч подробно писать не надо, т.к. для shared (#70) и для feature (#71) будут отдельные доки (потом смержим если надо)

Нужно добавить доку "Что есть фича" согласно методологии

Базово будет описано по задаче #61 , а здесь же - надо написать чуть подробнее

См. дискуссии: #23

UPD:

See also - секция с перечислением доп. материала и инфы для читателя "напоследок", на случай:

• Если он хочет больше изучить по теме (можно на статьи из доки и не только)
• Если он хочет помочь проекту или узнать больше "Напоследок"-инфы

Content

На свой вкус, но описал здесь свое мнение

• Из старой feature-driven доки
• Оставить ссылки только на важные статьи
• Оставить инфу про контрибьютинг + помощь
• Возможно, оставить важные комьюнити ссылки (#45 )

Дополнительно

• Максимально заинтересовать целевого читателя, чтобы он пошел дальше

  • Он должен понять - что методология решает его проблему
  • Т.е. мы должны нашим ридми - "продать методологию", а потом уже погружаться в детали

• По возможности - переиспользовать/доработать то что уже есть

• По возможности и необходимости - референсится на имеющиеся статьи в доке

Найти способ, добавлять динамически "ревьюверов на этой неделе"

Пока приходит только идея создать отдельную тиму "duty-reviewers" и выборку из людей-ревьюверов делать именно из них
Только каждую неделю тиму саму обновлять
Но как будто можно получше как-то...

@karina-drummer
ткнула на ссылочку "💫 Ознакомьтесь с нашим contributing гайдом"

Описать базово наши "хотелки"

Да, хочется поддерживать эту методологию и дальше как OpenSource решение

Но поскольку и члены core-team где-то работают, параллельно применяя накопленный опыт и развивая параллельно методологию - нужно решить значимый вопрос по лицензии

Т.е. условно работает человек M из core-team в компании MMM. Само собой, полученный опыт - выливается и в методологию - хоть может и не в рабочее время. Порой, этот M даже применяет методологию в самой компании MMM, обсуждает архитектурные вопросы с командой и т.п. (что возможно тоже пойдет в саму методологию, а не ее "форк" для компании и конкретных проектов)

Спустя какое-то время, если компания MMM очень жадна до прав - то она может потребовать/подать иск, чтобы за ней признали право на владение методологией (в случае же донатов - может быть и что-то еще)

Не хочется повторять историю nginx, поэтому хотелось бы - разрулить этот вопрос как можно раньше

@karina-drummer

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

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

• @karina-drummer
• @sergeysova
• @martis-git
• @ilyaagarkov
• @AlexandrHoroshih
• @binjospookie
• @OlegBrony

https://documentation.divio.com/

См. дискуссии: #41

Каждая сущность методологии должна иметь Public API

Импортировать содержимое сущности игнорируя Public API запрещено!

• feature
• process
• entity
• shared/*

Issue создано для отслеживание процесса написания документации

UPD: Поменялись ролями - теперь:

• Сама дока: @martis-git
• Тотальное ревью: @sergeysova + дежурные ревьюверы
  Чтобы "была вторая точка зрения по этой секции"

Head-description - pre-section перед остальными секциями

Content

На свой вкус, но перечисляю то - что точно должно быть "где-то" в head-description

• Предупреждение, что работа в процессе и лучше пока не юзать в проде
• Базовое описание в head-секции
• (Если успеешь) Визуальная схема по методологии
  • Предлагали торт / ту схему из чатика
  • Лучше статичную (с анимацией и гифками возможны проблемы)

Дополнительно

• Максимально заинтересовать целевого читателя, чтобы он пошел дальше
  • Он должен понять - что методология решает его проблему
  • Т.е. мы должны нашим ридми (и особенно head-description) - "продать методологию", а потом уже погружаться в детали
• По возможности - переиспользовать/доработать то что уже есть
• По возможности и необходимости - референсится на имеющиеся статьи в доке

• https://gist.github.com/sergeysova/9f6dc24e21efe5f5bb4f9878216c2ce9

TL;DR:

• Старайтесь называть абстракции по принципу "от общего к частному"
  
  
  

Опционально

Можете использовать такой подход везде, но методология не обязывает

- handleClick
+ clickHandle

- api.getUsers()
+ api.usersGet()

Details

TODO:

Что нельзя импортит одну фичу из другой, то же про entity и т.д.

Если получится приправить своим опытом и дискуссиями (#49) - будет вообще круто

Overview - секция с базовым прогоном по методологии и описанием "а что здесь есть"

Более подробно чем head-section, но менее чем остальная дока

Все - чтобы "продать" целевому читателю методологию

Content

Идея методологии, базовое описание

Дополнительно

• Максимально заинтересовать целевого читателя, чтобы он пошел дальше

  • Он должен понять - что методология решает его проблему
  • Т.е. мы должны нашим ридми - "продать методологию", а потом уже погружаться в детали

• По возможности - переиспользовать/доработать то что уже есть

• По возможности и необходимости - референсится на имеющиеся статьи в доке

Методология должна в том числе и показывать "как делать плохо"

Как по мне, надо явно сравнить с имеющимися фреймворками и понять преимущества и недостатки

• Чем не заходит Ангуляр?
• Чем не заходит feature-u?
• Чем не заходит https://www.eclipse.org/?
• и т.д.

См. дискуссию #56

Чтобы не затерялось

Overview - секция с базовым прогоном по методологии и описанием "а что здесь есть"

Overview/Motivation - подсекция, объясняющая то, почему была создана методология, какие ее цели, какие были проблемы которые методология была призвана решить методология

Content

На свой вкус, но описал здесь свое мнение

Проблемы, причины, цели, "задумка" и т.п.

Дополнительно

• Максимально заинтересовать целевого читателя, чтобы он пошел дальше

  • Он должен понять - что методология решает его проблему
  • Т.е. мы должны нашим ридми - "продать методологию", а потом уже погружаться в детали

• По возможности - переиспользовать/доработать то что уже есть

• По возможности и необходимости - референсится на имеющиеся статьи в доке

Материалы для задачи

Все это - опционально, на твой вкус - но лучше бы ознакомиться и выцепить оттуда что-то (тебе же проще будет)

• Дока по "мотивации"

  Можешь ее просто "ужать" до уровня ридми

• Дискуссия "Нужна ли методология?"

  На основе нее создавалась дока - но можешь ознакомиться тож, если будет возможность

• Дока "О методологии" (включая цели и проблемы)
• Да и в целом можешь глянуть, как в других либах/решениях раздел Motivation расписан

• старые доки вынести в old
• "причесать" основной README

Related: #45

• Dev.to
• Twitter
• YouTube

• Добавить как требование для PR минимум аппрув от 2 ревьюверов (позже потом разрулим согласно зона ответственности уже наверн)

UPD:

Надзадачи: #105 , #103

• Согласно diataxis
• Оставить feature-driven только в конкретной ветке
• Убрать лишние папки

Примеры:

• https://vuex.vuejs.org/#what-is-a-state-management-pattern
• https://effector.dev/docs/introduction/core-concepts/
• https://github.com/Flipper-Zero/docs/
• https://github.com/tannerlinsley/react-query/tree/master/docs
• https://github.com/facebook/react/tree/master/packages/shared
• https://github.com/graphql/graphql-js/tree/main/docs
• https://github.com/apollographql/apollo-client/tree/main/docs
• https://github.com/mobxjs/mobx/tree/main/docs
• https://github.com/vuejs/docs-next
• https://github.com/reduxjs/redux/tree/master/docs

Пока что же выглядит таким образом

#10

Взять рассуждения @sergeysova из чата

https://github.com/feature-sliced/wiki/blob/master/about/history.md

О том как развивалась, исходя из каких проблем, какие этапы преодолевала и т.д

Чтобы было графическое представление абстракций (#61 , #29)

Обсуждали на стриме

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

Content

На свой вкус, но описал здесь свое мнение

• Прямая вставка со структурой (см. как здесь)
• Фрагменты из твоего MVP в сжатом виде (сам же вроде как и хотел)
• Немного про "слайсинг" проекта

Дополнительно

• Максимально заинтересовать целевого читателя, чтобы он пошел дальше

  • Он должен понять - что методология решает его проблему
  • Т.е. мы должны нашим ридми - "продать методологию", а потом уже погружаться в детали

• По возможности - переиспользовать/доработать то что уже есть

• По возможности и необходимости - референсится на имеющиеся статьи в доке

Материалы для задачи

Как минимум нижеперечисленное, но можешь себя не ограничивать

• Твой MVP
• Дока про абстракции
• Дока про слайсинг