How to Contribute

Currently Calva is mostly JavaScript renamed to .ts, but slooooowly being migrated to being mostly ClojureScript. The plan is to have most of the ”logic” build with ClojureScript while keeping the integration with VS Code in TypeScript. (There are reasons for this, that I'll find the time to write about some time.)

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

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?)

The dev process is like so:

1. Do Run Build Task… in VS Code and chose npm: watch. (This will run shadow-cljs and make it watch :test and :calva-lib.)
2. Check the task Output pane and notice that tests are run.
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 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 master (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 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.

Please consider contributing to the porting of Calva to CLJS, as this will be a lot of work. Contact me and we can discuss together how we should go about it.