# 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](#contributing) * [Agile Principles](#Agile-Principles) * [Coding Convention Guide](#Coding-Convention-Guide) * [Build Environment](#Build-Environment) * [Repository Structure](#Repository-Structure) _____ ## Contributing Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms. ### New Issues - Review the [Project Board](../../projects/1) to verify that the issue does not already appear as a project task. - Search the [Issues](../../issues) to determine related issues (epics, dependencies, not yet triaged, ...). - Create a new issue using the "**New Issue**" button on the [Issues](../../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](#agile-principles) outlined for the project (i.e., [working](#working-software), [incremental](#incremental-development), [behavior-driven](#behavior-driven-development), [test-dreiven](#test-driven-development)). - Include supporting documentation as appropriate. - Before initiating a pull request (PR): - [Verify quality](#Quality-Assessment), including adherence to [conventions](#Coding-Convention-Guide). - Build, run, and test a distribution build. - 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](#Project-Specific-Conventions) take precedence. * If no project-specific convention is applicable, use the [Sun Convention](https://www.oracle.com/technetwork/java/codeconvtoc-136057.html) guide. * If something is not covered in the project-specific or the Sun Convention guide, use the [Google Convention](https://google.github.io/styleguide/javaguide.html) 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](https://checkstyle.sourceforge.io) tool and located in the [config/checkstyle](config/checkstyle) directory. - Multiple authors are indicated using multiple @author tags, one tag per line, one author per tag. ### Sun Convention guide - https://www.oracle.com/technetwork/java/codeconvtoc-136057.html ### Google Convention guide - https://google.github.io/styleguide/javaguide.html _____ ## 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](https://www.gradle.org/) Build-automation system using Groovy-based domain-specific language (DSL) ### Quality Assessment #### Unit Testing Framework ##### ✔ [JUnit5](https://junit.org/junit5/) Framework for unit-testing Java code #### Test Coverage Assessment ##### ✔ [JaCoCo](https://www.eclemma.org/jacoco/) Determines code coverage of Java tests #### Source Code Shortcoming Identification ##### ✔ [CheckStyle](https://checkstyle.sourceforge.io/) Identifies violations of coding conventions ##### ☐ [PMD](https://pmd.github.io/) Identifies common programming weaknesses ##### ☐ [SpotBugs](https://spotbugs.github.io/) Identifies bugs and potentially buggy code in Java code; a successor to FindBugs #### Design Complexity Assessment ##### ✔ [JaCoCo](https://www.eclemma.org/jacoco/) Provides complexity analysis of Java source code _____ _The following tools are under consideration for inclusion in the QT4BJ build environment._ #### [Travis CI](https://travis-ci.com/) Continuous integration #### [OpenClover](http://openclover.org/features) Code coverage analysis #### [AccessLint](https://www.accesslint.com/) 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](https://docs.gradle.org/current/userguide/organizing_gradle_projects.html)