docs(dev): update DEV_DOCS.md

DEV_DOCS.md

@@ -1,17 +1,284 @@
-# Release checklist:
+- [Before contributing](#things-you-must-follow-before-contributing)
+- [New Feature Checklist](#new-feature-checklist)
+- [Docs](#docs)
+- [Framework Structure](#framework-structure)
+- [Documentation](#documentation)
+- [Development](#development)
+- [Release](#release)
+- [Playground](#playground)
+- [Kitten Tricks development](#kitten-tricks-development)
+
+# Things you must follow before contributing
+- Don’t overcomplicate
+- Don’t make things too abstract
+- Use tslint, to check the code style
+- Never forget [document your changes add create some examples](#documentation)
+- Write tests
+- [Create playground components](#creating-playground-components) per each new component/feature
+
+# New Feature Checklist
+- lint checks are passing
+- tests are added/updated and passing
+- showcase in the playground updated
+- tsdocs added/updated
+- commit message is properly formatted
+- for the override styles - registered in a list of overrides
+- looks great on all default themes
+- requires approval from several core team contributors
+
+# Docs
+
+Docs is a separate Angular application located right in this project in [docs](./docs) folder.
+The pages structure is taken from `structure.ts` file.
+The components documentation is take from the component comment sections. 
+
+# Framework Structure
+
+- docs - Documentation and framework website built on top on the framework
+- src
+    - playground - independent module with runnable examples for each feature
+    - framework - Framework itself, represents the npm package     
+
+## UI Kit 
+
+Located in [./src/framework](./src/framework). Divided into two dirs:
+
+- [theme](./src/framework/theme) - Contains styling services and supporting components used to provide styles to basic components.
+- [ui](./src/framework/ui) - Contains basic UI components.
+
+## Styling services
+
+Located in [./src/framework/theme](./src/framework/theme)
+
+- [theme](./src/framework/theme/theme) - ThemeProvider component. Used to provide one of Eva themes used to style basic components.
+- [mapping](./src/framework/theme/mapping) - MappingProvider component. Used to provide one of Eva mappings to style basic components.
+- [style](./src/framework/theme/style) - StyleProvider components. This mixes both Theme- and Mapping- providers to provide usable basic component style object.
+- [application](./src/framework/theme/application) - Global ApplicationProvider component. This mixes StyleProvider implementation with Eva processing engine.
+
+### Basic UI components
+
+Located in [./src/framework/ui](./src/framework/ui)
+
+Each component implementation can be found in directory with corresponding name.
+
+#### UI component directory structure:
+
+- `*.component.tsx` - component implementation itself.
+- `*.spec.tsx` - component tests.
+- `*.spec.tsx.snap` - component test snapshots. This is a generated file. Could be presented or not depending on tests.
+
+Some of components can have more complex implementation. In this case the final component implementation could be divided into sub-components, but tests should be written in a single `*.spec` file. The good example is [TabView](./src/framework/ui/tab). 
+
+
+# Documentation
+
+Documentation is generated by the custom generator built on top of UI Kit.
+You have to use typedoc everywhere for the documentation purpose.
+
+## How to add page to the documentation
+
+Docs application splitted on the sections which you can find in the apps sidebar.
+Each section contains some pages.
+If you wanna add new page in the documentation, please, open `structure.ts`
+file in the root of docs application and add new page in the required section:
+
+```
+{
+  type: 'page',
+  name: 'Awesom page',
+  children: [
+    ... blocks
+  ],
+},
+```
+
+If it's completely new feature, maybe it would be better to create a new section:
+
+```
+{
+  type: 'section',
+  name: 'New super section',
+  children: [
+    ... pages
+  ],
+},
+```
+
+Page can contain multiple blocks of the following types:
+
+- [markdown](#markdown-block)
+- [component](#component-block)
+- [tabbed component](#tabbed-component-block)
+
+### Markdown block
+
+Renders plain markdown file from the `articles` dir.
+For example, if you wanna add getting started article you have to do the following:
+
+- put `getting-started.md` file in the `articles` folder.
+- add markdown block to the page children:
+
+```
+{
+  type: 'block',
+  block: 'markdown',
+  source: 'getting-started.md',
+},
+```
+
+### Component block
+
+If you have to render all the information about componend parsed with typedoc
+you have to use component blocks:
+
+```
+{
+  type: 'block',
+  block: 'component',
+  source: 'MyNewComponentName',
+},
+```
+
+### Tabbed component block
+
+Tabbed component block will render component description splitted on the following tabs:
+- Overview - This is typedoc comment above component
+- Theme - Theme variables listed in the typedoc comment above component with `@styles` tag, for example:
+
+```
+/**
+ * ...
+ *
+ * @styles
+ *
+ * var1
+ * var2
+ *
+ * ...
+ */
+```
+
+- API - parsing result of the typedoc above public methods and props
+- Examples - live examples listed in the typedoc comment above component
+
+## Examples
+
+When you're developing new functionality, please, always add some examples describing it.
+You have the following ways to add examples in your component documentation:
+- [Add raw code](#add-raw-code)
+
+### Add raw code
+
+If you wan't to describe small thing in two lines of code you can just add something similar in your typedoc comment:
+
+````
+```jsx
+const AwesomeComponentShowcase = () => (
+  <AwesomeComponent/>
+);
+```
+````
+
+And don't forget specify language above your example.
+
+## Development
+
+## Create a new component
+
+- create directory in `./src/framework/ui/awesomeComponent` with following files:
+````
+- awesomeComponent.component.tsx (component file)
+- awesomeComponent.spec.tsx (component tests)
+````
+
+- create directory in `./src/playground/src/ui/screen/awesomeComponent` with following files:
+````
+- awesomeComponent.container.tsx (component showcase container)
+- awesomeComponentShowcase.component.tsx (basic component showcase)
+- type.tsx (component configuration file)
+````
+
+Look through already existing showcases and use similar implementation (e.g [Button Showcase](./src/playground/src/ui/screen/button))
+
+- register your showcase in a playground: 
+
+Open `./src/playground/src/navigation/navigation.component.tsx` and expand playground navigation with your component container:
+```
+import {
+  ...
+  AwesomeComponentContainer,
+} from '../ui/screen';
+...
+[Awesome Component]: AwesomeComponentContainer
+```
+
+## Release
+
+0. For major version, search for `@breaking-change` to make sure all breaking changes are covered.
+
+To start a new release (publish the framework packages on NPM) you need:
 
 1. Create a new release branch with template `release/vX.X.X`
-2. Update package version in package.json
 3. Run tests: `npm run release:validate`
-4. Run [docs](docs)
+3. MANUALLY update a version in main ./package.json to a new one
+4. Generate documentation if needed: `npm run docs:start`
 5. Generate changelog: `npm run version:changelog`
 6. Fix/expand changelog manually
-7. Update [readme](README.md) files if needed
-8. Push the branch, create PR, approve, merge
-9. Switch to master branch and pull changes
+7. Update documentation (e.g [DEV_DOCS.md](./DEV_DOCS.md)) files if needed
+8. Push the branch, create PR, approve - merge
+9. Pull the upstream (master or other version branch (e.g. 4.0.1, next))   
 10. Run tests: `npm run release:validate`
 11. Assemble build: `npm run release:prepare`
 12. Publish the package to npm: `npm run release`
-13. Generate public [docs](docs/DEV_DOCS.md)
-14. Create and push [git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) with template `(vX.X.X)`
-15. Create release on GitHub for the tag
+13. Create and push [git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) with template `(vX.X.X)`
+14. Create release on GitHub for the tag
+
+# Playground
+
+Playground is an example app built on top of the [Expo](https://github.com/expo/expo) containing runnable component examples.
+
+## Start a Playground
+
+1. Install dependencies if needed with running `npm i` from the repository root
+2. `npm run start:pg:prod` to start a playground in a production environment
+
+### Playground environments:
+
+Playground module supports two environments: 
+- **Production** (Provides Eva Design System module published to npm)
+- **Development** (Provides local Eva Design System module)
+
+To run playground in a development mode:
+
+- Clone Eva Design System to the directory containing UI Kitten repo:
+```bash
+git clone https://github.com/eva-design/eva
+```
+- Ensure you have the following structure of repos:
+```
+- /Users/KittenDeveloper/
+  - react-native-ui-kitten
+  - eva
+```
+- Install dependencies if needed and finally run `npm run start:pg:dev`
+
+# Kitten Tricks development
+
+- Clone UI Kitten to the directory containing Kitten Tricks repo:
+```bash
+git clone https://github.com/akveo/react-native-ui-kitten
+```
+- Clone Eva Design System to the directory containing Kitten Tricks repo:
+```bash
+git clone https://github.com/eva-design/eva
+```
+- Ensure you have the following structure of repos:
+```
+- /Users/KittenDeveloper/
+  - react-native-ui-kitten
+  - eva
+  - kittenTricks
+```
+- Inside react-native-ui-kitten dir run `rm -rf ./node_modules ./package-lock.json && npm i` to install latest dependencies.
+- Inside Kitten Tricks directory `rm -rf ./node_modules ./package-lock.json && npm i` to install the latest dependencies.
+- `npm run start:dev` - this will start application in development mode and watch for UI Kitten and Eva changes.