How to Contribute

Your first pull request

First, thank you - Let's work together and make something cool!

First Steps

• Star the AndHow project on GitHub. This shameless bit of promotion raises the profile of AndHow a bit and may help others become contributors.

• If you are unfamiliar with the project, read through the home page (4 minute read).

Work from the main branch

• The main branch is the branch to work from: branch from it, make PRs to it

• The homepage branch is the default branch displayed on GitHub

This can be confusing because most projects use main as the default branch, but there are advantages to this structure.

Typical Task / Issue workflow

AndHow uses the typical feature branch repository strategy (aka fork-and-branch), where developers work on a branch in their own repository. Basically:

• Fork the AndHow project on GitHub

• Clone from your fork to your local machine to work on it

• Work on a task in a new branch created just for that task - create the branch from your main

• Submit completed work (or work in progress for review) as a Pull Request to main of the canonical repository

Feature branch names should look like this: Issue123-A-short-name-for-the-issue

If that is all new to you, here is a bit of help with a first git checkout.

Unit Testing

As a contributor, please:

• Write tests for new functionality at or new 100% test coverage

• Write tests for untested code if you are modifying it

...and always feel free to contribute tests for untested or poorly tested code

Code style

• This project uses tabs for indentation. If you are working on a file that is not tab indented, please convert it to tabs (but don't do other files).

• Add complete Javadocs for new methods and classes (other than test classes unless needed)

• Good javadocs comments what and why. We usually don't need comments on how.

More help getting started

Workstation setup is typical for Java development, but there is a New Workstation setup page if you need additional help, or post a question on the forum.

Working well together

One of the joys of a project like this is collaborating with others. Collaboration is more than completing issues, it is discussing ideas, asking questions, learning, discovering something new and cool together. Some ways to help that happen:

• Post Work In Progress (WIP) pull requests and ask for review - its a good way start discussion.

• Ask questions on issues: Is this really the best approach? Does this feature really need to be in this release?

• Take part in the Discussions or the user forum

Project Tenets and Development Guidelines

AndHow must use no runtime dependencies

AndHow is a low level utility that can be used in any application or other utility. If AndHow has dependencies, that can lead to version conflicts when included in other projects. AndHow does have dependencies for testing and at compile time (the tools.jar / jdk.compile module), but none of these are dependencies at runtime.

AndHow must have good quality and effective test coverage

As a low level utility, we don't want user's to have to second guess if it is working correctly. That does not mean that test coverage must be 100%, but the tests should give confidence that the code functions as intended and is capable of catching new bugs.

Part of AndHow is an annotation processor at compile time, so there are unique testing challenges. Caveats aside, the current test coverage (around 87%) should be improved.

Other ways to contribute

• Report a bug or suggest a feature on the issue tracker

• Submit pull-requests to improve the Javadocs or test coverage

• Any corrections or added documentation needed on this site can be opened as an issue on the project.

• Suggest a new example for the AndHow Samples Project