docs(abstractions): add feature description #78

binjospookie · 2021-03-21T15:08:54Z

close #71

azinit · 2021-03-21T16:12:30Z

@binjospookie пингани (или кинь в чат), как будет готово к ревью

binjospookie · 2021-03-21T16:19:10Z

@martis-git давай считать за преревью)

у меня есть пара вопросов:

надо ли раскрыть ещё какие-то аспекты?
раскрыты ли достаточно описанные аспекты?

azinit · 2021-03-22T00:33:18Z

@binjospookie советую ознакомиться с тем, как это ребята делали примерно)

https://github.com/feature-sliced/wiki/blob/docs/concepts/public-api/concepts/public-api.md
https://github.com/feature-sliced/wiki/blob/docs/concepts/understanding-needs/concepts/understanding-needs.md

azinit

@binjospookie в целом то неплохо, но много что доделать бы еще)

В целом, повторюсь, советую ознакомиться с тем, как это мы с ребятами делали уже (тут прям оч хорошо прослеживаются те правки которые я накидал тебе)
- https://github.com/feature-sliced/wiki/blob/docs/concepts/public-api/concepts/public-api.md
- https://github.com/feature-sliced/wiki/blob/docs/concepts/understanding-needs/concepts/understanding-needs.md
Как минимум то что сразу в глаза бросается - доработать бы в плане структуры и readability для пользователя

Сейчас же хедеров нет и структура не прослеживается
А "подробная инфа", к-рая прям всем-всем пользователям не понадобится - не скрывается в спойлерах
Вот все 11 правок - это только по форме было)
Если же смотреть по тому "чего не хватает содержательно" - то будет еще 20, но для этого как минимум придется еще за тебя работу проделать

Да и ты задолбаешься 30 чужих правок вносить, нежели сам написать сразу полноценно))

Поэтому прошу еще раз пройтись по изначальной дискуссии и посмотреть - какие тезисы там выдвигаются

Пока же, извини, возникает впечатление, что ты из своих ощущений писал больше

UPD: Можно пройтись по ~готовой доке, где тоже "бизнес-ценности" и "функциональность" разбираются

https://github.com/feature-sliced/wiki/blob/docs/concepts/understanding-needs/concepts/understanding-needs.md

azinit · 2021-03-22T00:34:44Z

about/abstraction/feature.md

@@ -0,0 +1,50 @@
+Feature — изменение в продукте, которое несет ценность пользователю.
+


Вынес бы в concepts/abstractions/feature.md

azinit · 2021-03-22T00:35:22Z

about/abstraction/feature.md

@@ -0,0 +1,50 @@
+Feature — изменение в продукте, которое несет ценность пользователю.


Не хватает хедера с overview секцией

Suggested change

Feature — изменение в продукте, которое несет ценность пользователю.

# Feature

## Описание

`feature` — изменение в продукте, которое несет ценность пользователю.

Здесь бы еще описания добавить, глянь как у @karina-drummer сделано)

azinit · 2021-03-22T00:44:01Z

about/abstraction/feature.md

+Рассмотрим некоторые GitHub features:
+
+- issues
+- actions
+- marketplace


Я бы вынес такое отдельным пунктом в ## Примеры

И тогда можно не только про GitHub сказать, но и про YouTube, и да - тот же маркетплейс

В принципе, если этот раздел будет до основного текста - вроде нормально по читаемости и смыслу будет

Тип как "Примеры из жизни"

azinit · 2021-03-22T00:48:59Z

about/abstraction/feature.md

+Features могут перекликаться с другими features. Например, marketplace позволяет найти готовый action, а не писать свой.
+
+Feature может содержать другие features: при создании issue можно проставить labels, assignees, milestone.
+
+Таким образом приходим к следующей структуре:
+
+```
+.
+├── issues/
+│   ├── assignees
+│   ├── labels
+│   └── milestone
+├── actions/
+├── marketplace/
+│   ├── list
+│   ├── search
+│   └── filter
+```
+


Да, понимаю что у тебя была подводка на основании примеров, но надо бы как-то более структурированно разделить и описать что есть фича (более содержательно)

См. как @AlexandrHoroshih сделал

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

Т.е. я бы добавил ее как раскрывающийся спойлер

Про nested-features - по-моему была речь на одном из созвонов, что nested-features у нас как таковых нет, у нас максимум - фичи могут "группироваться" по какой-то доменной зоне (например, условно feature/auth/by-phone, feature/auth/by-oauth и т.д.)

При этом группировка - это значит что просто фичи кладутся в одну папку, НО НЕ БОЛЕЕ

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

├── issues/ │ ├── assignees │ ├── labels │ └── milestone ├── actions/ ├── marketplace/

это же все как раз не фичи, а сущности над которыми и строятся фичи.

Вай нот? Возможность создать issue -- фича. Возможность повесить label на issue -- тоже фича.

создать issue это фича, но issue сами по себе это не фича.
Подобные фичи ведут как раз к необходимости импортить фичи из фич. И как раз эта проблема и привела к появлению такой сущности как entities

Готовые issue — результат создания.

Возможность создания — фича.
Возможность повесть label — фича.

Тот же label несёт пользователю ценность, например, можно указать тип issue.

Вот именно что не сам label несет ценность, а именно возможность повесть лейбл на что-то несет ценность.
В общем я свое мнение по поводу этого писал тут #23 (comment)

Лейбл в контексте issues.

