MASS-Developers Guide

Overview

The instructions in this article are intended primarily for those UWB CSS students actively engaged in MASS core library development. It is assumed that the developer has basic working knowledge of Java application development and Git usage. In particular, all developers should be able to perform the following operations using Git:

Repository cloning
Branching and Merging
Conflict resolution

If you are unfamiliar with one or more of these operations, please consult the following resources:

Prerequisites

You should have the following installed on your development computer:

Java Development Kit 11 (or newer)
A Git client, such as Atlassian Sourcetree
A Java IDE, such as NetBeans, Eclipse, or IntelliJ IDEA
Apache Maven, unless you prefer to use IDE-provided Maven functionality (most modern Java IDEs such as Eclipse, NetBeans, and IntelliJ IDEA provide native Maven functionality built-in)

Working With the Repository

Please observe the following guidelines when working with the repository:

Only commit files that you have created or modified. For example, sometimes an IDE will create workstation-specific configuration files that could cause other people using the same IDE problems when working on this project. If you only commit files that you have created or changed, you avoid adding unrelated files that can cause problems for others. In other words, if you don’t recognize the file as one that you have explicitly modified, do not add it to the repository!
Do not add JARs (or other binary artifacts) to the repository. A source-code revision control system is an inappropriate place to distribute compiled artifacts. Update the Maven POM to include any external resources that are required.
Commit log messages are public! Please refrain from using obscene language, and provide useful comments that indicate what changes the commit represents. Remember, in the future, potential employers or teammates may review your work performed on this project!
As you work, making sure to merge FROM develop INTO your branch periodically to keep your branch updated as other developers conclude their work. It is easier and less error-prone to resolve conflicts in your branch.
Your work should always be performed on a branch from “develop” (new features, enhancements, or minor bugfixes) or “master” (fixing major bugs in a released version). You should not be committing changes directly to the “develop” or “master” branches.
Name your branches in the following manner: ‘--’. For example, your branch might be named: ‘jeckert-develop-mobile_ring_counters’.
Commit and push often. As you commit, add the following text to your commit messages: ‘[#]’. For example, as ‘jeckert’ worked on his mobile ring counters, he might commit a change with the following message: ‘Added a simulator for the 6AV6 triode to improve performance [#7768]’

Coding Standards

There are no formal guidelines as of yet for source code formatting, etc. However, you should follow the following basic guidelines when developing the library:

Make sure all classes and methods include comments documenting what the class represents, what actions the method performs, and so on. All public methods should be commented using “Javadoc”-style guidelines. In particular, the “param”, “return”, “throws”, “author”, and “version” annotations should be provided where appropriate. This list is not all encompassing and a more complete list and guide can be found here. Leaving entries blank may cause warnings when compiling the project, so if you create a Javadoc comment make sure to fill it out completely and fill out blank ones you come across.
Use traditional camel-case naming conventions and package names: https://www.thoughtco.com/using-java-naming-conventions-2034199
Don’t deviate from the tasks you have agreed to work upon. Specifically, don’t modify files unrelated to your work without consulting Dr. Fukuda or a project manager. It is very easy to make conflicting changes that add to the burden of merging updates or introduce bugs into the codebase.

Project Versioning With Maven

Overview

The core library is structured around Maven. MASS-Java takes advantage of the dependency management and build functionality of Maven; Maven will need to be installed on your computer to build a properly functioning JAR. Maven is a popular tool for managing the development and maintenance lifecycle of Java applications; it is recommended that you visit the Maven home site and become familiar with its’ use. In particular, check out the following topics:

(Even if your IDE provides native support for Maven, it is a good idea to understand how Maven works “behind the scenes”)

Installing Maven

Some Java IDEs include Maven (such as NetBeans and IntelliJ IDEA), others may require a plugin. If you decide to use an IDE plugin or native functionality, refer to IDE documentation. For Linux, check to see if there is a installation package available for your distribution. For Windows (and Linux), you may use the ZIP archive available on the Maven home site. If you plan to use Maven from the command line, test your installation using the command “mvn –version”. If the installation is correct, you should see version and environment information returned by Maven.

Building the Library

The project is configured to build when Maven is instructed to execute the “package” build phase. If you are using an IDE plugin or built-in Maven support, refer to IDE instructions for starting the “package” phase. From the command line, “mvn package” executed at the top-level project directory will start the phase. Maven will automatically download any necessary dependencies, compile classes, and create the final JAR artifact. The JAR will be located in the “target” directory; Maven will place the final JAR in this location regardless of the invocation method (IDE, plugin, or command-line).

Invoking Maven will automatically execute unit tests. You may speed up build time (or temporarily work around failing tests) by adding the “-DskipTests” option. For example, to build the library without running unit tests, use the following command: “mvn -DskipTests package”

Version Numbers

Version numbers follow a “major.minor.fix-(RELEASE|SNAPSHOT)” scheme. Major numbers are incremented when significant enhancements are made with (typically) API changes. Minor numbers are incremented when enhancements are made requiring few (if any) API changes. Fix numbers are incremented when bug fixes are made and no API changes introduced.

“RELEASE” and “SNAPSHOT” version types have special meaning to Apache Maven. When somebody using the MASS library for an application specifies a “RELEASE” version, that particular artifact is retrieved from a public repository and not refreshed. If a “SNAPSHOT” version is specified, Maven will refresh the local artifact on the user’s workstation (usually) whenever a new application build is triggered.

It is important that the revision scheme is followed, otherwise the wrong version of an artifact may be used in a project.

Changing Project Version

When updating the version of MASS-Core, you must first determine what the new version will be, including version type. Here are a few examples of proper version numbers:

After performing a hotfix on version 1.2.10-RELEASE: ‘1.2.11-RELEASE’
Starting a new series of minor improvements: ‘1.3.0-SNAPSHOT’
After completing improvements to 1.3.0-SNAPSHOT: ‘1.3.0-RELEASE’

To change the version of MASS-Core, open a command-prompt in the root directory of the project. Enter the following command: ‘mvn versions:set -DnewVersion=’

For example, to change the version to “1.3.0-RELEASE”, the command would be as follows: ‘mvn versions:set -DnewVersion=1.3.0-RELEASE’

After Maven updates the project version, it will create a new file with an extension of “.versionsBackup” in the top-level directory. Once you are satisfied that the version number has been updated correctly, remove this file (do not commit this file to the repository).

Workflow

There are different development activities depending on the nature of the work being performed. In general, there are four different workflows:

Major new feature development or enhancements
Resolving minor issues documented in the issue tracker
Fixing critical bugs in the current released version
Releasing a new version of MASS-Core

The following instructions may refer to the following links:

General Notes

For all workflows, please note the following:

If you are not already working from an issue, create a new issue in the issue tracker that describes in general the work to be performed. The “Kind” of issue will most likely either be “enhancement” or “task”. Make sure to assign yourself as the “Assignee”. This issue will serve as a place to put design documentation, notes, and other such information you feel necessary to document your enhancement. Note the issue number, it will be used later during the development process.
Don’t forget to merge/delete your branch and change the issue status to “Resolved” once your project is complete.

Major New Feature/Enhancement Development

Overview

This workflow is used when major changes are to be made in MASS-Core. Typically a long-running branch will be used for the development activities. #### Workflow Steps 1. Create a new issue or assign an existing issue to yourself 2. Create a branch from “develop” 3. Perform your work on this new branch 4. Merge/delete your branch to “develop” and resolve the issue

Resolving Minor Issues

Overview

Use this workflow when making minor changes in response to an issue in the tracker. #### Workflow Steps 1. Assign the existing issue to yourself 2. Create a branch from “develop” 3. Perform your work on this new branch 4. Merge/delete your branch to “develop” and resolve the issue

Fixing Critical Bugs

Overview

Use this workflow when resolving major bugs in a released version of MASS-Core. #### Workflow Steps 1. Create a new issue or assign an existing issue to yourself 2. Create a branch from “master”. Your branch name should be like: ‘tnicely-hotfix-fdiv-error’. 3. Perform your work on this new branch. Your work in this branch should be confined to fixing the problem ONLY. 4. Once work is complete, increment the minor version in the POM (don’t forget to commit!). 5. Merge/delete your branch to “master”, tag this commit with the new version, and resolve the issue. 6. Switch to the “develop” branch and merge your changes FROM “master” TO the “develop” branch.

Releasing a New Version of MASS-Core

Overview

This workflow is used when it is decided that enhancements to MASS are considered ready to release. #### Workflow Steps 1. Make sure all source code files contain the UW copyright notice, and the year is updated if necessary In the “develop” branch, change the version type from “snapshot” to “release” and update the version number to reflect that nature of the changes since the last release. 2. Commit the updated POM(s). 3. Switch to the “master” branch and merge FROM “develop” TO “master”. 4. Tag this latest commit in the “master” branch with the complete version number. 5. Switch to the “develop” branch and merge your changes from “master” to the “develop” branch. 6. Increment the minor version in “develop” and switch the version type back to “snapshot”.

Make sure to review (or ask for assistance to review) all project documentation to make sure it is still reflects the changes made to the project!