You're already reading this page so we can assume that you are a.) using this library for something and b.) interested in contributing somehow. Great!
Open Source projects like this one can't survive without you, the user. We love working on this project, and absolutely want to provide every update and fix that you, our users, want. But we are a small team and can use all the help we can get.
Even if you don't have the time to hack away on this project, there are lots of things you can do to help. Please read through the list in the next section and I am sure you can find something that you have the time to help with.
Great, glad you made it to this section. There are lots of ways that you can help:
If you have any other ideas of how you can contribute feel free to run them by us using the contact information on the Get Help page.
Communication is the key to keeping any good project rolling in the right direction. Anything that is being worked on, Bugs, Feature Requests, Documenation efforts, are all tracked in the JIRA Issue Tracker. This makes sure that everyone is on the same page and that there are no duplication of efforts.
If you want to work on an existing Bug or Feature request, please check the JIRA issue for it and make sure that no one else has already claimed it. Also comment letting everyone know that you want to work on it and ask that the issue be assigned to you (or assign it to yourself if you have the correct permissions).
If you would like to work on an Bug or Enhancement that you have come up with, please log it in the JIRA Issue Tracker and get some feedback first. This make sure that no one else is working on the issue without coordinating on it, and that the issue can be properly tracked and prioritized within the project.
If you have any questions at all please don't hesitate to ask them on the JIRA issue, or using any of the methods listed on the Get Help page. We want to make it as easy as possible to help with the project and also keep the project moving in the right direction.
JavadocWe are strong proponents of well documented code and use Javadoc extensively. The documentation section of this website is built by running the Javadoc tool against this code using the command mvn javadoc:javadoc. Please document any new classes or methods, and make sure to update the comments for any existing code that you update.
User$ git clone git@github.com:[your user]/openshift-java-client.git Cloning into 'openshift-java-client'... remote: Reusing existing pack: 4745, done. remote: Total 4745 (delta 0), reused 0 (delta 0) Receiving objects: 100% (4745/4745), 1.92 MiB | 1.52 MiB/s, done. Resolving deltas: 100% (1475/1475), done. Checking connectivity... done
git remote add upstream https://github.com/openshift/openshift-java-client.git
git config branch.master.mergeoptions --ff-only
git pull --rebase upstream master(--rebase will automatically move your local commits, if you have any, on top of the latest branch you pull from, you can leave it off if you do not). Please note that --rebase is very important if you do have commits. What happens is that when git pull can't fast forward, it does a merge commit, and a merge commit puts the sucked in changes ON TOP of yours whereas a rebase puts them BELOW yours. In other words a merge commit makes the history a graph, and we prefer a cleaner, easier to follow linear history (hence the rebasing). Further once you do a merge commit it will be difficult to rebase the history before that commit (say you want to combine two commits to one later) as described in point 13. Luckily the option set in step 5 will prevent this from happening.
git push
git checkout -b my_cool_feature
git commit -m 'OSJC-XXXX Making this awesome new feature' git commit -m 'OSJC-YYYY Fixing this really bad bug' git push origin my_cool_feature
git fetch upstream git rebase -i upstream/master # if you have conflicts fix them and rerun rebase # The -f, forces the push, alters history, see note below git push -f origin my_cool_featureThe -i triggers an interactive update which also allows you to combine commits, alter commit messages etc. It's a good idea to make the commit log very nice for external consumption. Note that this alters history, which while great for making a clean patch, is unfriendly to anyone who has forked your branch. Therefore you want to make sure that you either work in a branch that you don't share, or if you do share it, tell them you are about to revise the branch history (and thus, they will then need to rebase on top of your branch once you push it out).
git checkout master git pull --ff-only upstream master
git push origin master
If you are using Eclipse or IntelliJ IDEA to work on this project, you will need to create a Maven project, or import an existing Maven project. This will allow the IDE to download the required dependencies, build the project (so that you don't get any nasty errors), and show you the test code coverage if applicable.
All tests must pass before a pull request will be merged. We also require that all new code, such as Feature Requests be covered by tests. Tests are written using the junit 4.x framework and are located in the src/test/java directory. We also use the fest assertions (https://code.google.com/p/fest/) to take advantage of more expressive verification-(assertion) statements. We have both unit tests and integration tests. The unit tests do no remoting, they use pre-recorded answers that you may find in src/test/resources/samples/. To fake server responses we use mockito and mock the http-client we're using in the openshift-java-client (HttpClientMockDirector):
public HttpClientMockDirector mockGetAny(String response) throws
SocketTimeoutException, HttpClientException {
when(client.get(any(URL.class), anyInt())).thenReturn(response);
return this;
}
The tests are all in src/test/java. We name unit tests XXXTest.java and integration tests XXXIntegrationTest.java so that one immediately knows if the test is talking to the backend or not.
You can either run the tests using your IDE or run the mvn clean verify -Pintegration-tests command in your terminal inside of the project directory that you cloned with git. The integration tests take quite awhile to run so be patient.
You can also run mvn clean verify -DshowTestTimes or mvn clean verify -Pintegration-tests -DshowTestTimes to show the name of each test and how many milliseconds it took to run.
If you would like to single out a specific test to run (maybe one you are currently working on writing) you can do the following:
mvn -Dtest=APIResourceTest testmvn -Dtest=APIResourceTest#shouldLoadListOfStandaloneCartridges testmvn -Dtest=APIResourceTest test -DshowTestTimesYou can read more about running specific tests here.
To build the library, run the mvn clean package command in your terminal inside of the project directory that you cloned with git. This will create a new directory called target that will contain all of the compiled class files along with a JAR file, and a sources.JAR file for use in your projects.
You can also run the command mvn clean install which will install the library in your ~/.m2 directory. You can then include the library in your project by adding the correct configuration to your pom.xml such as:
<dependencies>
<dependency>
<groupId>com.openshift</groupId>
<artifactId>openshift-java-client</artifactId>
<version>2.5.1-SNAPSHOT</version>
</dependency>
</dependencies>
When you are testing locally it is Maven convention to use version-SNAPSHOT for any non-finalized versions. Also remember to increment the minor or major version depending on the scale of the changes you have made to the source code.
Just as important as adding new features and fixing bugs is helping others figure out how to use this library in their own projects. That is where this website and the documentation section comes into play. If you notice an error on this website or have some knowledge that would be useful to others? Have some extra time to document a method?
We use Awestruct for this website and the documentation. Most of it is static HTML/CSS with Awestruct handling the templates (header, footer, navigation, etc).