# 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 stable version of the npm package. Unstable versions of the npm package are published automatically for every commit on master and on Merge Requests: `npm i @trumpf/ux.ui-community@master` or `npm i @trumpf/ux.ui-community@feature-my-branch`.
## 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)
### HTML Validation Tests
All components should include tests that check the validity of the rendered HTML markup.
You can find utilities that simplify those tests in `/test-utils/html-validate.ts`.
**Example:** src/components/accordion/test/accordion.e2e.ts
```typescript
import { newE2EPage } from "@stencil/core/testing";
import { testValidHtml } from "../../../../test-utils/html-validate";
describe("uic-accordion", () => {
// Other e2e tests
it("should render valid html", async () => {
await testValidHtml(`
`);
});
});
```
### 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.
### Commit Messages
This repository follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/), based on the Angular convention.
Each commit message should use following pattern:
```
[optional scope]:
[optional body]
[optional footer(s)]
```
**type** (required) - is one of:
* `build` - changes that affect the build system or external dependencies
* `chore` - no production code change
* `ci` - changes to CI configuration files and scripts
* `docs` - documentation only changes
* `feat` - introduces a new feature to the codebase (correlates with MINOR in Semantic Versioning)
* `fix` - patches a bug in your codebase (correlates with PATCH in Semantic Versioning)
* `perf` - code change that improves performance
* `refactor` - code change that neither fixes a bug nor adds a feature
* `revert` - commit, which reverts another commit
* `style` - changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
* `test` - adding missing tests or correcting existing tests
**scope** (optional) - definition of a change area. At best, it should contain the name of a changed component.
**description** (required) - brief description of a change in commit. Rules for a commit message:
* use the imperative, present tense: "change" not "changed" nor "changes"
* don't capitalize the first letter
* no dot (.) at the end
**body** (optional) - full description of a change. Same message rules are applying, as for _description_. The body should include the motivation for the change and contrast this with previous behavior.
**footer** (optional) - should contain any information about Breaking Changes. Breaking Changes should start with the word `BREAKING CHANGE:` with a space or two newlines. The rest of the commit message is then used for this.
[Complete list of commit message linting rules](https://github.com/conventional-changelog/commitlint/tree/master/@commitlint/config-conventional)
## 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.