Trying ClojureScript Patches
Improvements to ClojureScript are very much community driven. One easy way to help is to try out proposed ClojureScript patches.
By doing this, you provide needed coverage relative to diverse environments and codebases. This produces immense value—relative to the effort required—and greatly reduces the burden in ascertaining whether a given patch is valid, won't cause regressions, etc.
How easy is it? It really doesn't need to involve more than applying a patch and using it. Here's how:
- Select a patch you find interesting. Check the Screenable list for a ticket, and download its patch (listed under Attachments).
- In a temporary directory, clone ClojureScript:
git clone https://github.com/clojure/clojurescript - Go into the
clojurescriptdirectory, and apply the patch you downloaded:git apply ~/Downloads/CLJS-1234.patch - Build the compiler:
script/build - Note the version number, and incorporate it into your build tooling.
You will see output like: [INFO] Building ClojureScript 1.8.123.
If you are using Leiningen, simply update your :dependencies to reflect this version: [org.clojure/clojurescript "1.8.123"].
If your project instead makes direct use of the shipping
cljs.jar, you can make your own by executingscript/uberjarwhich producestarget/cljs.jar.
That's it! Just use the patched compiler. That—in and of itself—is helpful.
Additional Topics
Here are additional things that you can do to further help.
Comment in the relevant ticket with your findings. This is useful, even if things work for you.
Sometimes, when running git apply, you will find that a given patch cannot be applied. This can happen if the ClojureScript codebase has evolved in a way that causes a conflict with the patch. In this case, a comment in the ticket is useful.
If possible, try excersising the patch's fix or enhancement. Use it for a few days to see if it happens to cause any regressions within your project. Run your project's unit tests to see if they still pass with the patched compiler.
If you see something wrong, remember that you are really trying a patched version of master. So, sometimes it is necessary to back up and try using an unpatched build of the ClojureScript compiler in order to tell whether it is the patch that is causing a problem, or if there is simply a regression in master. In the former case, comment on the patch ticket, and in the latter, it may make sense to log a new JIRA ticket.
The above covers applying and testing a single patch. But, if you are going to be “soaking” things, running with a patched version for a while, you can get more bang for your buck by trying multiple patches. To do this, just download the patches, and apply them all at once: git apply ~/Downloads/*.patch.
If you are feeling adventurous, you can actually run the patched compiler's unit tests. This takes a little work to set up, but once done, it is an easy check you can help do.
Look at the code in the patch. It may be difficult to see the specifics of what it is doing, but, then again, you might see something that gives you an idea or two on how to break things. Also, oftentimes this illustrates that it is not that difficult to patch the compiler—maybe it would inspire you to contribute.
I'd say, regardless of what happens, there is a decent chance that you will ultimately see any given patch in some future release, and you will almost certainly see the changes in master. So, one benefit for you is that you get a preview of things—a leg up on knowing whether anything breaks for your setup.
Hope this helps, and inspires you to help in this regard. In my opinion, this is a really easy way for the ClojureScript community at large to make a difference!