Repository Guidelines

Introduction

This project's repository will be hosted here on GitHub at https://github.com/fracture91/wpi-suite-tng. The repository is structured using the gitflow methodology. All contributors to this project are expected to follow the rules and best practices described below.

Structure

The repository follows the gitflow methodology as described by Vincent Driessen in his January 2010 blog post, “A successful Git branching model”. We will have two main branches in the git repository. They are called dev and master. The dev branch contains the latest changes that will be added to the next release. The master branch contains a tagged revision for each production release. Supporting branches also exist, and for this project they will be called feature and release. A feature branch should be created when adding new functionality and should branch off from the dev branch. Once the feature is fully developed the relevant feature branch should be merged back into the dev branch. A release branch should be created before every production release. The purpose of this branch is to apply finishing touches to the new release while allowing work on the dev branch to proceed with features for the next release.

Master Branch

The release branch should be merged into the master branch only when it is ready to move to production. The revision should then be tagged with the release number.

Rules for committing to the master branch:

1. All commits to the master branch should be the merging back of a release branch that is ready for production.
2. All commits should be tagged with the release number

Dev Branch

The dev branch should branch off the latest production release from the master branch. All development occurs on this branch. When adding a new feature, a new branch should be created off dev. Once work on the feature is complete the feature branch should be merged back into dev. When dev is ready for release, a new release branch should be created that branches off dev. Once the release is ready to move to production, the release branch should be merged back into dev and master branches.

Merges into the dev branch must follow the "Accepting Changes" rules on the Governance page.

Team Branches (temporary)

In order to facilitate cooperation during the MQP, each team will maintain a branch off of the dev branch. These are dev-core and dev-exemplar for the Core team and Exemplar Module team respectively. For each iteration, the teams will work on their own branches to fulfill requirements, pulling in changes from the other team's branch as necessary. Teams can create their own feature branches named dev-core-feature-* or dev-exemplar-feature-*.

At the end of an iteration, changes should be merged into dev as follows:

1. The Exemplar team merges dev-core into dev-exemplar
2. The Exemplar team ensures that tests run and the program is not broken
3. The Exemplar team merges dev-exemplar into dev
4. The Core team merges dev into dev-core at some later point

Feature Branches

Feature branches are used for the development of new functionality or fixing bugs. Feature branches branch off the dev branch. Once the feature has been implemented and is passing all unit tests, it can be merged back into the dev branch (see dev branch merging rules).

Feature branch names should be of the form feature-*

Pushing

Those who have permission to push to the main repository on GitHub must follow the rules below. The master, release, and dev branches must follow these rules strictly. There is some leeway for branches farther away from master, but it is good practice to follow these rules anyway.

Rules for pushing to the main repository:

1. All commits must have an informative commit message in present tense (e.g. "Fix bug in comment editor that prevents adding line breaks")
2. Changes within commits should be focused on a single task. If you're fixing a bug in one file, don't change whitespace in some irrelevant file within the same commit. This is distracting when reviewing commits.
3. Lines should be 110 characters or shorter, except under extreme circumstances

Coding Style

We should look into using code pro for style management.

• If you use a gui-builder for creating a swing gui, you must rewrite its output to be human-readable and understandable
• Indentation
  • Always use tab characters for indentation (no spaces allowed!)
  • Always use spaces for multi-line code alignment
• For non-ternary if statements (ternary if statements are still allowed)
  • always use curly braces
• Curly braces
  • open curly braces should be on the same line as the declaration
  • closing curly braces should be tabbed to match the block declaration start.

Comments

We will be using Javadoc-style Doxygen comments. For each class, a detailed description of the class’ functionality must be provided, including class responsibilities. All methods (public, private, and protected) must have a detailed description. They must also have all parameters noted and described with @param (inc. datatype). Finally they must also have all return values and exceptions noted and described.

Naming Conventions

• Class names
  • upper CamelCase
• Method names
  • camelCase (first letter must be lowercase)
  • Prefix getters with “get”
  • Prefix setters with “set”
• Test cases (JUnit)
  • Prefix with “test”

Method Order

1. Fields
2. Constructors
3. Public Methods
4. Protected Methods
5. Private Methods
6. Getters/Setters