Skip to content

How to Contribute

Jump to bottom Edit New page
Peter Strömberg edited this page Oct 12, 2019 · 36 revisions

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 a :node-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. From the VS Code Terminal menu, choose: Run Build Task….
    1. Wait for it to
      1. Build the :node-library, :calva-lb, and run its tests
      2. Build the TypeScript code
      3. Start watching.
  2. (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.
  3. Start the extension in debug mode (the Extension Host): F5.
  4. Hack away. The watch tasks will rebuild the extension really quickly.
    • You'll find the output from the build task in the 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).
  5. 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.

Make sure you are directing the pull request at the dev branch, unless you have reasons to target some other branch. And ”some other branch” is never master, which happens to be the default.

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 typo, 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. GitHub is awesome with this, let's leverage!

Please see our Pull Request Template for more info on what a full PR cycle can look like.

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, @cfhse 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, and grammar 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.

Again, see the Pull Request Template for more.

About Testing VSIX Packages

A VSIX package is how VS Code extensions are packaged. It is a zip-file with the extension .vsix (e.g. you can examine the contents some with unzip -l).

Building a VSIX Package

To build the Calva extension (assuming you have done npm i):

$ npx vsce package

This will compile all the things and leave a Calva-<version>.vsix file for you. <version> will be picked from package.json, which on dev (which you branched off your changes from, remember?) will be the currently released version + 1 patch. In order to play nicely along with VS Code's auto-update features, you probably want to add a prerelease suffix to that version, so that it reads <version>-your-prerelease-suffix.

Please also note that a VSIX package will be built by CircleCI, when you file a PR. You'll find a CI section at the end of the PR page on Github. There you'll see that one of the build steps is called ci/circleci: build. The details link takes you to the job on CircleCI, and there you should find a tab labeled Artifacts. Download the .vsix file from there. (This file will always be suffixed as a prerelease).

NB: At a time of this writing you need to be logged in on CircleCI to see it. Either do that or opt-in for the New Experience UI that the page offers, because that version of the UI shows the artifacts tab regardless of if you are logged in or not.

Installing a VSIX Package

To use your custom Calva VSIX package you open the Extensions pane in VS Code and locate the small meatballs menu at the top of the pane. It has the option: Install from VSIX...

To start using the currently released Calva again use the settings gear menu on the Calva entry in the Extensions pane and choose Install Another Version....

VS Code adhers to SemVer when it comes to extension versions. So if you have autoupdates on, which is nice, it will update to any released version with a major.minor.patch higher than the one you are currently using. And it will also update any major.minor.patch-pre-release, with the same, or higher, major.minor.patch. Good to keep in mind.

Just One More Thing

Happy Calva coding! ❤️

Add a custom footer
Add a custom sidebar
Clone this wiki locally