Contributing New Features

Thank you for your interest in contributing! We keep our components, functions, and utilities in the frontend-packages repository, which is a lerna monorepo. We highly recommend reading up on lerna and monorepos.

Before you start

Semantic Versioning

We follow semantic versioning. We release patch versions for critical bugfixes, minor versions for new features or non-essential changes, and major versions for any breaking changes. When we make breaking changes, we also introduce deprecation warnings in a minor version so that our users learn about the upcoming changes and migrate their code in advance. Every significant change is documented in the changelog file.

Branch Organization

We use feature branches strategy from the master branch. This means that each new feature, you will create a new branch based on master, and your pull request will aim to merge it back. We don’t use separate branches for development or upcoming releases. We do our best to keep master in good shape, with all tests passing.

Code that lands in master must be compatible with the latest stable release (always keep your branch updated with the master branch). It may contain additional features, but no breaking changes.

Bugs

We are using GitHub Issues for our public bugs. We keep a close eye on this and try to make it clear when we have an internal fix in progress. Before filing a new task, try to make sure your problem doesn’t already exist. You can report new issues/bugs using the GitHub Issues providing a reduced test case.

Proposing a Change

If you intend to change the public API, or make any non-trivial changes to the implementation, we recommend filing an issue. This lets us reach an agreement on your proposal before you put significant effort into it.

If you’re only fixing a bug, it’s fine to submit a pull request right away but we still recommend to file an issue detailing what you’re fixing. This is helpful in case we don’t accept that specific fix but want to keep track of the issue.

Prerequisites

• A configured dev environemnt

• Unlike most projects, frontend-packages requires yarn

Project Structure

This project uses Lerna and Yarn Workspaces to manage the packages and dependencies.

Packages

All packages are under the packages directory. They contain their own package.json and other configuration files. All configuration for a package is completely independent.

packages

|- package-a

|- package-b

|- src

|- tests

|- package.json

|- webpack.config.js

lerna.json

package.json

requirejs.config.js

Dependencies

All internal package dependencies should be locked to the latest major version and allow minor and patch versions, to ensure that breaking changes in one package do not carry through to the dependant package.

{

"dependencies": {

"@iqmerix/b": "^1.2.3"

}

}

Getting Started

1. Download the frontend-packages repository from Github.

   $ git clone git@github.com:iQmetrix/frontend-packages.git

   $ cd frontend-packages

2. Install dependencies, Bootstrap, and build the repository in the frontend-packages root folder.

   yarn && yarn bootstrap && yarn build

   Protip: You can pass command line flags to yarn commands. This can be useful for watching for changes while developing.

   yarn build --watch

3. Create a new package if required.

   There is a _template folder that contains all the required files to begin with. Copy this folder and replace the TODO and packageName values accordingly.

   • We require that packages include unit tests if possible. Your package.json must include an npm script named "test".

     "test": "jest"

     If your package has no tests, you still need to provide a test script that indicates you are not providing tests.

     "test": "jest --passWithNoTests",

   • You can test your pacakge externally using yarn link, which creates symlinks to local projects in node_modules.

     In your package

     yarn link

     And in the consuming app

     yarn link "@iqmetrix/packageName"

     yarn link can sometimes have issues with nested dependencies. If your package is not working when linked, you can try publishing an alpha version.

   • Update package.json, changelog.md and readme.md files.

   • It is important to use the right type of dependencies in package.json:

     • dependencies are packages used in the implementation of your package.

     • devDependencies are used during development and build steps. These packages are not used within the implementation of your package. Eg. eslint for linting, or jest for testing.

     • peerDependencies are packages that your package expects to be installed alongside itself. Eg. Plugins are a common examples of peer dependencies.

4. Update the documentation website.

   • Contributing Documentation
   • Component Documentation Template
   • Function Documentation Template
   • For new and updated components, consider adding stories to @iqmetrix/storybook

Creating a Pull Request

Before submitting a pull request, please make sure the following is done:

1. Create your branch from master.
2. Run yarn in the repository root.
3. If you’ve fixed a bug or added code that should be tested, add tests!
4. Ensure that all the packages are able to build (yarn build)
5. Ensure the test suite passes (yarn test). Tip: yarn test --watch TestName is helpful in development.
6. Format your code with prettier (yarn prettier).
7. Make sure your code lints (yarn lint). Tip: yarn linc to only check changed files.

Create PRs in both the frontend-packages repository and iQ.design.system.docs repository (if you are updating iQ.design.system.docs). - Reference the PRs from one another

```markdown

Documentation iQmetrix/iQ.design.system.docs#51

Code iQmetrix/frontend-packages#115

```

- Include your changes in the package's `changelog.md` under the `Unreleased` heading. Follow [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) formatting.

```markdown

## [Unreleased]

### Added

- A new feature

```

host-interop packages

If you are adding a new host-interop supported package, or have changed any of our host-interop supported packages, please make sure to update the Host Support documentation.

Publish Your Package

Once your PRs are approved and merged publish your package. If your changes involve multiple packages (eg. @iqmetrix/antd and @iqmetrix/style-tokens) you will need to publish all changed packages.

To publish, in the root directory of frontend-packages, run yarn run publish. Note that this will pick up any changes that weren't already versioned and published previously.

This command uses lerna publish to version and publish our packages. This will bump your versions and create changelogs based on the Conventional Commits formatted commit messages. It will also push a GitHub Tag with these changes, and publish to our Azure DevOps Artifacts NPM registry.

Contribution Prerequisites

• You have Node installed at v10.0.0+ and Yarn at v1.2.0+.

Development Workflow

After creating your own branch, run yarn to fetch its dependencies. Then, you can run several commands (on the root):

• yarn lint checks the code style.
• yarn linc is like yarn lint but faster because it only checks files that differ in your branch.
• yarn test runs the complete test suite.
• yarn test --watch runs an interactive test watcher.
• yarn test <pattern> runs tests with matching filenames.
• yarn build creates a dist folder for all the packages.

Tip for when creating new branches

In the scenario you already have the frontend-packages repository cloned and you are creating a new branch, it is recommended to run git clean -fdx && yarn && yarn build to make sure you will install all the latest dependencies and re-build all the packages.

Style Guide

We use an automatic code formatter called Prettier. Run yarn prettier after making any changes to the code.

Then, our linter will catch most issues that may exist in your code. You can check the status of your code styling by simply running yarn linc.

However, there are still some styles that the linter cannot pick up. If you are unsure about something, looking at ESLint recommended rules. Another good resource is the Airbnb’s Style Guide which can guide you in the right direction.

Troubleshooting

I am getting an error when trying to build the repository for the @iqmetrix/hub-dev-server package

Configure two environment variables related to TeamCity authentication

export TC_USERNAME=your_ActiveDirectory_user

export TC_PASSWORD=your_ActiveDirectory_password

I am getting an error when trying to run all the tests for the @iqmetrix/cypress package

Configure the environment variables related to hubtests Azure KeyVault App Registration.

export AZURE_CLIENT_ID=client_id

export AZURE_CLIENT_SECRET=a_client_secret

export AZURE_TENANT_ID=tenant_id