Joshua uses Apache Maven to build, and many of its developers use Eclipse. This page describes how to set up your development environment and contribute code.
Table of Contents
If you are interested in working on Joshua, and are looking for project ideas, a good place to start is by looking at the roadmap for the next release. You can also see the complete list of issues.
Installing Joshua and Dependencies
See the Getting Started page for information on getting Joshua set up.
Many Joshua developers use Eclipse. It is easy to get setup in Eclipse due to its knowledge of Maven projects and Joshua's TestNG test suite.
- Make sure you have set up Joshua, including downloading and installing KenLM, if you want to use that.
- In Eclipse, go to File → Import → Maven → Existing Maven Project. Click Next, then navigate to the root of your cloned Joshua repo. Click OK. Joshua's pom.xml should be selected. Add it to your working set and capitalize it, if you prefer. Click Finish.
- Next, you need to install the TestNG plugin. Go to Help → Eclipse Marketplace. Search for "testng", choose "TestNG for Eclipse", and click Install. Go through the installation procedure, which is straightforward.
Please make sure that you import the Eclipse style formatter.
- Right click on the project name -> Properties -> Java Code Style -> Formatter.
- Activate project specific settings.
- Click on Import, select "eclipse-codeformat.xml" in the root repository of the git directory, and activate it.
We strive to ensure that the code we release on this project works as expected. When making a contribution to the project be sure to run the test suites for the relevant components before submitting your contribution. If you are working with Joshua from source, you should have Apache Maven installed which can can be used to run the unit tests.
cd $JOSHUA mvn test
Creating a Pull Request on Github
Pull Requests via Github are the primary means through which contributions are made to the codebase. We maintain an identical workflow for contributors and committers alike.
Apache Joshua Project on Github: https://github.com/apache/incubator-joshua
Apache Joshua JIRA issue tracker: https://issues.apache.org/jira/browse/JOSHUA/
Prerequisites to Contributing
You will need to fork the project on Github and clone it to your local machine. You will need an account of Github in order to fork the project.
Fork the project
Click the "Fork" button on the top-right side of the project page on Github.
Clone the project
Find the SSH/HTTPS clone URL on the ride side of the page on your forked version of the codebase (www.github.com/<your username here>/incubator-joshua)
Run the following command using the above URL in your terminal.
git clone <ssh/https clone url>
- Create/locate an issue on JIRA and save the Issue Number for later use (i.e. JOSHUA-123).
Create a Branch and name it using the JIRA Issue Number from Step 1
git checkout -b JOSHUA-123
Do your work on the branch and commit your changes. Your code should be compliant with the CodingConventions. Please follow a reasonable set of guidelines when forming your commit message. The short first line summary should include the issue number from JIRA. Please be as consistent as possible with existing commit messages. For instance, we favor using a hyphen as a bullet point in our commit messages. Additionally, please write the messages in the imperative. It is recommended that you setup your editor of choice to handle this formatting for you.
JOSHUA-381 - Remove Incubator references in build.xml - Remove '-incubating' postfix from version number. - Remove '.incubating' from project URL. - Update author email to point to firstname.lastname@example.org
Push your branch to your repo on Github
git push origin JOSHUA-381
- Log into Github and Create Pull Request via:
Be sure to include the ticket number in the title. Ex: "JOSHUA-381 - My PR Title Here" to ensure that everything mirrors correctly to JIRA.
Submitting a Patch
While not the preferred means of receiving contributions (see above), the project also accepts patches posted on a relevant ticket. The first 3 steps from above are the same here. From the branch where you made your commits you can generate a patch with the following:
git format-patch master --stdout > JOSHUA-###-<your name/username>.patch
Post that output file onto the relevant ticket.
Committing to the Master
If you have commit karma on the project be sure to clone the ASF repo found here:
$ git clone https://git-wip-us.apache.org/repos/asf/incubator-joshua.git
Add the project's Github mirror as an additional remote.
$ git remote add github https://github.com/apache/incubator-joshua.git
When a pull request comes in a notification will be posted on the related JIRA ticket (assuming the user followed the above directions). This notification will tell you the pull request number. Fetch the pull request with:
$ git fetch github refs/pull/<pull request number here>/head:JOSHUA-<ticket number here>
Checkout the branch and validate the request (tests work, etc). Checkout master and merge in the changes with:
$ git merge --no-ff JOSHUA-<ticket number here>
When adding the merge commit message be sure reference the pull request number so it is closed properly. For instance, "close #<pull request number here>". Checkout Github's help pages for message formatting help. Publish the changes to the ASF repo with:
$ git push origin master
Click here to see all open JIRA tickets.
If you have any issues with the above workflow, pease contact us on email@example.com.
Lewis John McGibbney
Matt Post DONE