@claromentis/design-system/dist/docs/CONTRIBUTING.md

Claromentis Design System Component Library

# Contributing

A set of guidelines for contributing to the Claromentis Design System Component Library.

- [Getting started](#getting-started)
- [Linking your local Stencil and Claromentis](#linking-your-local-stencil-and-claromentis)
- [How to submit changes](#how-to-submit-changes)
  - [1. Create / Find ticket](#1-create--find-ticket)
  - [2. Create Branch](#2-create-branch)
  - [3. Make Changes and submit MR](#3-make-changes-and-submit-mr)
  - [4. Merge and release](#4-merge-and-release)
- [How to report a bug](#how-to-report-a-bug)
- [Style Guide / Coding Conventions](#style-guide--coding-conventions)
  - [Naming components](#naming-components)
  - [Component creation guidelines](#component-creation-guidelines)
  - [Git Commit Messages](#git-commit-messages)
  - [Documenting Components](#documenting-components)
  - [Accessibility](#accessibility)

## Getting started
To get started with the project follow the installation steps in the [README.md](../README.md)

### Linking your local Stencil and Claromentis
To test changes on your local copy of Claromentis it is best to link your local version of Stencil to your local version of Claromentis using the `npm link`:

1. First go to your local components library and run `npm link` to register it as a linkable module.
2. go to core and run `npm link @claromentis/design-system` to create a symlink to your local components library.
3. in order for the symlink to work you must build assets in Claromentis and run your local components library simultaneously.

## How to submit changes
### 1. Create / Find ticket
Look at the Design System [JIRA board](https://claromentis.atlassian.net/jira/software/projects/DS/boards/56) to see if a ticket exists for the work you are going to carry out.
If there is not a ticket already create one


### 2. Create branch

The convention we use for branch names is the following:

    Include the type of issue at the beginning, followed by a forward slash /
    Include a concise, snake-case description after the slash
    If there is an issue ID, such as a Jira issue reference, include this after the description and an underscore

Examples

    bugfix/fix-cla-progress-bug_DS-XXX
    improvement/some-component-improvement_DS-XXX
    feature/exciting-new-feature_DS-XXX

### 3. Make Changes and submit MR

* Make your changes in the branch
* Create a merge request in the project for the version branch of the version you are targeting (e.g `v0.1`).
* Run the library using the command `npm start --prod`
* Update version number incrementally in `package.json` using the Semantic versioning scheme. e.g:
    - 1.0.15 should be changed to 1.0.16 for a patch release (bug fixes and improvements)
    - 1.1.2 should be changed to 1.2.0 for a minor release (new features)
    - 1.2.0 should be changed to 2.0.0 for a major release (breaking changes)
    - Note that 0.x versions, like 0.0.34 or 0.12.0 are considered work in progress versions, where minor releases contain breaking changes
    - [Semantic versioning scheme](https://semver.org/) documentation.
* Run `npm install` so the `package-lock.json` file gets updated
* Edit the [Changelog.MD](CHANGELOG.md) with changes before submitting MR
* Another developer on the project will need to review the MR before it can be merged

### 4. Merge and release
When the work has passed review merge it into the correct main version branch (`master` is the latest version, older main version branches are prefixed with `v` e.g. the main branch of version 0.1 is `v0.1`)  
Finally, create a release using the guide in [readme.md](readme.md) (Publishing to NPM and using Component)

## How to report a bug
To report a bug please add an issue to the [Design System JIRA board](https://claromentis.atlassian.net/jira/software/projects/DS/boards/56/backlog)

## Style Guide / Coding Conventions

### Naming components

When creating new components, use the **`cla-` prefix** for their **tag name**. For example: `<cla-button>`.

In the `src/components` directory, name every directory and file related to a component consistently with its tag name.

For example, for the `<cla-button>` component:

```
src/components/cla-button/cla-button.tsx
src/components/cla-button/cla-button.scss
```

And in its `@Component` definition:

```ts
@Component({
  tag: 'cla-button',
  styleUrl: 'cla-button.scss',
  scoped: true,
  shadow: true
})
```

### Component creation Guidelines

- Use **props** for element **options**
  - 🚨Avoid using reserved public names for props like 'title' or anything prefixed with 'on...'🚨

> Reusing prop names that are already
> defined on the element's prototype may cause unexpected runtime
> errors or user-interface issues on various browsers, so it's best to
> avoid them entirely.

- Use **slots** for element **content**
- Emit **events** after **user interaction** and component **state changes**
- Document every `@Component`, `@Prop`, `@Slot` and `@Event` decorator with annotations and a description in a docblock

### Git Commit Messages

* Use the past tense ("Added feature" not "Add feature")
* Limit the first line to 72 characters or less
* Consider starting the commit message with an applicable emoji:
    * :art: when improving the format/structure of the code
    * :memo: when writing docs
    * :bug:  when fixing a bug
    * :fire: when removing code or files
    * :arrow_up: when upgrading dependencies



### Documenting components

 * Copy the below code snippet into the bottom of the src/index.html page.
 * Add a title, a working demonstration of the component and an example of the code as well as an example of the code within the `<xmp>` or `<pre>` tags dependant on length and a list of properties which is automatically generated from the id e.g. `id="cla-`".

```
  <section>
    <h3>Component name</h3>
    <cla-component></cla-component>
    <div class="code-block">
    <p>Basic use:</p>
      <xmp class="code">
        cla-component attribute="version"></cla-component>
      </xmp>
      </div>
      <p>Props:</p>
      <div id="cla-component" class="props">
      </div>
    </section>
```

   ###### if the code example is one line tall please use the following basic use code:
```html
  <p>Basic use:</p>
    <xmp class="code copy-code">
      cla-component attribute="version"></cla-component>
    </xmp>
```
  ###### if the code example is over one line tall please use the below code and run the code through an [escaping tool](https://www.freeformatter.com/xml-escape.html) to replace `XML` entities with characters and hold the code in `<pre>` tags with a class of `code` :

    `'` is replaced with `&apos;`
    `"` is replaced with `&quot;`
    `&` is replaced with `&amp;`
    `<` is replaced with `&lt;`
    `>` is replaced with `&gt;`

```html
  <p>Basic use:</p>
  <pre class="code">
&lt;cla-insignia size=&quot;large&quot; shape=&quot;hexagon&quot; type=&quot;empty&quot;&gt;
  &lt;cla-insignia-image  source=&quot;link.to&quot;&gt;&lt;/cla-insignia-image&gt;
&lt;/cla-insignia&gt;
    </pre>
```

### Accessibility
Refer to the [Accessibilty guide](https://design.claromentis.net/accessibility/overview) on the Design System documentation website for an overview and checklist about developing with Accessibility in mind.