The ref-java-cli community welcomes anyone that wants to help out in any way, whether that includes reporting problems, helping with documentation, or contributing code changes to fix bugs, add tests, or implement new features. This document outlines the basic steps required to work with and contribute to the ref-java-cli codebase.
- Install the tools
- Repository
- Local development
- Proposing the changes
The following software is required to work with the ref-java-cli codebase and build it locally:
- Git 2.2.1 or later
- JDK 17 or later, e.g. OpenJDK
- Apache Maven 3.8.4 or later
See the links above for installation instructions on your platform. You can verify the versions are installed and running:
$ git --version
$ javac -version
$ mvn -version
ref-java-cli uses GitHub for its primary code repository and for pull-requests, so if you don't already have a GitHub account you'll need to join.
Go to the ref-java-cli repository and press the "Fork" button near the upper right corner of the page. When finished, you will have your own "fork" at https://github.com/<your-username>/ref-java-cli, and this is the repository to which you will upload your proposed changes and create pull requests. For details, see the GitHub documentation.
At a terminal, go to the directory in which you want to place a local clone of the ref-java-cli repository, and run the following commands to use HTTPS authentication:
$ git clone https://github.com/<your-username>/ref-java-cli.git
If you prefer to use SSH and have uploaded your public key to your GitHub account, you can instead use SSH:
$ git clone git@github.com:<your-username>/ref-java-cli.git
This will create a ref-java-cli directory, so change into that directory:
$ cd ref-java-cli
This repository knows about your fork, but it doesn't yet know about the official or "upstream" ref-java-cli repository. Run the following commands:
$ git remote add upstream https://github.com/rrajesh1979/ref-java-cli.git
$ git fetch upstream
$ git branch --set-upstream-to=upstream/main main
Now, when you check the status using Git, it will compare your local repository to the upstream repository.
You will frequently need to get all the of the changes that are made to the upstream repository, and you can do this with these commands:
$ git fetch upstream
$ git pull upstream main
The first command fetches all changes on all branches, while the second actually updates your local main branch with the latest commits from the upstream repository.
To build the source code locally, checkout and update the main branch:
$ git checkout main
$ git pull upstream main
Then use Maven to compile everything, run all unit and integration tests, build all artifacts, and install all JAR, ZIP, and TAR files into your local Maven repository:
$ mvn clean install -Passembly
If you want to skip the integration tests (e.g., if you don't have Docker installed) or the unit tests, you can add -DskipITs and/or -DskipTests to that command:
$ mvn clean install -Passembly -DskipITs -DskipTests