config: describe the main fields #284

qfox · 2018-02-13T08:07:53Z

qfox · 2018-02-14T00:13:54Z

Vittly · 2018-02-14T08:27:53Z

packages/config/README.md

+
+Field   | Type    | Purpose
+---     | ---     | ---
+root    | `Boolean` | Used to determine the root directory from the current one


Can you explain this? May be with an example

Vittly · 2018-02-14T08:30:29Z

packages/config/README.md

+Field   | Type    | Purpose
+---     | ---     | ---
+root    | `Boolean` | Used to determine the root directory from the current one
+naming  | `string`, `Object` | Name of existing in [`naming.preset`](https://github.com/bem/bem-sdk/tree/master/packages/naming.presets) preset or custom definition


"Name of one of [naming.presets] or custom preset definition" is better for me

Vittly · 2018-02-14T08:32:14Z

packages/config/README.md

+root    | `Boolean` | Used to determine the root directory from the current one
+naming  | `string`, `Object` | Name of existing in [`naming.preset`](https://github.com/bem/bem-sdk/tree/master/packages/naming.presets) preset or custom definition
+levels  | `Array<LevelConf>` | List of known levels in the right order<br> (usually local) with their configurations
+sets    | `Object<string, SetConf>` | Named sets of layers to use in projects


Levels/layers again :) What is layer? Why do we declare levels not layers above?

"to use in projects" > "to build" is better I think

Layer is a property of a level. So we defining all levels but use just some.

Good example with images at methodology will help I think

Vittly · 2018-02-14T08:34:23Z

packages/config/README.md

+levels  | `Array<LevelConf>` | List of known levels in the right order<br> (usually local) with their configurations
+sets    | `Object<string, SetConf>` | Named sets of layers to use in projects
+libs    | `Object<string, LibraryConf>` | Dependency libraries to use in sets
+plugins | `Object<string, PluginConf>` | Various configurations for plugins,<br>can be reached via [`.module`](#module) method


reference "how/where .module is used" to docs or example is required

Vittly · 2018-02-14T08:35:24Z

packages/config/README.md

+
+#### `LevelConf`
+
+Describes level with sources.


level > redefinition level + link to methodology article

Vittly · 2018-02-14T08:36:31Z

packages/config/README.md

+In modern version represents a set of layers relative to library path (`.bemrc` location)
+and depends on naming preset — e.g. `common` and `desktop` for just `bem-components/` (library) path and [`origin`](https://github.com/bem/bem-sdk/blob/master/packages/naming.presets/origin.js) preset.
+
+- `layer` - name of level‘s layer to use in sets


sets > sets option OR SetConf

Vittly · 2018-02-14T08:38:18Z

packages/config/README.md

+Describes level with sources.
+In classic version it represents a directory for a single layer — e.g. `bem-components/common.blocks/` for `common` or `bem-components/desktop.blocks/` for `desktop`.
+In modern version represents a set of layers relative to library path (`.bemrc` location)
+and depends on naming preset — e.g. `common` and `desktop` for just `bem-components/` (library) path and [`origin`](https://github.com/bem/bem-sdk/blob/master/packages/naming.presets/origin.js) preset.


More text is needed. May be example can help or methodology article somewhere in https://en.bem.info/methodology/

Vittly · 2018-02-14T08:39:00Z

packages/config/README.md

+- `layer` - name of level‘s layer to use in sets
+- `naming` - naming preset for this level
+- `path` - optional. required for legacy way, unwanted for the modern one
+- the rest fields will have passed to level config


We need to explain why do someone need other fields

Vittly · 2018-02-14T08:43:48Z

packages/config/README.md

+#### `LibraryConf`
+
+- `path` - to library which should better contain their own `.bemrc` file with their own sets
+- the rest fields will have passed to library config and extend `.bemrc` config found at `${path}/.bemrc`


path - path (repeating is okey) to library. Library should contain its own .bemrc file. If omitted path is evaluated to node_modules/${libraryName} (shorted sentences are more readable)

Vittly · 2018-02-14T08:46:46Z

packages/config/README.md

+
+One of:
+- single string with all used layers; e.g. `'bem-core@ common deskpad desktop'`
+- list of layers and/or libraries and library sets; e.g. `[{library: 'bem-core'}, 'common', 'deskpad', 'desktop']`


please add variant with library and set in one item

actually, if set is undefined then the current one will be used by default.
Not sure how to show it in one sentence

Your definition "if set is undefined then the current one will is used by default" is okey. Write more short sentences

In this version we missed 'bem-core@desktop' and { library: 'bem-core', layer: 'desktop' }

"targets specific layer in library"

tadatuta · 2018-02-15T08:34:11Z

just pushed tiny update

Vittly · 2018-02-15T12:15:00Z

packages/config/README.md

+        .bemrc
+    .bemrc
+```
+and `/projects/prj1/` as current working directory `root` option set to `true` in `/projects/prj1/.bemrc` will prevent `bem-config` to collect data from `/projects/.bemrc` and `/.bemrc`.


Too complicated. We shall to come up with basic process of bem/sdk-config walking file system and collecting bemrc.

Start with more realistic example:

project/ src/ libs/ fooLib/ .bemrc .bemrc

And tell "config of project contains of two .bemrc" and define merge algorithm. After it we can explain things like root-property

Vittly · 2018-02-15T13:35:22Z

packages/config/README.md

+#### `LevelConf`
+
+Describes [redefinition level](https://en.bem.info/methodology/key-concepts/#redefinition-level) with sources — a set of layers relative to library path (`.bemrc` location)
+and depends on naming preset. E.g. `common` and `desktop` for `bem-components/` (library) path and [`origin`](https://github.com/bem/bem-sdk/blob/master/packages/naming.presets/origin.js) preset.


"a set of layers relative to library path (...)" - is very good.

The second part is not. Can we simply add some examples:

{ layer: 'common', path: 'foo/bar' } defines set of one layer with relative path 'foo/bar'
{ layer: 'common' } defines set of layers depending on naming. Relative paths can be 'common.blocks/', 'blocks-common', etc.

Am I right?

You are right.

We want to merge levels into libraries (as it is semantically the same) but @tadatuta worries about classic definition of level.
What you think if we just move this part to the library description with any custom fields?

Vittly · 2018-02-15T13:37:16Z

packages/config/README.md

+Usualy it represents a directory for a single layer — e.g. `bem-components/common.blocks/` for `common` or `bem-components/desktop.blocks/` for `desktop`.
+
+- `layer` - name of level‘s layer to use in `sets` option
+- `naming` - naming preset for this level


What is default value here? Root naming?

Guess, it should be 'origin'. Let's write here about it if no one against

Vittly · 2018-02-15T13:37:33Z

packages/config/README.md

+Field   | Type    | Purpose
+---     | ---     | ---
+root    | `Boolean` | Used to determine the root directory. Configs in parent dirs won't be gathered
+naming  | `string`, `Object` | Name of one of [naming presets](https://github.com/bem/bem-sdk/tree/master/packages/naming.presets) or custom naming definition


And default value?

Vittly · 2018-02-15T13:39:26Z

packages/config/README.md

+- `layer` - name of level‘s layer to use in `sets` option
+- `naming` - naming preset for this level
+- `path` - optional, deprecated. Required for legacy way, unwanted for the modern one
+- the rest fields will be passed to level config (if required by some custom consumer)


Oh, it's deprecated... So example above is bad idea. Can we put properties in a table | Field | Property | Type | ?

Vittly · 2018-02-15T13:40:17Z

packages/config/README.md

+        {
+            "layer": "common",
+            "naming": "origin",
+            "scheme": "nested"


scheme? Is it an example of custom property? Can we add a comment for it?

Vittly · 2018-02-15T13:41:44Z

packages/config/README.md

+
+One of:
+- single string with all used layers; e.g. `'bem-core@ common deskpad desktop'`
+- list of layers and/or libraries and library sets; e.g. `[{library: 'bem-core'}, 'common', 'deskpad', 'desktop']`


In this version we missed 'bem-core@desktop' and { library: 'bem-core', layer: 'desktop' }

Vittly · 2018-02-15T13:42:27Z

packages/config/README.md

+
+#### `LibraryConf`
+
+- `path` - path (repeating is okey) to library. Library should contain its own .bemrc file. If omitted path is evaluated to node_modules/${libraryName}


Please put bemrc and node_modules/... in ticks

Vittly · 2018-02-15T13:42:52Z

packages/config/README.md

+
+#### `PluginConf`
+
+- all the fields will be passed directly to plugins


What plugins? Can we add an example?

Vittly · 2018-02-17T06:12:39Z

packages/config/README.md

+`string|Array<string|{library: string, set?: string}>`
+
+One of:
+- single string with all used layers; e.g. `'bem-core@ common deskpad desktop'`


Mistake. Right form is @bem-core

Vittly · 2018-02-19T05:53:38Z

packages/config/README.md

+#### `LibraryConf`
+
+- `path` - path (repeating is okey) to library. Library should contain its own .bemrc file. If omitted path is evaluated to node_modules/${libraryName}
+- the rest fields will be passed to library config and extend `.bemrc` config found at `${path}/.bemrc`


Seems it is not true. librarySync for example computes cwd from LibraryConf only

Vittly · 2018-03-12T12:55:21Z

I need some extra effort here @tadatuta

qfox · 2018-03-24T21:44:49Z

packages/config/README.md

+---     | ---     | ---
+root    | `Boolean` | Used to determine the root directory. Configs in parent dirs won't be gathered
+naming  | `string`, `Object` | Name of one of [naming presets](https://github.com/bem/bem-sdk/tree/master/packages/naming.presets) or custom naming definition
+levels  | `Array<LevelConf>` | List of known levels in the right order<br> (usually local) with their configurations


Feels like we don't need the difference between levels and libraries — in all cases they are the same.

Let's drop this field in favor of layerOrder: string[] since we need to only to define ordering between layers for now and it's almost useless logic for the most of our users.

If we need to configure some directory (originally levels) with additional fields we should convert them to libraries and define in libs field. path there would start with './' as it does in nodejs's require function so it will be very familiar too.

So:

Dropping levels

Adding layerOrder

Filtering libraries, if need to get local ones (configured "levels")

cc @blond @tadatuta

qfox · 2018-03-24T23:39:15Z

packages/config/README.md

+
+Usualy it represents a directory for a single layer — e.g. `bem-components/common.blocks/` for `common` or `bem-components/desktop.blocks/` for `desktop`.
+
+- `layer` - name of level‘s layer to use in `sets` option


Guess we don't need to write level's here. No one should care about level in new paradigm

level's → semantic

qfox force-pushed the config.describing-bemrc-fields branch from 56a5cff to 4dbb567 Compare February 13, 2018 23:57

qfox changed the title ~~wip~~ config: describe the main fields Feb 13, 2018

qfox force-pushed the config.describing-bemrc-fields branch 2 times, most recently from 8cd14c7 to b2e17ee Compare February 14, 2018 00:10

docs(config): describe the primary set of fields in .bemrc

a7db60f

qfox force-pushed the config.describing-bemrc-fields branch from b2e17ee to a7db60f Compare February 14, 2018 00:11

Vittly requested changes Feb 14, 2018

View reviewed changes

fixup! docs(config): describe the primary set of fields in .bemrc

8213d50

Vittly requested changes Feb 15, 2018

View reviewed changes

Vittly reviewed Feb 17, 2018

View reviewed changes

Vittly reviewed Feb 19, 2018

View reviewed changes

qfox commented Mar 24, 2018

View reviewed changes


		#### `LibraryConf`

		- `path` - path (repeating is okey) to library. Library should contain its own .bemrc file. If omitted path is evaluated to node_modules/${libraryName}


		#### `PluginConf`

		- all the fields will be passed directly to plugins


		Usualy it represents a directory for a single layer — e.g. `bem-components/common.blocks/` for `common` or `bem-components/desktop.blocks/` for `desktop`.

		- `layer` - name of level‘s layer to use in `sets` option

config: describe the main fields #284

Are you sure you want to change the base?

config: describe the main fields #284

Conversation

qfox commented Feb 13, 2018

qfox commented Feb 14, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

qfox Feb 14, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tadatuta commented Feb 15, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Vittly commented Mar 12, 2018

qfox Mar 24, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

qfox Feb 14, 2018 •

edited

Loading

qfox Mar 24, 2018 •

edited

Loading