Skip to content

Latest commit

 

History

History
241 lines (190 loc) · 9.52 KB

DevelopmentConventions.md

File metadata and controls

241 lines (190 loc) · 9.52 KB

Quality Tools for BlueJ (QT4BJ) - Development Conventions

This document describes intended and preferred conventions for development and maintenance of the Quality Tools for BlueJ software product.

Contributing

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

New Issues

  • Review the Project Board to verify that the issue does not already appear as a project task.
  • Search the Issues to determine related issues (epics, dependencies, not yet triaged, ...).
  • Create a new issue using the "New Issue" button on the Issues page.
    • Choose an appropriate issue template (e.g., "Bug report", "User Story").
    • Change the title of the issue.
    • Modify the body of the issue in accordance with the template.

Changes

Here is the basic GitHub workflow for this project:

  • Fork the repository.
  • Create a feature branch in your fork.
  • Follow the Agile Principles outlined for the project (i.e., working, incremental, behavior-driven, test-dreiven).
  • Include supporting documentation as appropriate.
  • Before initiating a pull request (PR):
  • Submit a pull request (PR) from your branch.
  • One or more reviewers will review the request and may make comments in the PR conversation.
    • Participate in the conversation associated with the PR, updating your branch as appropriate.
  • After reviewer approval, someone with commit access will merge the PR.

Agile Principles

Working Software

The project code base is always buildable and runnable.

For example, no merge results in a non-buildable state or a buildable product that does not execute.

Incremental Development

The project code base is relevant to the current iteration.

Architectural elements, tests, and implementation code match requirements associated with the current and previous versions of the product.

For example, tests and code for features identified for future versions are excluded from the project code base.

Behavior-Driven Development

All code is associated with an explicit requirement specification (User Story).

Tracing backward from tests reveals the requirement(s) that such tests verify in the product.

Tracing backward from code likewise reveals the requirement(s) that such code implements in the product.

Test-Driven Development

All code is associated with an explicit means for verification.

For example, new code is not merged into the project code base prior to the existence of automated test code for that new code.

Tracing backward from the code reveals the tests used to verify the behavior of the code.

The intent is for code to be developed using a test-first methodology, in which automated tests are written prior to writing the implementation.

Tests associated with successful implementation remains in the code base as regression tests.

(Note: Test coverage tools may facilitate tracing forward from a test to code that the test is intended to verify.)

Coding Convention Guide

Style Convention Precedence and References

  • Project-specific conventions take precedence.

  • If no project-specific convention is applicable, use the Sun Convention guide.

  • If something is not covered in the project-specific or the Sun Convention guide, use the Google Convention guide.

  • If a topic is not covered by any guides, use best judgement and consider opening a project issue to formalize the decision.

Project-Specific Conventions

  • Style conventions are embodied in configuration files for the Checkstyle tool and located in the config/checkstyle directory.
  • Multiple authors are indicated using multiple @author tags, one tag per line, one author per tag.

Sun Convention guide

Google Convention guide

Build Environment

The following tools are established as comprising and contributing to the build environment for the QT4BJ project.
(✔ indicates already integrated into the build environment.)

Build Automation

✔ Gradle

Build-automation system using Groovy-based domain-specific language (DSL)

Quality Assessment

Unit Testing Framework

✔ JUnit5

Framework for unit-testing Java code

Test Coverage Assessment

✔ JaCoCo

Determines code coverage of Java tests

Source Code Shortcoming Identification

✔ CheckStyle

Identifies violations of coding conventions

☐ PMD

Identifies common programming weaknesses

☐ SpotBugs

Identifies bugs and potentially buggy code in Java code; a successor to FindBugs

Design Complexity Assessment

✔ JaCoCo

Provides complexity analysis of Java source code

The following tools are under consideration for inclusion in the QT4BJ build environment.

Travis CI

Continuous integration

OpenClover

Code coverage analysis

AccessLint

Automated web accessibility testing

Repository Structure

.
├── .github/ISSUE_TEMPLATE/  	# Templates for new issues (e.g., user stories, bug reports)
├── archive/                    # Historical artifacts
├── config/                    	# Build configuration
├── docs/                    	# GitHub Pages website content
├── gradle/        		# See Gradle documentation
├── src/                     	# Source files
├── .gitignore                  # Directories and file types to be ignored by git
├── CODE_OF_CONDUCT.md	        # Contributor code of conduct
├── DevelopmentConventions.md	# Development and maintenance conventions
├── LICENSE                     # Open source license file
├── README.md
├── RequirementsSourceInfo.md	# Goals of previous, related project
├── Vision.md                   # Vision statement and stakeholder identification
├── build.gradle                # See Gradle documentation
├── gradlew                     # See Gradle documentation
├── gradlew.bat                 # See Gradle documentation
├── settings.gradle	        # See Gradle documentation
└── toolsForIntegration.md      # List of code analysis tools to be implemented and descriptions

Github Issue Templates

.
├── ...
├── .github
│   ├──ISSUE_TEMPLATE  		
│      ├── bug_report.md       # Bug report template
│      ├── user-story.md       # User story template
│   └── ...                    # etc.
└── ...

Archive

.
├── ...
├── archive                         # Historical artifacts
│   ├── decisionNotes               # Documentation that informed project decision-making
|      ├── AntGradleComparison.md   # Comparison report of Ant and Gradle build tools
│      ├── IvyAntGradleMavenComparisonReport.md     	 
|                                   # Comparison report of Ant, Ivy, Gradle and Maven build tools
│   └──
└── ...

Build Configuration

.
├── ...
├── config                         # Build configuration
│   ├── checkstyle                 # Configuration files for Checkstyle tasks
|      ├── checkstyle.xml          # Checkstyle configuration and specification
│      ├── suppressions.xml        # Checkstyle suppression specification
│   └──
└── ...

GitHub Pages Website

.
├── ...
├── docs                    # GitHub Pages website content	
│   ├── README.md           # Project overview
│   ├── _config.yml         # Jekyll configuration
│   └── ...                 # etc.
└── ...

Gradle Wrapper

├── ...
├── gradle 			# See Gradle documentation
│   ├── wrapper                      # Gradle Wrapper
│      ├── gradle-wrapper.jar        # Gradle packages and distributions
│      ├── gradle-wrapper.properties # Gradle Wrapper configuration
│   └──
└── ...

Source

├── ...
├── src 			# Project source code
│   ├── main    		# Implementation source code
│      ├── java
│         ├── edu/msudenver/bluejext/qualitytools/  # QT4BJ implementation
│   └──
│   ├── test 			# Testing source code
│      ├── java
│         ├── edu/msudenver/bluejext/qualitytools/  # QT4BJ tests
│   └──
└── ...

Gradle structure based on Organizing Gradle Projects