Skip to content
This repository has been archived by the owner on Jul 24, 2019. It is now read-only.

How to Contribute

Jump to bottom
Peter Strömberg edited this page Jun 29, 2018 · 7 revisions

Calva Formatter is made using mainly using ClojureScript. The CLJS code is compiled into a JavaScript library that we then use from TypeScript, which is used for the VS Code integration.

The library is build using shadow-cljs.

The setup:

  1. Fork and clone your fork.
  2. Create a new branch for your changes. (See below for choosing where to branch off from.)
  3. npm install
  4. Open the project root directory in VS Code (code . if you have set up things like a boss)

The dev process:

  1. In VS Code: Tasks -> Run Build Task… -> Watch CLJC. Wait for it to compile the CLJC code and start watching.
  2. In VS Code: Tasks -> Run Build Task… -> Watch TS. Wait for it to compile the TypeScript code and start watching.
  3. Connect Calva: ctrl+alt+v c and select the :calva-fmt-libbuild. (Switch off Calvas auto connect feature in Settings for this Workspace).
  4. Start the extension in debug mode (the Extension Host): F5.

As you edit code, shadow-cljs will recompile the extension really fast, as will the TypeScript compiler. The test runner is triggered (but not discovering tests, see below). You need to restart the Extension Host after each rebuild to test it. (If you know how to get live reload to work, please let us know.)

Before sending pull requests

Try ”embed” some basic unit tests for any functionality in the ClojureScript code that you add or change. See below.

Use the vice tool to package a vsix file and install it manually in your VS Code and do some quick smoke testing.

After sending pull requests

When you have issued your Pull Request it is best to ping us about it to catch our attention. The #editors channel of the Clojurians Slack is a good place to ping us.

Embedded automatic tests

In this project we are trying to keep the tests with the code. To make it more synchronous and easy to maintain, and also so that the tests better can serve as documentation. The style we want to use is like so:

(defn- split
  "Splits text at idx"
  {:test (fn []
           (is (= [" " " "]
                  (split "  " 1)))
           (is (= ["(foo\n " "\n bar)"]
                  (split "(foo\n  \n bar)" 6))))}
  [text idx]
  [(subs text 0 idx) (subs text idx)])

It works very well together with interactive development using the REPL. Often you can start exploring in this :test function instead of e.g. a (comment …) block. Some of the explorations can then stay as tests (and documentation.

The project is set up to build a node-test target which triggers tests to run at each save of a file.

HOWEVER

cljs.test differs from clojure.test in that that it does not automatically discover these tests when running tests. 😢 It is very disappointing, but we will try keep this style anyway and try to fix the running of tests. Meanwhile make sure to evaluate the tests often (it is easy if you are a Calva user, after all).

If you have some knowledge about cljs.tests and/or macros, fixing this issue is the best way you can contribute to both Calva and Calva Formatter at the moment.

Clone this wiki locally