- Contributing
This guide covers contributing to the Java track. If you are new to the Exercism Java track, this guide is for you.
If, at any point, you're having any trouble, pop in the Exercism forum for help.
For general guidelines about contributing to Exercism see the Exercism contributing guide and Contributing via GitHub.
Hi! Thanks for contributing to the Exercism Java track!
Before opening your pull request, please review the track policies and make sure your changes comply with them all. This helps us focus our review time on the more important aspects of your contributions.
Also, please only address one issue per pull request and reference the issue in your pull request. This makes it easier for us to review it, and it means that if we request changes to the fix for one issue, it won't prevent to a fix for another issue being merged.
It's perfectly fine to have more than one pull request open at a time. In that case it's important to keep the work for each pull request on a separate branch to prevent unrelated commits being added to your pull request. This is good practice to do always, even if you only have one pull request open.
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
.
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, so thank you!
To submit a fix for an existing exercise or port an exercise to Java with the least amount of setup, follow these steps.
Make sure you have the latest Java tooling installed on your computer, see exercism.org: Installing Java.
Also make sure you have git
installed on your computer.
Create a fork of the exercism/java repository in your GitHub account, see GitHub Help: Forking.
Clone the fork you created to your computer using git
, and create a new branch from the main
branch to start working on your contribution.
The Getting Familiar With the Codebase section will help you get familiar with the project.
After making changes to one or more exercises, make sure that they pass all validations. Run the following commands from the root of the exercise directory.
./gradlew test
./gradlew check
./gradlew compileStarterTestJava
When you finished your changes and checked that all validations have passed, it's time to commit and push them to your fork:
git add .
git commit -m "(An intention-revealing commit message)"
git push -u origin your-branch-name
Then, open a Pull Request on the exercism/java repository. Check out the Contributors Pull Request Guide for some guidelines on what we expect in a Pull Request.
After opening a Pull Request, one of our maintainers will try to review it as soon as they are available. They will also trigger the GitHub Actions workflows which will build and test the project. Your Pull Request will not be merged unless those workflows pass.
IntelliJ IDEA is one of the more popular IDEs when working with Java, and it includes several tools to help simplify the process. The following steps outline how to import the git repository, make changes, and push them back to your fork.
Open the IDE, and from the startup menu select "Check out from Version Control". This will open a dialog where you can enter the URL of your fork repository and specify the directory that you would like to clone the repo into.
Select "Import Project from External Model" and click the "Gradle" radio.
Set the Gradle properties per the screenshot below. Ensure that the "exercises" folder is selected as the root of the project
Add the java
folder as a module.
Open the project settings and view the modules.
Click the +
button, select "Import Module".
Select the java
directory and accept the default values.
The git tools in IDEA are located in the VCS menu. To create a new branch, select VCS > Git > Branches and then click "New Branch". Give the branch a meaningful name and create.
Each exercise will have gradle tasks that can be executed from the IDE.
To test changes within an exercise, find the gradle task for that folder in the "Gradle" toolbar on the right, open the Tasks > Verification folder and double click test
.
Once all the changes have been made, you can look at the diffs and commit from the "Commit File" window, which can be reached by selecting VCS > Git > Commit File from the top menu. If all the changes are acceptable, checkmark all the files that are to be committed, enter a meaningful commit message, and then click "Commit and Push".
After pushing your changes, Open a Pull Request to contribute them to the Java track.
NOTE: Git and gradle commands can still be run in the command line when using and IDE. The steps outlining how to perform using IDE tools are for convenience only.
There are two objectives to the design of this build:
- 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 reference solution; - 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 submodules.
- its
build.gradle
points the "main" sourceset to the reference solution. - its
settings.gradle
names each of the subprojects, one for each problem in the set.
The exercises
subdirectory contains all 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. - its
README.md
describes the exercise.
Each problem/submodule has three source sets:
src/test/java/
— a test suite defining the edges of the problem.meta/src/reference/java/
— a reference solution that passes all the testssrc/main/java/
— starter source file(s).
Please read Implementing a Concept Exercise.
Please read Contributing to Practice Exercises.