New Workstation Setup

Reference workstation platform

Main development has been done on this platform:

• Java JDK 1.8 - JDK 16

• Any IDE that works well with Maven

• Maven 3.5 (min 3.2.2 required)

• Git 2.8.1 or better

• A Github account is required to submit pull requests to merge you code changes into the canonical repository

MacOS 10.13 was used as the OS, but this is not an actual requirement. Linux and Windows systems should work but are untested.

Any current JDK (1.8 - 16) is capable of building AndHow. Java JDK8 is a requirement for building a release or snapshot. The 1.8 requrement is due to Jigsaw, introduced in JDK9, which allows modularization of the JDK and applications. AndHow depends on the JDK tools.jar, which was removed in JDK9 and replaced with the jdk.compile module. The add-modules mechanism of JDK9 forces the built jar to be Java9 compatible - its not possible to compile with JDK9, add a module and build a Java8 compatible jar.

Fret Not! The resulting JDK8 AndHow jar can be used in Java9 and newer projects, so this limitation only affects development of AndHow itself, not projects that use it.

Any IDE can be used to develop AndHow. Some free options are:

• Netbeans 12.4

• IntelliJ CE

• Eclipse

Netbeans is now an Apache project and works very well with Maven, but is a bit rough. IntelliJ Community Edition is very polished, but struggles with Maven a bit, though, this is mostly an issue when changing module structure. Eclipse... I haven't used for several years.

Maven 3.5 or newer is a requirement. Any recent version of Maven will work. Maven provides dependencies and build scripting for this and many other Java projects.

Git 2.8.1 is a requirement, though any recent version will work. Git is the source code management system for this project and is in wide use.

Checking out the code

AndHow development follows a typical fork-and-branch aka fork-and-pull workflow. The basics of that are:

• As a developer, you will have your own private fork of the AndHow project on GitHub

• You will clone code from your fork to your local machine

• Work for each task/feature/bug fix is done in a new branch just for that task

• Completed work is submitted for review via creating a pull request, requesting that changes from a development branch be merged into the canonical repository.

If this workflow is new to you, there are lots of good write-ups on the topic. Assuming you have already forked AndHow, here is the quick version of getting a local copy ready for development:

> git --version

git version 2.15.2 [Or something similar]

> git clone https://github.com/[your user name]/andhow.git

Cloning into 'andhow'...

remote: Counting objects: 10545, done.

remote: Compressing objects: 100% (73/73), done.

remote: Total 10545 (delta 19), reused 60 (delta 7), pack-reused 10445

Receiving objects: 100% (10545/10545), 13.

> cd andhow

> git remote add upstream https://github.com/eeverman/andhow.git

Building the Code

If your local environment is setup correctly, you should be able to build the code like this:

> mvn --version

Apache Maven 3.5.2 (...)

Maven home: /usr/local/Cellar/maven/3.5.2/libexec

Java version: 1.8.0_152, vendor: Oracle Corporation

Java home: /Library/Java/JavaVirtualMachines/jdk1.8.0

> mvn clean install

...A whole bunch of messages...

[INFO] ------------------------------------------------------------------------

[INFO] BUILD SUCCESS

[INFO] ------------------------------------------------------------------------

[INFO] Total time: 36.001 s

[INFO] Finished at: 2018-09-09T20:24:58-05:00

[INFO] Final Memory: 38M/399M

[INFO] ------------------------------------------------------------------------

If you get to [INFO] BUILD SUCCESS, you win! Looking in the [project-root]/andhow/target directory, there should be a andhow-0.x.x-SNAPSHOT.jar file, which is your newly build jar file.

Doing your first task

To actually do work, start by creating a new branch. By convention for this project, branches are named based on the issue number and (optional but helpful) a short keyword description. If you were working on issue 348, you might name the branch Issue348-ValidatedValue-unused-code, eg:

git checkout -b Issue348-ValidatedValue-unused-code

While working on your task, you should regularly commit your changes, pull in updates from upstream and push your changes to your fork.

Later, when your work is complete or you are just ready for a review of your work in progress, submit a pull request from your branch. Be sure to add something like this to the description:

Blah blah blah, lots of changes...

Fixes #348

With the 'Fixes' comment, GitHub will auto-close the associated ticket when the pull request is merged.

Join the Discussion

Don't forget to join the AndHow Slack discussion.

Happy Hacking and Thanks!

If you've read this far, you've earned several bonus points and a seat at the head of the table. Any and all help is appreciated and I look forward to hearing from you!