# Contributing to ux.ui-community
Contributions to this collection of components are welcome, but should follow our guidelines.
## Process for new components/changes
1. __Create an issue__ in gitlab.com and attach the RFC-label (Request For Comments) - small bugfixes may also be created without RFC. The issue should describe the planned component and all its subcomponents and also their API (Props/Events). If you need third-party libraries list them with links to their github. More infos about third-party libraries below.
2. The issue will be discussed and has to be __approved__ by 2 "Main-Contributors" (Chris Ungur, Jannik Lassahn, David Randler, Tommaso De Marco, Jan Massberg) - this is indicated with a "Thumbs up" on the issue. Then the Approved-label will be added to the issue.
3. Development in a new branch can be started. Always create the __new branch from master__ it should be called feature/*feature-name* or bugfix/*bug-name*.
4. After development a __Merge Request__ from your branch to master has to be created. 2 Main Contributors will give comments / approve the Merge Request and merge it to master. Then they will release a new version of the npm package.
## Naming conventions
All names, comments and examples should be in __English__ language.
* All components have to be named with this prefix for their __tag-name__ and __CSS class-name__: `uic-`.
* All __Events__ have to use the prefix `uic` and when possible the name of the component.
* __Files and folders__ have to be lowercase, words are separated with `-`. We do not use the `uic`-prefix in component folder names.
## File structure
Components are placed in `/src/components` in individual directories that use the component name (without prefix).
A component directory typically contains the following type of files (for this example we use search-field):
* `search-field.tsx` the stencil component
* `search-field.scss` the styles for the component
* `search-field.e2e.ts` optional stencil E2E test
* `search-field.spec.ts` optional stencil spec test
* ...
Utilities are placed in `/src/utils`. Test files should be named like the file where the source code is located.
Stories are placed in `/stories/02-web-compoments`. The MDX-syntax is preferred (More on that: see Coding Guidelines below). If you need example files for your stories, you can place them in `/resources`.
## Coding Guidelines
The project contains ESlint, StyleLint, prettier and .editorconfig files to help with a common codestyle. Every time a developer does a `git commit`, a pre-commit hook is executed that checks and fixes code style errors.
### Styles
For compatibility reasons (IE11) we do __not use ShadowDOM__. Exceptions should be discussed in a gitlab issue and if ShadowDOM is used it has to be documented in the story. All Styles should be placed in SCSS files (except dynamic styles).
All Styles have to be scoped to a classname with the `uic-` prefix. All classnames have to conform to the [BEM naming conventions](http://getbem.com/naming/).
Components in this project can use CSS variables to make them themeable for different Environments. The variable declaration should be done in `src/sass/themes/default` - in separate files per component. The declarations should be done under the classname `.uic-theme-responsive`. In the future we might add another theme directory next to default to also support other styleguides than the responsive styleguide. In your component SCSS please document the CSS-vars you used (example: `/** @prop --uic-dialog-backdrop-color: color of the overlay background / backdrop. Use rgba to achieve opacity. */`). This will generate a section about the used CSS Custom Properties in the Documentation, that will be visible on the story page of the component.
### TypeScript
Use documentation comments to describe all Props, Events and Slots. Those will be used in the automatically generated Documentation. We recommend to write automated tests where it is possible - see [Stencil Testing Guide](https://stenciljs.com/docs/testing-overview)
### Stories
Create a story for each component and also for variants of components. One MDX file may contain multiple stories (for example a component with multiple variants). MDX Files use a syntax that is similar to Markdown, but with JS/JSX support. Ensure to always leave one empty line between Markdown and JS/JSX content. Note that you will need to use the `html`-helper from "lit-html" to write stories with web-components. [lit-html Syntax reference](https://lit-html.polymer-project.org/guide/template-reference)
Example for lit-html syntax in a story:
```
{html`
{[1, 2, 3].map(number => html`Item ${number}`)}
`}
```
Import the documentation (Readme) that is automatically generated by stencil. Include the readme like this: `` at the end of the MDX file.
## Third Party libraries
if you need a third party library, you need to consider the following guidelines:
| Criteria | Definition | Threshold | importance (1=least, 5=most important) | comment |
| -------- | ---------- | --------- | -------------------------------------- | ------- |
| Wide usage | Minimum number of weekly downloads at npm | 10.000 | 2 | Can be seen at npm page of a package. Example: https://www.npmjs.com/package/@stencil/core |
| Active maintenance | Last release date | not older than 3 months | 2 | Can be seen at npm page of a package as "Last publish". |
| Active maintenance | Last commit | not older than 2 weeks | 1 | Can be checked only, if a public repository is available. |
| Active maintenance | Minimum number of contributors: | 3 | 5 | |
| License type | License is in this whitelist: | MIT, BSD, Apache, ISC | 5 | License of a package and it's dependencies can be checked with https://www.npmjs.com/package/license-checker |
| Clear documentation | Documentation is available and describes well the usage of a package | Documentation exists | 4 | Documentation can be present as a fully descriptive website for a bigger packages, or it can be well prepared README.md for a smaller. |
| Security | The packages itself and it's dependencies show 0 vulnerabilities with npm audit | 0 | 4 | |
| Stability | used version is stable | Stable | 3 | No alpha, beta, RCs are allowed. |
| Maintenance | Easily exchangeable | | 2 | Will it be possible to replace a library with another one without need to make a changes across the code |
| Maintenance | Doesn't pollute the global scope | | 3 | No global CSS styles are defined |
Those criterias should be seen as basis for discussion about new dependencies.