Skip to content

Commit 6dc56c2

Browse files
Artur Yorshmalashkevich
Artur Yorsh
authored and
malashkevich
committed
docs(dev): update DEV_DOCS.md
1 parent 450ab18 commit 6dc56c2

File tree

1 file changed

+276
-9
lines changed

1 file changed

+276
-9
lines changed

‎DEV_DOCS.md

Lines changed: 276 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,284 @@
1-
# Release checklist:
1+
- [Before contributing](#things-you-must-follow-before-contributing)
2+
- [New Feature Checklist](#new-feature-checklist)
3+
- [Docs](#docs)
4+
- [Framework Structure](#framework-structure)
5+
- [Documentation](#documentation)
6+
- [Development](#development)
7+
- [Release](#release)
8+
- [Playground](#playground)
9+
- [Kitten Tricks development](#kitten-tricks-development)
10+
11+
# Things you must follow before contributing
12+
- Don’t overcomplicate
13+
- Don’t make things too abstract
14+
- Use tslint, to check the code style
15+
- Never forget [document your changes add create some examples](#documentation)
16+
- Write tests
17+
- [Create playground components](#creating-playground-components) per each new component/feature
18+
19+
# New Feature Checklist
20+
- lint checks are passing
21+
- tests are added/updated and passing
22+
- showcase in the playground updated
23+
- tsdocs added/updated
24+
- commit message is properly formatted
25+
- for the override styles - registered in a list of overrides
26+
- looks great on all default themes
27+
- requires approval from several core team contributors
28+
29+
# Docs
30+
31+
Docs is a separate Angular application located right in this project in [docs](./docs) folder.
32+
The pages structure is taken from `structure.ts` file.
33+
The components documentation is take from the component comment sections.
34+
35+
# Framework Structure
36+
37+
- docs - Documentation and framework website built on top on the framework
38+
- src
39+
- playground - independent module with runnable examples for each feature
40+
- framework - Framework itself, represents the npm package
41+
42+
## UI Kit
43+
44+
Located in [./src/framework](./src/framework). Divided into two dirs:
45+
46+
- [theme](./src/framework/theme) - Contains styling services and supporting components used to provide styles to basic components.
47+
- [ui](./src/framework/ui) - Contains basic UI components.
48+
49+
## Styling services
50+
51+
Located in [./src/framework/theme](./src/framework/theme)
52+
53+
- [theme](./src/framework/theme/theme) - ThemeProvider component. Used to provide one of Eva themes used to style basic components.
54+
- [mapping](./src/framework/theme/mapping) - MappingProvider component. Used to provide one of Eva mappings to style basic components.
55+
- [style](./src/framework/theme/style) - StyleProvider components. This mixes both Theme- and Mapping- providers to provide usable basic component style object.
56+
- [application](./src/framework/theme/application) - Global ApplicationProvider component. This mixes StyleProvider implementation with Eva processing engine.
57+
58+
### Basic UI components
59+
60+
Located in [./src/framework/ui](./src/framework/ui)
61+
62+
Each component implementation can be found in directory with corresponding name.
63+
64+
#### UI component directory structure:
65+
66+
- `*.component.tsx` - component implementation itself.
67+
- `*.spec.tsx` - component tests.
68+
- `*.spec.tsx.snap` - component test snapshots. This is a generated file. Could be presented or not depending on tests.
69+
70+
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).
71+
72+
73+
# Documentation
74+
75+
Documentation is generated by the custom generator built on top of UI Kit.
76+
You have to use typedoc everywhere for the documentation purpose.
77+
78+
## How to add page to the documentation
79+
80+
Docs application splitted on the sections which you can find in the apps sidebar.
81+
Each section contains some pages.
82+
If you wanna add new page in the documentation, please, open `structure.ts`
83+
file in the root of docs application and add new page in the required section:
84+
85+
```
86+
{
87+
type: 'page',
88+
name: 'Awesom page',
89+
children: [
90+
... blocks
91+
],
92+
},
93+
```
94+
95+
If it's completely new feature, maybe it would be better to create a new section:
96+
97+
```
98+
{
99+
type: 'section',
100+
name: 'New super section',
101+
children: [
102+
... pages
103+
],
104+
},
105+
```
106+
107+
Page can contain multiple blocks of the following types:
108+
109+
- [markdown](#markdown-block)
110+
- [component](#component-block)
111+
- [tabbed component](#tabbed-component-block)
112+
113+
### Markdown block
114+
115+
Renders plain markdown file from the `articles` dir.
116+
For example, if you wanna add getting started article you have to do the following:
117+
118+
- put `getting-started.md` file in the `articles` folder.
119+
- add markdown block to the page children:
120+
121+
```
122+
{
123+
type: 'block',
124+
block: 'markdown',
125+
source: 'getting-started.md',
126+
},
127+
```
128+
129+
### Component block
130+
131+
If you have to render all the information about componend parsed with typedoc
132+
you have to use component blocks:
133+
134+
```
135+
{
136+
type: 'block',
137+
block: 'component',
138+
source: 'MyNewComponentName',
139+
},
140+
```
141+
142+
### Tabbed component block
143+
144+
Tabbed component block will render component description splitted on the following tabs:
145+
- Overview - This is typedoc comment above component
146+
- Theme - Theme variables listed in the typedoc comment above component with `@styles` tag, for example:
147+
148+
```
149+
/**
150+
* ...
151+
*
152+
* @styles
153+
*
154+
* var1
155+
* var2
156+
*
157+
* ...
158+
*/
159+
```
160+
161+
- API - parsing result of the typedoc above public methods and props
162+
- Examples - live examples listed in the typedoc comment above component
163+
164+
## Examples
165+
166+
When you're developing new functionality, please, always add some examples describing it.
167+
You have the following ways to add examples in your component documentation:
168+
- [Add raw code](#add-raw-code)
169+
170+
### Add raw code
171+
172+
If you wan't to describe small thing in two lines of code you can just add something similar in your typedoc comment:
173+
174+
````
175+
```jsx
176+
const AwesomeComponentShowcase = () => (
177+
<AwesomeComponent/>
178+
);
179+
```
180+
````
181+
182+
And don't forget specify language above your example.
183+
184+
## Development
185+
186+
## Create a new component
187+
188+
- create directory in `./src/framework/ui/awesomeComponent` with following files:
189+
````
190+
- awesomeComponent.component.tsx (component file)
191+
- awesomeComponent.spec.tsx (component tests)
192+
````
193+
194+
- create directory in `./src/playground/src/ui/screen/awesomeComponent` with following files:
195+
````
196+
- awesomeComponent.container.tsx (component showcase container)
197+
- awesomeComponentShowcase.component.tsx (basic component showcase)
198+
- type.tsx (component configuration file)
199+
````
200+
201+
Look through already existing showcases and use similar implementation (e.g [Button Showcase](./src/playground/src/ui/screen/button))
202+
203+
- register your showcase in a playground:
204+
205+
Open `./src/playground/src/navigation/navigation.component.tsx` and expand playground navigation with your component container:
206+
```
207+
import {
208+
...
209+
AwesomeComponentContainer,
210+
} from '../ui/screen';
211+
...
212+
[Awesome Component]: AwesomeComponentContainer
213+
```
214+
215+
## Release
216+
217+
0. For major version, search for `@breaking-change` to make sure all breaking changes are covered.
218+
219+
To start a new release (publish the framework packages on NPM) you need:
2220

3221
1. Create a new release branch with template `release/vX.X.X`
4-
2. Update package version in package.json
5222
3. Run tests: `npm run release:validate`
6-
4. Run [docs](docs)
223+
3. MANUALLY update a version in main ./package.json to a new one
224+
4. Generate documentation if needed: `npm run docs:start`
7225
5. Generate changelog: `npm run version:changelog`
8226
6. Fix/expand changelog manually
9-
7. Update [readme](README.md) files if needed
10-
8. Push the branch, create PR, approve, merge
11-
9. Switch to master branch and pull changes
227+
7. Update documentation (e.g [DEV_DOCS.md](./DEV_DOCS.md)) files if needed
228+
8. Push the branch, create PR, approve - merge
229+
9. Pull the upstream (master or other version branch (e.g. 4.0.1, next))
12230
10. Run tests: `npm run release:validate`
13231
11. Assemble build: `npm run release:prepare`
14232
12. Publish the package to npm: `npm run release`
15-
13. Generate public [docs](docs/DEV_DOCS.md)
16-
14. Create and push [git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) with template `(vX.X.X)`
17-
15. Create release on GitHub for the tag
233+
13. Create and push [git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) with template `(vX.X.X)`
234+
14. Create release on GitHub for the tag
235+
236+
# Playground
237+
238+
Playground is an example app built on top of the [Expo](https://github.com/expo/expo) containing runnable component examples.
239+
240+
## Start a Playground
241+
242+
1. Install dependencies if needed with running `npm i` from the repository root
243+
2. `npm run start:pg:prod` to start a playground in a production environment
244+
245+
### Playground environments:
246+
247+
Playground module supports two environments:
248+
- **Production** (Provides Eva Design System module published to npm)
249+
- **Development** (Provides local Eva Design System module)
250+
251+
To run playground in a development mode:
252+
253+
- Clone Eva Design System to the directory containing UI Kitten repo:
254+
```bash
255+
git clone https://github.com/eva-design/eva
256+
```
257+
- Ensure you have the following structure of repos:
258+
```
259+
- /Users/KittenDeveloper/
260+
- react-native-ui-kitten
261+
- eva
262+
```
263+
- Install dependencies if needed and finally run `npm run start:pg:dev`
264+
265+
# Kitten Tricks development
266+
267+
- Clone UI Kitten to the directory containing Kitten Tricks repo:
268+
```bash
269+
git clone https://github.com/akveo/react-native-ui-kitten
270+
```
271+
- Clone Eva Design System to the directory containing Kitten Tricks repo:
272+
```bash
273+
git clone https://github.com/eva-design/eva
274+
```
275+
- Ensure you have the following structure of repos:
276+
```
277+
- /Users/KittenDeveloper/
278+
- react-native-ui-kitten
279+
- eva
280+
- kittenTricks
281+
```
282+
- Inside react-native-ui-kitten dir run `rm -rf ./node_modules ./package-lock.json && npm i` to install latest dependencies.
283+
- Inside Kitten Tricks directory `rm -rf ./node_modules ./package-lock.json && npm i` to install the latest dependencies.
284+
- `npm run start:dev` - this will start application in development mode and watch for UI Kitten and Eva changes.

0 commit comments

Comments
 (0)