How to Contribute

There are many ways to contribute. Test, make tutorials, cheer us on, etcetera. This document is so far about introcuding changes to Calva. Please also see our maintainer's documentation about this.

Calva is mostly TypeScript, but some things are written in ClojureScript. The cljs code is compiled by shadow-cljs into an npm library, that is then required from TypeScript.

The Setup:

Start by saying hello in #calva-dev at the Clojurians Slack. Then:

1. Clone your fork of https://github.com/BetterThanTomorrow/calva
2. Checkout the dev branch. This is where all Calva development happens.
3. Open the project root directory in VS Code. (You are using VS Code and Calva, right?)
4. Open an integrated Terminal and npm install

The dev process looks like so:

1. Run the build task Watch TS.
   1. Wait for it to compile the TypeScript code and start watching. (Only takes a second).
2. Run the build task Watch Webpack.
   1. Wait for it build its stuff and start watching. (This also only takes a second).
3. (Optional, if you want to play with the cljs part of Calva) Jack in Calva to Calva itself.
   1. Choose to connect to the :calva-lib cljs REPL.
   2. Wait for it to build and run the tests. (You'll see this happening in the Terminal spawned to run the Jack-in task.)
4. Start the extension in debug mode (the Extension Host): F5. (This is the app with a cljs REPL server your Calva will connect to.)
5. Hack away. The watch task will rebuild the extension really quickly.
   • You'll find the output from both build task in their respective vscode Terminal view, and for the cljs part in its Jack-in terminal.
   • NB: There are no automated tests for the TS code, 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).
6. Restart the extension host when you have new TS code to test (cljs code will hot-reload, just as you are used to).

Before Sending Pull Requests

Feel invited to send us a PR just as a way to get feedback. You don't need to wait until your code works or the change is completed. Work in progress is totally PR-able.

That said: Make sure you are directing the pull request at the dev branch, unless you have reasons to target some other branch.

Also:

1. Please consider filing an issue for the thing you are fixing, wether it is a bug, a change to a feature, or a new feature. (Unless, of course, such an issue already exists.)
2. If your PR is more than just fixing a type, have your work in a feature branch. Since most PRs will be of a work-in-progress nature, you are welcome to follow our convention of naming our feature branches wip/<short-feature-title>.
3. Update CHANGELOG.md under [Unreleased]. Link your entry to the issue you are fixing.
4. In PR commit message, mention any issues you are addressing or fixing (maybe by, as per 1.). Use the fixes/closes syntax, if applicable. (If you are not fixing the entire issue, say something like ”Addressing: #42”).
   • This will make people looking at that issue see that there is work being done, where it is carried out, and what is being changed. Also using the ”Fixes” syntax will make GitHub automatically close the issue, linking the commit that did it, when the commit is merged onto master.

After Sending Pull Requests

When you have issued your pull request, it is best to ping us about it to catch our attention. The #calva-dev channel of the Clojurians Slack is a good place for this ping, mention @pez and @ksthen even.

We will try to get back to you quickly with our assessment of wether this PR fits the Calva path. Depending on the nature of the change it might need some discussion.

We use Circle-CI to automatically build any updates to a PR. It will run the automated tests and give you feedback on the PR page on Github. It will also build a VSIX package for you. Every time you have pushed updates to the PR, please download it and smoke test it some. Our release process relies on that the VSIX packages are sanity checked along the development process.

To Get Your PR Merged

1. The Calva team will have to agree it fits the path Calva is travelling along.
2. All tests must pass. Please add some basic unit tests if the code base it affects has unit tests. (Currently only the ClojureScript parts.)
3. Any changes to README.md are done (or, if you prefer we write it, communicated to us).
4. The VSIX package is tested by you.

Happy Calva coding! ❤️