Contributing

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

Getting started

To get started with the project follow the installation steps in the 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 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 documentation.
  • Run npm install so the package-lock.json file gets updated
  • Edit the 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 (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

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:

@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:
  <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 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;`
  <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 on the Design System documentation website for an overview and checklist about developing with Accessibility in mind.

UI Components