How to Contribute

Calva Formatter is made using a mix or TypeScript and ClojureScript. Generally the integration with VS Code is done in TypeScript and the actual formatting is done in ClojureScript.

The CLJS code is compiled by shadow-cljs into an npm module, @cospaia/calva-lib, that is then required from the TypeScript part.

Depending on what you want to contribute you might have to fork at least two repos: This one, and calva-lib.

The setup:

Consider saying hello in #calva-dev at the Clojurians Slack.

Unless you know that your change is on the extension/TypeScript end only, start with:

calva-lib

1. Clone your fork of https://github.com/BetterThanTomorrow/calva-lib
2. Most often you'll be branching off of master (the main branch).
3. npm install (This will install, amongst other things, shadow-cljs)
4. Open the project root directory in VS Code. (You are using VS Code and Calva, right? Not that it is a requirement for hacking on calva-lib, really)

The dev process is like so:

1. Run the npm watch build task. (This will run shadow-cljs and make it watch :test and :calva-lib.)
2. Check the task Output pane and notice 6 tests failing (all todo with top level indenting not working yet, please feel free to discuss with me ways to fix this.)
3. Connect Calva and choose the node-repl for your CLJS repl (it won't work with any of the build repls, unfortunately).
4. Hack away. Every time you save, the tests are run.
   1. Add/remove/modify any relevant test.
5. Test the changes in the actual extension (see below about that setup).
   1. Assuming it is setup this means switching to the calva-fmt window and restart the extension host process (then switch to the extension host window and do your manual testing).

For testing the changes to the actual extension you'll need to setup:

The extension

1. Clone your fork (I'll assume you do so in a sibling directory to calva-lib).
2. Most often you'll be branching off of develop (the main branch).
3. npm install
4. Open the project root directory in VS Code.

The dev process depends a bit on wether you are hacking also on calva-lib. If you are, then start with:

1. npm link ../calva-lib/packages

Regardless, this:

1. Run the build task Watch TS. Wait for it to compile the TypeScript code and start watching. (Only takes a second).
2. Start the extension in debug mode (the Extension Host): F5.
3. Hack away. The watch task will rebuild the extension really quickly.
   1. There are no automated tests for the extension, mainly because I don't know how to do it. Please consider setting that up to collect gold stars in heaven (as we say in Sweden).
4. Restart the extension host when you have new code to test (regardless if it is calva-lib, or the calva-fmt, or both that has changed.

Before sending pull requests

1. Make sure all tests pass. Please add some basic unit tests for any functionality in the ClojureScript code that you add or change.
2. If you have changed calva-lib, then build a release build:
   1. npm run release
3. Restart the extension host in the calva-fmt window and test that things still work. (You need to add the ^:export meta-data to anything you want to be accessible from the requiring TypeScript code.)
4. Package a vsix file:
   1. vsce package (you might need to npm install -g vsce first.)
   2. Install the vsix it manually in your VS Code and do some testing that the production build works.

After sending pull requests

When you have issued your Pull Request it is best to ping me about it to catch my attention. The #calva-dev channel of the Clojurians Slack is a good place for this ping, mention @pez even.