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
Last updated