Introduction

This project's repository will be hosted here on GitHub at https://github.com/struct-by-lightning/wpi-suite. 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 four main branches in the git repository. The first are called dev and master, and are from the original wpi-suite repository. These are not to be touched. The other two main branches are sbl-dev and sbl-master. The sbl-dev branch contains the latest changes that will be added to the next release. The sbl-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.

SBL-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 sbl-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

SBL-Dev Branch

The sbl-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 sbl-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 sbl-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.

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

The keyword here is DON'T, unless you are the release engineer. You all have the power to push to the team repository so that you can edit the wiki. Don't abuse it by messing with the repository itself.

Coding Style

Process Engineer, update this to what you want

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