Contributing

Development & scripts

Development should be pretty straight forward. Run compas test to run the test suite. Before making a commit, make sure to run compas lint. Note that this automatically tries to fix most issues. All commands in this repo can be run vai the 'self-hosted' @compas/cli. Run compas help for an overview. Below a few commands related to things you could be working on:

General:

# Install dependencies
npm install
# Format with ESLint & Prettier
compas lint
# Run the tests
compas test (--coverage)

Documentation:

# Sync CLI api reference and regenerate
compas run syncMetadata

Code generation, @compas/store structure changes:

compas generate

Improving test coverage

There are many things not covered by tests, there are a few ways to improve coverage, but let's start by running compas test --coverage and opening file:///path/to/repo/coverage/lcov-report/index.html in your browser.

If it is your first time doing this, start by checking out files in the generated directory. Most of these files are partially covered, and it should be pretty straight forward to find a related function that is tested, and doing the same for the yet untested function. For new cases related to code generation, add the missing case in gen/testing.js and regenerate with compas generate. Then run compas test --coverage again to see that the new case is not yet covered by tests.

Debugging tests

Debug that file as if you debug whatever other Node.js script. E.g in Webstorm: (right-mouse click -> Debug file.test.js)

Publishing

• Ensure you are logged in to npm with npm whoami, when logged out; npm login
• Ensure you have the main-branch checked out, and are completely up-to-date
• Write to the changelog
  • Run compas run changelog
  • Replace x.x.x with the new version (3 times) in ./changelog.md
  • Write about the changes and how to use it them, in docs/releases/x.x.x.md
• Check if types are still generating with compas run types
• Sync metadata: compas run syncMetadata, this will sync the changelog to the docs folder and regenerate the api reference.
• Commit with chore: prepare release for vX.X.X and push to main
• Run compas release --version vX.x.X --otp 111111. This will build & publish all packages
  • Specify the new version
  • Check packages it will publish and send y
  • Give a new OTP every time it is asked.

WebStorm

• Help > Edit Custom Properties... > idea.javascript.max.evaluation.complexity=80
• Open /package.json > Find Actions > Apply Prettier Code Style Rules
• Open /.eslintrc.cjs > Find Actions > Apply ESLint Code Style Rules
• Settings > Node.js And NPM > Coding assistance for Node.js
• Edit configurations... > Templates/Node.js:
  • V8 Profiling > Allow taking heap snapshots
  • Configuration > Working directory > /path/to/checkout/root