Будь ещё какой-то лейбл, то, да, его частя болталась бы в entities.

Тут больше с @ilyaagarkov соглашусь

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

Я с entities плотно не работал, тож обычно похожим образом на фичи разбивал (labels-list, issue-details и т.д.)

Но похоже на правду - что при разбиении как предлагает @ilyaagarkov и другие ребята (entities + features) - архитектура будет более масштабируемой, читаемой и при этом - сведутся к минимумы необходимости кросс-импортов (а это главный бич сейчас у похожих подходов)

Лейбл в контексте issues.

Будь ещё какой-то лейбл, то, да, его частя болталась бы в entities.

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

Чтобы более плоская структура получалась, и не нужно было вкладывать

Хотя с другой стороны, это уже похоже на проблему nested-entities

@binjospookie @ilyaagarkov можем обсудить попозже в войсе

azinit · 2021-03-22T00:49:44Z

about/abstraction/feature.md

+│   └── filter
+```
+
+Как выглядит feature в реализации?


А вот здесь как раз можно выделить секцию для структуры

## Реализация ...

azinit · 2021-03-22T00:50:25Z

about/abstraction/feature.md

+
+Как выглядит feature в реализации?
+
+Зачастую, это логическая часть и способ взаимодействия с ней.<br />


По-моему хватит просто переноса на след. строку ,без br

azinit · 2021-03-22T00:52:57Z

about/abstraction/feature.md

+Логическая часть = feature `model`. Это место, где описаны правила, по которым существует feature.
+
+Рассмотрим на примере формы аутентификации:
+
+- хранилище значений полей формы (email, password)
+- хранилище валидности формы (ошибки в полях)
+- события обновления хранилищ
+- эффект отправки формы
+
+Этому слою feature не важно как с ним взаимодействует пользователь. Через браузер или через командную строку.
+
+Посредником между пользователем и feature model выступает визульный слой: `UI`


Вот я бы прям на верхнем уровне описал что-то вроде

По реализации `feature` может иметь любые низкоуровневые абстракции (ui, lib, api, model), но чаще всего ограничивается двумя: - `ui/` - логика отображения фичи > Добавляем спойлер с более подробной инфой, который не должен глаза мазолить - `model/` - бизнес-логика фичи > И здесь снова спойлер - сюда бы как раз добавил пункт "Рассмотрим на примере формы аутентификации: ..."

azinit · 2021-03-22T00:53:48Z

about/abstraction/feature.md

+├── feature/
+│   ├── model (logic)
+│   └── ui (visual)
+```


Посмотри как в README сделано примерно

```sh

├── model # Business logic

azinit · 2021-03-22T00:57:38Z

about/abstraction/feature.md

+├── feature/
+│   ├── model (logic)
+│   └── ui (visual)
+```


Не хватает в конце раздела что-то вроде Further Reading (опять же глянь примеры которые кидал выше)

Как минимум добавить ссылка на изначальную дискуссию должна быть

## 📑 См. также  - [*Обсуждение* "Что есть 'feature'?"](https://github.com/feature-sliced/wiki/discussions/23)

От себя бы добавил еще следующие ссылки:

https://ryanlanciaux.com/blog/2017/08/20/a-feature-based-approach-to-react-development/

https://alexmngn.medium.com/why-react-developers-should-modularize-their-applications-d26d381854c1

https://alexmngn.medium.com/how-to-better-organize-your-react-applications-2fd3ea1920f1

https://www.pluralsight.com/guides/how-to-organize-your-react-+-redux-codebase

docs(abstractions): add feature description

1a99609

akaia-shadowfox added the documentation label Mar 21, 2021

akaia-shadowfox assigned binjospookie Mar 21, 2021

akaia-shadowfox added this to the 2.0.0-alpha.1 milestone Mar 21, 2021

azinit requested review from a team, AlexandrHoroshih and akaia-shadowfox and removed request for a team March 22, 2021 00:30

azinit suggested changes Mar 22, 2021

View reviewed changes

azinit mentioned this pull request Mar 22, 2021

feat(layers): Add basic definition of shared #79

Closed

azinit added the help wanted Extra attention is needed label Mar 25, 2021

azinit modified the milestones: Спринт 2021_1, Спринт 2021_2 Apr 5, 2021

sergeysova requested review from azinit, ilyaagarkov and sergeysova April 10, 2021 08:19

azinit removed the help wanted Extra attention is needed label Apr 11, 2021

binjospookie closed this Apr 11, 2021

		@@ -0,0 +1,50 @@
		Feature — изменение в продукте, которое несет ценность пользователю.

-Feature — изменение в продукте, которое несет ценность пользователю.
+# Feature
+## Описание
+`feature` — изменение в продукте, которое несет ценность пользователю.


		Как выглядит feature в реализации?

		Зачастую, это логическая часть и способ взаимодействия с ней.<br />

docs(abstractions): add feature description #78

docs(abstractions): add feature description #78

Uh oh!

Conversation

binjospookie commented Mar 21, 2021

Uh oh!

azinit commented Mar 21, 2021

Uh oh!

binjospookie commented Mar 21, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

azinit commented Mar 22, 2021

Uh oh!

azinit left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

azinit Mar 22, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ilyaagarkov Mar 22, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

binjospookie commented Mar 21, 2021 •

edited

Loading

azinit left a comment •

edited

Loading

azinit Mar 22, 2021 •

edited

Loading

ilyaagarkov Mar 22, 2021 •

edited

Loading