@coveord/jsadmin-common

jsadmin-common

The project's main objective is to provide logic that can be used by multiple jsadmin-* repositories.

It is important to keep in mind that jsadmin-common is installed by all the jsadmin-* repositories, therefore any exported bit of code needs to be generic enough so that it can be reused accross all other jsadmin repositories.

Prerequisites

Set up a developer machine.

Setup

All the commands in the instructions must be run at the root of the jsadmin-common folder, unless otherwise specified.

Install

First you need to install the project's dependencies.

npm install

Once the operation is complete, you should see a node_modules folder at the root of the jsadmin-common folder.

Build

npm start

This command builds the source code, and automatically triggers a rebuild when a source file is saved.

Test

Run the complete test suite to ensure your local jsadmin-common build is healthy and does not introduce any unwanted regressions.

npm test

WARNING: Even if all the tests are successful, changes in this repository can introduce bugs in any other jsadmin-* repositories. It is the pull request author's reponsability to identify and properly handle any potential breaking changes they may be introducing.

Contributing

1. hg update on the tip of default branch (hg pull && hg update default).
2. Create a branch to work on following our branching model.
3. Work work work!
4. Create a pull request, our team will automatically be notified.
5. We will review your awesome fix/feature as soon as we manage to.
6. Once your PR gets enough approvals (at least 2 different members of our team), you can merge (or ask us to do so if you don't have the required credentials).
7. Our automated build system will take care of the rest.

Guidelines

• A pull request that increases or maintain the code coverage ratio has higher chances of being merged quickly.
• Make sure your pull requests follow the project's code style. To do so, you can simply run npm run lintfix and it'll fix all the code style errors by itself. Don't forget to commit those changes.
• We're pretty flexible on the commit messages structure and pull requests descriptions, but still, make sure your commit messages and pull request descriptions provide enough details for fellow reviewers.
• We tend to avoid comments in our code base, we strongly prefer good naming and code structure.

Pull request demos

Our automated build system kindly provides a demo link for each pull request, given the build is healthy (all unit tests have run successfully). When available, the links are automatically posted in our #cloudadminbuild private Slack channel. We will gladly invite you to the channel if you're not already a member when you submit a pull request. If we forget to do so, just ping us in Slack and we'll do it right away.

Front-end developpers are visual creatures!

We always like to see your changes in action (when it is relevant) before merging pull requests. Therefore, please include a comment in your pull requests that provides the demo link once it is available. Also, it makes things easier for everone when the link points towards the exact section where lies the bulk of your changes.

Tips and tricks

• npm test command creates a local coverage report at the end of its execution. You can browse this report to see the hits and misses of your unit tests. To do so, open the coverage/lcov-report/index.html file in your favorite web browser.
• npm run test:watch command will run tests on file save.
• npm run reconstruct command will reinstall and rebuild your local branch from scratch without discarding any pending change. Run this if you think your current state is corrupted.
• You can target specific unit tests or test suites by putting an f character in front of any it or describe block (thus writing fit and fdescribe). Only tests in the targeted blocks will be run on the next execution. Don't forget to remove the f before committing.

Running your jsadmin-common changes locally in the Administration Console

If you want to test out your changes locally directly in the Administration Console, you can do so using a local build of jsadmin-v2 and the npm link feature.

Step	Terminal window 1	Terminal window 2
1	cd path/to/jsadmin-common	cd path/to/jsadmin-v2
2		npm link ../relative/path/to/jsadmin-common
3	npm start
4		npm start

You can leave both terminal windows running. Changes saved in either repositories will trigger a rebuild of the local demo.

WARNING: running npm install in either of the linked repos might break the npm link. Running again the steps above will fix the situation.

Building a pull request demo with a custom jsadmin-v2 branch

Sometimes while working on complex features or fixes, you will be making changes in both jsadmin-common and jsadmin-v2 repositories. In order to provide a working demo link that includes your changes from both repositories, you will need to specify your jsadmin-v2 branch name in jsadmin-common/.demo-branch file.