Developer guide

Contributing to RedDeer

Contributions to RedDeer are welcomed. There are few tasks which have to take place before submitting a commit to RedDeer. First one is importing RedDeer to your workspace in Eclipse. Second one is processing your commit as a pull request. Please follow and respect this workflow to let your commit be merged to RedDeer successfully.

Content:

• Build RedDeer from command line
• Import RedDeer to Eclipse
• [Submit a contribution] (Developer-guide#submitting-a-contribution)
• Top reasons why PR is not accepted
• Contribution workflow/process

Building RedDeer from command line

To build RedDeer from command line you will need maven, java and git. Once you have installed maven on your system, update settings.xml to contain JBoss Nexus repo:

<settings>
    <profiles>
        <profile>
            <id>jboss-maven-repos</id>
            <repositories>
            <repository>
                <id>jboss-releases</id>
                <url>https://repository.jboss.org/nexus/content/repositories/releases</url>
                <releases>
                    <enabled>true</enabled>
                </releases> 
            </repository>
            <repository>
                <id>jboss-snapshots-repository</id>
                <url>https://repository.jboss.org/nexus/content/repositories/snapshots/</url>
                <snapshots>
                    <enabled>true</enabled>
                </snapshots> 
            </repository>
        </repositories>
        </profile>
    </profiles>
    <activeProfiles>
        <activeProfile>jboss-maven-repos</activeProfile>
    </activeProfiles>
</settings>

Once you have properly configured you environment you can build RedDeer with following commands:

git clone https://github.com/jboss-reddeer/reddeer.git
cd reddeer
mvn clean install -DskipTests

This will run maven build of RedDeer and skip running tests. To ensure that even javadoc is correct, run mvn javadoc:aggregate command. If you want to run tests to be sure that everything is working, remove argument -DskipTests from the maven command above.

Import RedDeer to Eclipse

Right before start of developing RedDeer it is necessary to import RedDeer source code to Eclipse workspace. At first fork RedDeer repo, clone your RedDeer git repository and add remote upstream git@github.com:jboss-reddeer/reddeer.git. Once its done import RedDeer source code to Eclipse as maven project. When import is done, prompt install additional plugins is shown. Install all those following plugins to your Eclipse:

• maven-clean-plugin
• tycho-compiler-plugin
• tycho-packaging-plugin

There are more steps to be completed before starting contributing to RedDeer:

• Install SWTBot to Eclipse from http://download.eclipse.org/technology/swtbot/releases/latest/ to your eclipse
• Install latest Graphiti to Eclipse from one of the update sites found at https://eclipse.org/graphiti/download.php
• Install mockito plugin to Eclipse
• Go to http://download.eclipse.org/tools/orbit/downloads
• Select latest build and use update site of Orbit Build Repository
• In Eclipse Install New Software... select testing bundle and install it to your Eclipse

Submitting a contribution

Now you are ready to create a contribution. Select an existing issue or create your own if you have found any place for improvement. Create a new branch for this issue. If commit is changing API or there is a new feature, add "update_doc" label to the issue and create and link a new issue labeld with "doc" label to this one. There should be precisely one commit per issue and commit message should reflect to which issue it belongs. Remember to use descriptive message of commit, what does it really solve. Example of commit message:

"Fixes select method of TreeItem (fixes #12345)".

Once the commit is pushed to your branch, convert issue to pull request using hub from command line: hub pull-request -i 12345

Most often issues preventing code from being accepted

1. Code doesn't fix the problem.
2. Missing tests.
3. Missing javadoc for all public members for API (for tests and tooling it is optional)
4. Duplicated code.
5. Missing related doc issue if it is needed.
6. Multiple commits in the PR.
7. Multi-purpose PR or PR with additional source code re-formatting.
8. Commit message is missing "(fixes #ID)" or similar acceptable reference to the issue.

Standard code contribution work flow steps

1. (D) issue is created and assigned to developer (https://github.com/jboss-reddeer/reddeer/issues/) or taken by a contributor if there is no assignee.
2. (D) pull request is created/updated and linked to the issues (https://github.com/jboss-reddeer/reddeer/pulls).
3. (D) If PR affects documentation, another issue referenced from the original one should be created and labeled with "doc" label. Original issue should have "update_doc" label.
4. (A) verification job is triggered automatically.

• If you want to run verification job again, add comment "testPR"

1. (D) when verification job is OK then add rev_ prefix.
2. (GK) pull request is reviewed ([gatekeeper]_ prefix is added).

• (D) If something is wrong with PR, prefix is removed, developer has to take care of it. Changes should be amended in previous commit. Go back to step 4.

1. (GK) pull request is pushed to master (https://github.com/jboss-reddeer/reddeer/commits/master).
2. (GK) issue is closed and [gatekeeper]_ prefix is removed.
3. (D|GK) Whoever closes issue without applying PR must add reason of doing so.

Standard documentation contribution flow steps

1. (D) Doc issue is created and assigned to developer.
2. (D) Once doc/wiki page is created/modified review_required label is added. Doc/wiki page is waiting for a review.
3. (DR) Doc/wiki page is reviewed ([docReviewer]_ prefix is added).
4. (DR) If there is still some work to do, [docReviewer]_ prefix and review_required label are removed. Go back to step 2.
5. (DR) [docReviewer]_ prefix is removed and issue is closed.

Legend

• D - developer/contributor
• A - automated (jenkins, etc.), no user action is required
• GK - gatekeeper (PR reviewer)
• DR - Documentation reviewer