Join Us

Why Should I Help?

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.

Ok, You Convinced Me. How Can I Help?

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.

Project Best Practices

Communication

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.

Javadoc

We 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.

Getting The Code and git Best Practices

  1. Create an account on github if you don't already have one at github.com.
  2. Fork the OpenShift java Client project to your github account.
  3. Clone your newly forked repository into your local workspace
    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
  4. Add a remote ref to upstream for pulling future updates
    git remote add upstream https://github.com/openshift/openshift-java-client.git
  5. As a precaution, disable merge commits to your master branch
    git config branch.master.mergeoptions --ff-only
  6. To pull later updates from the upstream
    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.
  7. Push the pulled updates to your fork of openshift-java-client on github
    git push
  8. Make sure there is a JIRA logged for your Bug Fix or Feature Request that you are working on here.
  9. Create a simple topic branch to isolate that work (just a recommendation)
    git checkout -b my_cool_feature
  10. Make the changes and commit one or more times (Don't forget to push)
    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
  11. Rebase your branch against the latest master (applies your patches on top of master)
    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_feature
    The -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).
  12. Get your changes merged into upstream
    1. Make sure your repo is in sync with other unrelated changes in upstream before requesting your changes be merged into upstream by repeating step 11.
    2. Send a github pull request, by clicking the pull request link while in your repo's fork
    3. As part of the review you may see an automated test run comment on your request. Currently this link can only be viewed by Red Hat employees, but if you request a copy we can send you one. In the future we hope to make this public
    4. After review a maintainer will merge your patch, update/resolve issues by request, and reply when complete
    5. Don't forget to switch back to master and pull the updates
      git checkout master
      git pull --ff-only upstream master
    6. To update the master branch of your github repository (otherwise you will see a message like 'Your branch is ahead of 'origin/master' by XXX commits.' if you are use 'git status' on your local master branch.
      git push origin master

Setting Up Your IDE

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.

Writing Tests

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.

Running the Tests

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:

You can read more about running specific tests here.

Building the Library

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.

Updating this website and adding documentation

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?

Now just sit back, relax, and give yourself a high five while we review your change and merge it. We'll let you know if we have any questions or something in your change needs to be corrected.

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).

Thanks

A special thanks to the WildFly team for putting together this page which was the inspiration for the git tips listed here.