* [Overview](#overview)

* [Before Making Your Pull Request](#before-making-your-pull-request)

* [Contributing With Minimal Setup](#contributing-with-minimal-setup)

* [Getting Familiar With the Codebase](#getting-familiar-with-the-codebase)

* [The `exercises` Module](#the-exercises-module)

* [The Problem Submodules](#the-problem-submodules)

* [Advanced: Complete Local Setup](#advanced-complete-local-setup)

* [Tip: `gradle clean` before `exercism fetch`](#tip-gradle-clean-before-exercism-fetch)

This guide covers contributing to the Java track. If you are new, this guide is for you.

If, at any point, you're having any trouble, pop in the [Gitter exercism/java room](https://gitter.im/exercism/java) or the [Gitter exercism/dev room](https://gitter.im/exercism/dev) for help.

One last thing to note before you get started. When you fork the repository and you want to sync your fork, you can perform a [`git rebase`](https://git-scm.com/docs/git-rebase). This is preferred over merging the changes because merging leads to a dirty commit history whereas performing a rebase adds in those changes without making extra commit messages. However, this is only preferred, so don't worry about it too much.

First things first: by contributing to Exercism, you are making this learning tool that much better and improving our industry as a whole... thank you!!!

To submit a fix for an existing exercise or port an exercise to Java with the least amount of setup:

1. **Ensure you have the basic Java tooling installed:** JDK 1.8+, an editor and Gradle 2.x.

(see [exercism.io: Installing Java](http://exercism.io/languages/java/installing))

- **Setup a branch on a fork of [exercism/java](https://github.com/exercism/java) on your computer.**

See [GitHub Help: Forking](https://help.github.com/articles/fork-a-repo/). Use those instructions (in conjunction with the [Git Basics doc](https://github.com/exercism/docs/blob/master/contributing-to-language-tracks/git-basics.md)) to:

* "fork" a repository on GitHub;

- install `git`;

- "clone" a copy of your fork;

- configure an "upstream remote" (in this case, `exercism/java`);

- create a branch to house your work

- **Write the codes.** Do your work on that branch you just created.

The [Getting Familiar With the Codebase](#getting-familiar-with-the-codebase) section, below, is an orientation.

- **Commit, push and create a pull request.**

Something like:

```

```

The Git Basics doc has a section on [commit messages](https://github.com/exercism/docs/blob/master/contributing-to-language-tracks/git-basics.md#commit-messages) that provides practical advice on crafting meaningful commit messages.

- **Verify that your work passes all tests.** When you create a pull request (PR), GitHub triggers a build on Travis CI. Your PR will not be merged unless those tests pass.

There are two objectives to the design of this build:

1. when a problem is built from within the `exercism/java` repo (i.e. when you, the contributor, are developing the exercise), the tests run against the "example" code;

2. when a problem is built outside the `exercism/java` repo (when a participant is solving the exercise), the tests run against the "main" code.

This repo is a multi-project gradle build.

This is the top-level module, contained in the `exercises` directory. It is a container for the problem sub-modules.

* its `build.gradle` points the "main" sourceset to the example code.

* its `settings.gradle` names each of the subprojects, one for each problem in the set.

The `exercises` subdirectory contains all of the problem submodules.

Each problem/submodule is a subdirectory of the same name as its slug.

* its `build.gradle` names dependencies required to work that problem.

Each problem/submodule has three source sets:

* `src/test/java/` — a test suite defining the edges of the problem

* `src/example/java/` — an example solution that passes all the tests

* `src/main/java/` — starter source files, if required/desired *(this directory usually only has a `.keep` file in it)*.

If you are going to make significant contribution(s) to the track, you might find it handy to have a complete local install of exercism on your computer. This way, you can run the full suite of tests without having to create/update a PR.

The easiest way to achieve this is simply use the `bin/journey-test.sh` script. However, you may want to perform other tests, depending on what you are doing. You can do so by duplicating the setup performed by the `bin/journey-test.sh` script.

If you `exercism fetch` after doing a build, the CLI will fail with the following error message:

and if you review the logs of your x-api, you'll find:

This is because some files generated by the build can't be served from the x-api. This is by design: the CLI does not serve binaries. To fix this, simply make sure you do a clean in your `exercism/java` repo before you fetch: