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.
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.
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.
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.
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.
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.
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.
Download the frontend-packages repository from Github.$ git clone email@example.com:iQmetrix/frontend-packages.git$ cd frontend-packages
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
Create a new package if required.
There is a
_templatefolder that contains all the required files to begin with. Copy this folder and replace the
We require that packages include unit tests if possible. Your
package.jsonmust 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
In your packageyarn link
And in the consuming appyarn link "@iqmetrix/packageName"
yarn linkcan sometimes have issues with nested dependencies. If your package is not working when linked, you can try publishing an alpha version.
It is important to use the right type of dependencies in package.json:
dependenciesare packages used in the implementation of your package.
devDependenciesare 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.
peerDependenciesare packages that your package expects to be installed alongside itself. Eg. Plugins are a common examples of peer dependencies.
Update the documentation website.
Before submitting a pull request, please make sure the following is done:
- Create your branch from master.
yarnin the repository root.
- If you’ve fixed a bug or added code that should be tested, add tests!
- Ensure that all the packages are able to build (
- Ensure the test suite passes (
yarn test). Tip:
yarn test --watch TestNameis helpful in development.
- Format your code with prettier (yarn prettier).
- Make sure your code lints (yarn lint). Tip: yarn linc to only check changed files.
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.
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.
After creating your own branch, run
yarn to fetch its dependencies. Then, you can run several commands (on the root):
yarn lintchecks the code style.
yarn lincis like
yarn lintbut faster because it only checks files that differ in your branch.
yarn testruns the complete test suite.
yarn test --watchruns an interactive test watcher.
yarn test <pattern>runs tests with matching filenames.
yarn buildcreates a
distfolder 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.
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
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.
I am getting an error when trying to build the repository for the
Configure two environment variables related to TeamCity authentication
I am getting an error when trying to run all the tests for the
Configure the environment variables related to hubtests Azure KeyVault App Registration.