Development practices

Development workflow

1. Follow README.md instructions for setting up the dev environment.
2. Create a local feature branch off the latest master and switch to it.
   • Use the naming scheme <initials>/<short-kebab-case-description> (example: gg/hot-buttons). This reduces potential conflicts and signifies a responsible party for the branch so that it can be deleted when stale.
   • If starting a collaborative or long-lived feature branch, use the naming scheme feature/<short-description>.
3. Run gulp.
   • Fix any console errors (caused by merge conflicts, broken unit tests, failed linting, etc.) until the server starts successfully.
4. Go to the local LiveReload server at localhost:9000/packages/docs/dist/.
5. Write code.
   • The dev server will hot-swap CSS changes.
   • If you edit KSS markup or TypeScript code, you will need to refresh the page.
   • Follow our coding guidelines.
6. Rely on your editor for real-time feedback by setting up the appropriate linter and compiler plugins.
7. Write unit tests for your change.
8. Commit your code with a descriptive message.
   • If your change resolves an existing issue (usually, it should) include "Fixes #123" on a newline, where 123 is the issue number.
9. Push your feature branch to your fork of the blueprint repo and open a PR.
   • If your change is visual (most Blueprint features are), include a screenshot or GIF demonstrating the change.
   • If you have permissions, mark the PR with the label "PR: needs review" so we know it's ready for us. You can use the "Status: work in progress" label if you're not ready for full code review yet.
10. Get approval from the Blueprint team.
    • When addressing feedback, push additional commits with just the revisions. Be descriptive in your commit messages: prefer "fix style nits" to "address CR feedback" because the former provides context at a glance.
    • Each successful build will trigger a comment on the PR with a link to the compiled artifacts on Circle. This notification is usually enough to signal reviewers that there are new changes.
11. Squash & merge.
    • We use GitHub's squash & merge feature to maintain clean history on develop. It's great.
    • If you're not a core contributor, please let a team member merge your PR.

Running unit tests

gulp karma runs all the unit tests in Phantom.

You may run a specific sub-project's tests via gulp karma-<name>. Alternatively, gulp karma-unit-<name> runs tests in Chrome (and re-runs them on file changes) where you can debug them more easily.