Development practices

Development workflow

1. Follow README.md instructions for setting up the dev environment.
2. Create a local feature branch off the latest develop 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 yarn verify.
   • If there are errors during this process, it usually helps to dive into each individual package and run the failing build script to debug it.
     • We recommend this approach in general for all developers after your first time building the Blueprint repo (instead of yarn verify at the root).
     • For example, try cd packages/core and run yarn test / yarn lint individually in that package.
   • Fix any build errors (caused by merge conflicts, broken unit tests, failed linting, etc.) until the server starts successfully.
4. Use the development script relevant to your work (detailed in the README).
5. Write code.
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.
   • Fill out the pull request template.
   • If your change is visual (most Blueprint features are), include a screenshot or GIF demonstrating the change.
10. Get approval from the Blueprint team.
    • When addressing feedback, push additional commits instead of overwriting or squashing (we squash on merge).
    • Be descriptive in your commit messages: prefer "fix style nits" to "address CR feedback" because the former provides context at a glance.
    • Our build bot will leave a comment on the PR with a link to the compiled artifacts on Circle. This notification is usually enough to alert 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.

Updating documentation

The Blueprint build system uses a tool called documentalist as part of its static site builder for the documentation site. It crawls source code and markdown files to do its job. If you edit any of the documentation markdown (.md) files in this repo, you will need to run yarn compile inside packages/blueprint-docs-data to see those changes reflected in the docs application.

Running unit tests

• yarn test runs all tests.
• cd packages/<name> && yarn test:karma:debug will run the karma unit tests for a single package in watch mode so they'll re-run on source or test changes.
  • use describe/it.only() to limit the suites run each time, but don't commit that!