Developer

Join in the Fun

Wow, I'm honored that you are considering helping out with this project. Lets work together - I know we will make something great!

First Steps

• >>> 'Star' the AndHow project in GitHub<<< This raises the profile of AndHow a bit and may help others to become contributors.

• Join the AndHow discussion so you can ask questions and discuss development topics

Contributing

There are lots of ways to contribute to AndHow:

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

• Take on an existing help wanted issue - Start by assigning it to yourself (or indicating that your are working on it in a comment) so we know you have taken it. If you are new to the project, be sure to check out the issues marked good first issue.

• Offer to help write or edit the documentation on this site

• Write tests or improve the Javadocs

• If you want to get involved but don't see an issue that you feel comfortable working on, join the mailing list or Slack channel and ask for a suggestion.

Project Tenets and Development Guidelines

AndHow must use no runtime dependencies. AndHow is intended to be a low level dependency that can be used in any application or other utility. If AndHow has its own set of dependencies, that can lead to version conflicts and bloat 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. Effective test coverage does not mean that test coverage numbers must approach 100%, but the tests should give confidence that the code functions as intended and is capable of catching new bugs.

As a contributor, please:

• Write tests for new functionality

• Write tests for untested code if you are modifying the code

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

Because AndHow operates as an annotation processor at compile time and as a singleton during runtime, there are unique challenges to testing. Caveats aside, the reported test coverage is ~80%, which is lower than it should be - see the list of individual file coverage.

Project Branching Strategy

AndHow uses a slightly modified feature branch strategy for branching. The key thing to remember: After you fork the AndHow project, you will branch off of the main branch and submit pull requests (merge requests) against AndHow's main branch. This is the case even though the main branch is not the default branch for this project.

The key branches are:

main - This is the branch that contains all latest code. When you start a task you start from this branch, and when you submit a pull request it goes to this branch.

[Your Repository]/Issue###-Short-issue-name - This is a feature branch in your repository. When you start work on an issue, pull in the latest code from main to your personal main branch, then branch to create a feature branch with a name like shown. When you complete your work, put in a pull request from your feature branch to main.

homepage - This branch is based at the latest released version and is the default branch displayed when a user visits the AndHow GitHub page. Splitting the homepage branch from the main branch has several advantages:

• The displayed Readme.md file can reflect the current release version, and can be separately updated to display notes or announcements, without putting those changes into the release under development.

• Conversely, new code examples and new best practices that might be put in the Readme.md for the upcoming version can be worked on without affecting what users see.

release - A separate branch for creating a release. It may only be visible during release creation.

[some other feature branches] - One limitation of GitHub is that the project owner cannot create a fork of their own project - the project itself is their 'private' fork. Thus, other feature branches in the project are probably the project owner's because they have no other place to put them :-)

Setting up a development workstation

...is detailed on the New Workstation Setup page