Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Next, create a new branch for yourself:

Code Block
languagenonebash
$ git checkout -b fixbug42
Switched to a new branch "fixbug42"

...

Code Block
languagenone
$ ./antsetup.sh             # Only needed once in a new Clojure tree, for ant to work
$ ant

# Some prefer to use Maven rather than ant
$ mvn test

As noted in readme.txt, you will need to run ./antsetup.sh as a one-time setup before running ant.  If you want to add new tests, that would be great too. Once you've finished making your changes you need to commit them.

...

Code Block
languagenone
$ git format-patch master --stdout > your-patch-file.diff

Adding patches

Now you can attach that patch file to the JIRA ticket.  In the More Actions menu near the top of the page, select Attach Files.  Please read and follow the recommendations below when writing comments about your attached patch.  Screeners have limited time available for screening.  You are more likely to get your patch approved if you can be as clear as you can, and as efficient with their time as possible.

  • Please use .diff or .patch (not .txt) as a suffix for patch files.
  • Include the file name and date of the patch in any comments referring to it.  It is possible to match up comments with patches based on the date and time, but it is tedious and error prone.
  • To get email whenever the ticket is updated, click on the word "Watch" in the top right area of the page.  This can help you know when someone else comments on your patch, or creates a new one, etc.  Click "Watching" if you want to stop these update emails for that ticket.  You may want to verify that the automated emails get through your spam filter.  Emails will be sent to the address associated with your JIRA account, and will come from the address jira@dev.clojure.org 
  • If you create a new patch that incorporates one or more earlier ones, please combine them all into one patch file, and indicate in your comments that you have done this (with file names and dates of the patches you are superseding).
  • If one of your patches becomes superseded by a later one, consider removing your patch to avoid confusion.  See the instructions under the heading "Removing Patches" below.

...

A stale patch means one that used to apply cleanly to the latest Clojure master version, but due to commits made since the patch was created, it no longer does.  In particular, the output of this command:

Code Block
languagenone
%$ git am --keep-cr -s --ignore-whitespace < patch_file.diff

includes 'Patch failed' and 'To restore the original branch and stop patching, run "git am --abort"'.  You should do the "git am --abort" to get rid of state of the failed patch attempt left behind by the command above.

...

To apply such a patch, the 'patch' program by Larry Wall is extremely useful.  It comes preinstalled with Mac OS X and most Linux distributions.  You can easily install it with Cygwin for Windows.

Code Block
languagenone
%$ patch -p1 < patch_file.diff

The output will give you some hints of whether each "hunk" of the patch file succeeded or failed.  If they all succeed, then likely the only thing wrong with the patch file is that a few context lines were changed.  If any hunks fail, patch creates files ending with ".rej" containing rejected hunks that it did not apply, and you can focus on those as places where the source code likely changed more significantly.  A command like this will find them all:

Code Block
languagenone
%$ find . -name '*.rej'

You will need to look at those rejected hunks, perhaps think about them for a bit to see if and how they still apply, and apply them by hand-editing the source code yourself.

When recreating a new git format patch with:

Code Block
languagenone
%$ git format-patch master --stdout > patch_file.diff

it puts your name and the current date near the top of the file.  If the only changes that you have made are in the context lines, please keep the original author's credit intact by copying the name and date from the original patch that you started from, then upload that.

If you write unit tests where there were none in the original patch, but didn't otherwise modify the original patch, and you would like your name in the commit log for your work, create a separate patch of test additions with your name on it, leaving the original author's name on the updated patch.

Screening a patch

If you are a screener testing a patch, you can create a new branch and apply the patch to start working with it:

Code Block
$ git checkout -b testxyz
$ git am --keep-cr -s --ignore-whitespace < patch_file.diff

And you can throw that branch away when you're done with:

Code Block
$ git checkout master
$ git branch -D testxyz 

How To Run All Clojure Tests

Code Block
$ mvn test

To reduce the duration of the pseudo-randomly generated generative tests from 60 sec down to 1 sec (for example), edit the file src/scripts/run_tests.clj and change the 60000 number.  Just be careful not to include such changes in any patches you submit.

Run An Individual Test

First, build the latest Clojure without running any tests:

Code Block
languagebash
$ ant jar
# If no compilation errors, 'ant jar' creates clojure.jar in Clojure tree root dir

# Or, if you prefer Maven
$ mvn -Dmaven.test.skip=true package
# If no compilation errors, mvn command above creates target/clojure-1.7.0-master-SNAPSHOT.jar

The commands above build a Clojure jar file, but neither compile nor run the tests.

Start a repl and run individual tests from it:

Code Block
# Replace clojure.jar with target/clojure-1.7.0-master-SNAPSHOT.jar if you ran mvn command
$ java -cp test:clojure.jar clojure.main
Clojure 1.7.0-master-SNAPSHOT
;; We're testing with clojure.test 
=> (require 'clojure.test)
nil
;; Load a test file 
user=> (require 'clojure.test-clojure.data)
nil
;; Run it 
user=> (clojure.test/run-tests 'clojure.test-clojure.data)
 
Testing clojure.test-clojure.data
Ran 1 tests containing 17 assertions.
0 failures, 0 errors.
{:type :summary, :pass 17, :test 1, :error 0, :fail 0}   

Start a repl and run a generative test from it:

Generative tests use additional testing jars (installed when you run ./antsetup.sh). Thus, you'll need to have some additional classpath which antsetup.sh will leave in the maven-classpath file. If you are on *nix, the easiest way to leverage this file is:

Code Block
# Replace clojure.jar with target/clojure-1.7.0-master-SNAPSHOT.jar if you ran mvn command 
$ java -cp `cat maven-classpath`:test:clojure.jar clojure.main 
Clojure 1.7.0-master-SNAPSHOT 
;; Load a test file that uses test.generative
user=> (require 'clojure.test-clojure.reader)
nil
;; Load the test.generative runner ns 
user=> (use 'clojure.test.generative.runner)
nil
;; Test a specification on 1 thread for 200 ms
user=> (run 1 200 #'clojure.test-clojure.reader/types-that-should-roundtrip)
{:iter 60, :seed 1255541066, :test clojure.test-clojure.reader/types-that-should-roundtrip}
nil