By Alys Brooks

We’re always excited when someone new contributes a fix, test, documentation update, or even a major new feature to our open source projects. If you’re new to programming, open source projects are a great way to get experience working on a larger project. If you’re not so new, they can be an opportunity to try a new technology or work on a kind of software you usually don’t get a chance to. Either way, it’s rewarding to help out your fellow users or developers—these issues are for Kaocha, one of the most popular and advanced Clojure test runners.

But open source can also be intimidating. If you haven’t been sure where to start, then this post is for you! We’ve outlined the process step by step, and we’re here to support you every step of the way.

Below are some issues we’ve specifically picked for newcomers that have roadmaps to guide your development. If you get stuck, we’re happy to answer questions in the Clojurians Slack or on your PR. After you Sign up for Clojurians you can find us in the #lambdaisland and #kaocha channels. We’re also available for a quick call to help orient you.

But who are we? Lambda Island provides educational materials on Clojure web development, testing, and many other topics, plus we create open source projects like Kaocha and deep-diff2, which produces clear diffs for Clojure data structures.

Here’s how you get started:

1. Pick an issue from the below list.
2. Confirm that it isn’t assigned and leave a comment saying you’re working on it.
3. Review the guidelines.
4. Create a fork.

5. Clone the repository:

   Go to your newly created fork on Github (this should look like https://github.com/[YOURUSERNAME]/kaocha), and look for the big green “Code” button. This will give you the URL that you can pass to git clone.

   You have the option to use HTTPS or SSH, which you can read about in Github’s documentation. Using SSH can be convenient but requires some configuration. When in doubt, just pick HTTPS.

   git clone https://github.com/[YOURUSERNAME]/kaocha.git
   cd kaocha
   

6. Create a branch.

   git checkout origin/main -b <your-branch-name>
   
   # Branch 'your-branch-name' set up to track remote branch 'main' from 'origin'.
   # Switched to a new branch 'your-branch-name'
   

   Pick a nice desriptive branch name like fix-widget-interaction-issue or focus-command-line-narrows-suite-definition.

7. Have a look around, and then make your changes.

   Kaocha’s implementation lives under the src directory, while the test directory contains our test suite for testing Kaocha itself. The issue you picked should contain details on where to look to get started, but feel free to just open some files at random and have a look around. You won’t understand everything (or perhaps, anything), but that’s ok. Just get a feel for what is there, and try to imagine how some of it might fit together.

   You can start by running bin/kaocha, which will cause Kaocha to test itself. This is a good starting point to make sure your environment is correctly set up. Next you can try to “jack in” with your editor so you are able to evaluate code. Once you are connected, you can start coding.

8. Test your changes. There are a couple of options:

   • Using your REPL or interactive environment. This should be the first place to start; try calling the functions you are working on directly to see if they work. This isn’t always trivial since sometimes quite a bit of setup is needed, but it’s the best way to get quick feedback. We’re happy to help figure this part out. If you can get this far, then adding unit tests for your changes will be easy too. (Or at least, easier!)
   • Use the kaocha.repl namespace to run some (or all) tests. This works on two levels, this runs Kaocha, and so you might see your new code in action that way, it also runs tests which test various parts of Kaocha.
   • You can also run bin/kaocha again from a terminal. This ensures you are running from a clean slate, regardless of the state of your REPL. You may want to use the -c option to specify a custom tests.edn file that you can add any newly created options to or tweak the options to produce the behavior you’re trying to fix. You can run bin/kaocha unit to just run the unit tests, which is faster than running the entire suite including integration tests.

   • Use your version of Kaocha on an Clojure project you already have, or on a new “test” project you create. With deps.edn this is very straightforward:

     ;; deps.edn in the new project
     {:deps {lambdaisland/kaocha {:local/root "/path/to/where/you/cloned/kaocha"}}}
     

     Follow the Kaocha documentation to set up this test project with Kaocha (tests.edn, bin/kaocha, and test/*.clj files).

     If you want to use Kaocha on a project that doesn’t use deps.edn but instead uses project.clj (Leiningen) or build.boot (Boot), then you need to build and install Kaocha locally first. Make sure you have Maven installed:

     $ mvn --version
     Apache Maven 3.6.3
     Maven home: /usr/share/maven
     Java version: 11.0.7, vendor: GraalVM Community, runtime: /home/arne/opt/graalvm-ce-java11-20.1.0
     Default locale: en_US, platform encoding: UTF-8
     OS name: "linux", version: "5.8.0-34-generic", arch: "amd64", family: "unix"
     

     Then in the Kaocha directory run mvn install. This will install a local copy of Kaocha, including your changes. Make note of the version, and use exactly that version in the test project. Since this installs a copy into your local Maven cache, you will have to rerun mvn install every time you make changes to install a version with your changes.

9. Add your changes to git:

   When you’re ready, or you want to share your progress, then it’s time to create a git commit. First review your changes:

   # see which files changed
   git status
   
   # see the changes
   git diff
   
   # see a summary of the changes
   git diff --stat
   

   Now add your changes to the git “staging area,” so they are ready to be committed:

   git add <changed files>
   

10. Commit your changes:

    git commit
    

    This will open your editor, so you can write a commit message. Start with a single line with short description, then leave a blank line, followed by a detailed description of the what and, more importantly, the why of your changes.

11. Push your changes to Github

    git push origin <your-branch-name>
    

12. Follow the link in the message that appears to create a new Pull Request from your changes.
13. Write up what you changed and create a pull request.

If you get stuck at any of these steps, we’re happy to help!

To help you pick an issue that fits the amount of time you have, the list’s divided up into Quick(ish) Fixes and Features. Keep in mind that sometimes there are unexpected twists and turns in addressing an issue and that your first issue will take a little extra time as you aren’t (yet) familiar with the codebase.

Quick(ish) Fixes

Provide a warning when no tests are found #34

It’s not always clear why no tests are found. If this happens, there should be a helpful error message to let the user know what might have gone wrong.

More details are in this comment.

Unhelpful error message when ns-patterns is a string #124

It’s easy to miss the s in :ns-patterns and just specify a single pattern. If you make this mistake, you get an ambiguous error about class casting. If you add a helpful error pinpointing the configuration mistake, it could be cleared up.

This comment has the details.

Features

Fix the is trip-up (#65)

The is macro is intuitively named. (is (= "string1 "string2")) is kind of like “string1 is equal to string2” or even “Is string1 equal to string?”. But in other programming languages (not to mention English), is by itself has a similar meaning to =, so it’s tempting to write (is "string1" "string2") . But in Clojure tests, writing (is "string1" "string2") won’t do what you want. When called with two arguments, the first argument is (still) the test and the second argument is the message. But values (besides false) are treated as equivalent to true, so you’ve created a test that can never fail!

We can smooth over this speed bump in Kaocha, since it’s looking at all your tests anyway.

In short, you’ll need to create a replacement for clojure.test/assert-any and use a technique called monkey patching to replace this library function with your new-and-improved one.

This comment has the details.

Allow configuring skip-meta / focus-meta at the top level (#47)

You can already tag tests with metadata, like :Pending or :Critical and configure tests suites to either skip them or focus on them (run only them). However, you can’t make this configuration global; you’d have to repeat it for each test. You can fill in this gap.

As a bonus, you could make --skip-meta add to what’s already skipped rather than replace what’s already being skipped.

This comment has the details.