Contributing

Issues

Report issues and suggest features and improvements on the GitHub issue tracker. Don’t ask questions on the issue tracker - use the support channels instead.

If you want to file a bug, please provide all the necessary info listed in our issue reporting template (it’s loaded automatically when you create a new GitHub issue).

Patches

Patches in any form are always welcome! GitHub pull requests are even better! :-)

Before submitting a patch or a pull request make sure all tests are passing and that your patch is in line with the contribution guidelines.

Documentation

Good documentation is just as important as good code.

Consider improving and extending this manual.

Working on the Docs Site

The documentation site is generated from the AsciiDoc files in the doc folder of nREPL’s GitHub repo and is published to https://nrepl.org. Antora is used to convert the manual into HTML. The filesystem layout is described at the Antora docs.

To make changes to the manual you simply have to change the files under doc. The site is rebuilt and published automatically: on every push to the nrepl.org repository, once a day, and whenever a doc change lands on master here.

When you rename or move a page, add a :page-aliases: attribute naming the old file to the new page, so the old URL keeps working.

Building the Site

The site lives in the nrepl.org repository, which pins the Antora version it builds with, so clone it next to your nREPL checkout and use its Makefile rather than a globally installed Antora:

$ cd nrepl.org
$ make

That fetches nREPL’s master and every released version from GitHub and writes the site to build/site; open build/site/index.html in your browser.

Previewing Local Changes

To build the site from your local nREPL checkout instead, uncommitted changes included, use the local playbook:

$ cd nrepl.org
$ npm run antora -- antora-playbook-local.yml

It builds whatever branch ../nrepl has checked out, so only that one version shows up in the version menu.

If you want to make changes to the manual’s page structure you’ll have to edit nav.adoc.

Releasing

Deploying to Clojars

Releases are done by CircleCI automatically. To push a release, you need to tag a commit in the master branch with the desired release version, starting with v, e.g. v1.2.3.

$ git tag v1.2.3
$ git push origin v1.2.3

Tagging a new release will also trigger the creation of a GitHub release automatically.

Funding

While nREPL is free software and will always be, the project would benefit immensely from some funding. Raising a monthly budget of a couple of thousand dollars would make it possible to pay people to work on certain complex features, fund other development related stuff (e.g. hardware, conference trips) and so on. Raising a monthly budget of over $5000 would open the possibility of someone working full-time on the project which would speed up the pace of development significantly.

We welcome both individual and corporate sponsors! We also offer a wide array of funding channels to account for your preferences (although currently Open Collective is our preferred funding platform).

If you’re working in a company that’s making significant use of nREPL we’d appreciate it if you suggest to your company to become a nREPL sponsor.

You can support the development of nREPL, CIDER, clojure-mode and inf-clojure via Open Collective, GitHub Sponsors, Patreon and PayPal.

Open Collective