Project Development Information

Repository Structure

build: MsBuild targets, scripts and ressources that are required to get the project to build. These are usually ms build target files, key files to sign the assemblies and scripts for pre or post build steps.
docs: All kinds of documentation. Usually contains a subfolder for the API documentation and one for these development guidelines. See Documentation section for details.
output: A folder used to build released libraries.
scripts: Scripts that ease the creation of the project, documentation or related things. See Scripts section for details.
sources: Code files and project files.
submodules: Other projects that are used to run and/or build the solution which are not provided by NuGet packages. Usually dependencies provided as code rather than binary files.
tests: Test code files and test projects. See Tests section for details.

Documentation

All classes and structures need to be thoroughly documentated. API documentation should be created for all public and protected methods and properties. The documentation needs to be accessible via webbrowser. Documentation is generated out of code comments in order to keep it up to date.

Currently the documentation is generated out of the comments in code using Doxygen in order to make it accessible in a webbrowser. Additionally namespaces are documented in empty code files that can be found in the docs/additional folder. Here each assembly documents the namespaces it contains. Examples should be added to the docs/examples folder and briefly referenced in the code comments. The documentation should also contain the changelog and the readme file as well as this development documentation.

Projects including webservices also need to document their available endpoints.

Scripts

The number of necessary scripts should be kept small and new scripts should only be introduced where there is a real benefit. If possible all scripts should be written in bash in order to be easily execute them on a development system as well as on the CI system. The following scripts exist:

docs-html.sh: Creates HTML documentation out code docs and files in docs.

Tests

All classes and structures need to be thoroughly unit tested. The unit tests should not make use of any external resources but should be able to run independently. They should be designed to be fast and provide an overview of how a class behaves when it's methods are called. Each test should only contain one Assertion if possible.

For each project there should exist a corresponding test project with the suffix ".Tests" containing the unit tests of that project. Failing tests discovered by the CI system should be repaired immediately.

The unit tests can be organized in multiple classes each containing one logical test case with multiple tests. It is also possible to organize the tests in a single class as long as the naming of the methods clearly distinguishes the test cases.

The following pattern can be applied to the name of a test method when using a single test class: Test{NameOfMethodUnderTest}_{TestCase}_{ExpectedTestResult}. Example: TestMethodNaming_AppliedToTestMethod_GeneratesUnderstandableName.

When using one test class per test case each class name should state the case like this: *{ClassUnderTest}_{TestCase}Tests*. Each method should follow the same rules as for a single class but can omit the TestCase part.

For each developed component there should be a component test covering the basic use cases of that component. Component tests should be grouped into separate projects called ComponentTests. Should the need arise to have multiple such projects they should be named according to the test cases they contain a carry the suffix ".ComponentTests".

For most UI components none of these rules apply. They are usually only tested manually.

The unit test framework that is used is NUnit and NSubstitute is used as an isolation framework. NUnit is used for unit tests and for component test.

Release Requirements

When a certain number of features is implemented a new release can be tagged in the version control system. Requirements for a new release are:

The build is stable and all tests are executed successfully on the CI system
Component and Unit tests coverage is sufficient
Documentation is provided for all classes and features
Version number for all assemblies is increased (usually not necessary because the git tags determine the actual version number)

Versioning

The project follows the suggestions of Semantic Versioning. It also follwos the suggestion that there are no breaking API changes until major version 1.

The version of a release consists of a major version, a minor version, a patch version, a revision number and the commit short hash. (major.minor.patch+revision-shorthash). The revision number is generated from the number of commits since the last released version and is usually zero for stable versions. The version is stored as the informational version because assembly and file versions do not support characters which are required to store the short hash. The short hash is omited for the assembly and file versions (major.minor.patch.revision).

During development the major version will stay zero and minor and patch version will serve as marking API breaking changes and pure additions to the API. There is no patch version until major version 1.

Public API

The following is considered the public API for different kinds of projects:

Library: all public classes, methods and properties are considered to be the API
Executable: command line arguments, configuration and data files are considered the API
Web Application: sevice API, command line arguments, configuration and data files are considered the API

CI System

The system building and testing projects is a Jenkins Server that can be accessed at http://ci.norsecorby.de.

Every project needs to specify a Jenkinsfile that contains the pipeline steps for the project to be build, tested and if necessary publish. Generating and publishing documentation should be part of the publish step.

All projects that run inside of docker containers should also include a second Jenkinsfile that is able to build the project and a docker image that is ready to be used.