|
AuthenticationService
v0.2.0
|
MsBuild targets, scripts and ressources that are required to get the projrct to build. These are usually ms build target files, key files to sign the assemblies and scripts for pre or post build steps.
All kinds of documentation. Usually contains a subfolder for the API documentation and one for these development guidelines. See Documentation section for details.
A folder generated by the deployment scripts. The scripts put the build artefacts into this folder.
All the NuGet packages that are required.
Scripts that ease the creation of the project, documentation or related things. See Scripts section for details.
Code files and project files.
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.
Test code files and test projects. See Tests section for details.
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.
Scripts are currently separated into two groups distinguishable by their prefixes. The scripts in each group often rely on each other in order to work without prerequisites.
A simple script that will restore all missing NuGet packages for the solution. Requires NuGet to be installed in */usr/lib/nuget/*.
Builds the solution in release configuration. The script relies on build-get-nuget-packages.sh to retrieve the missing NuGet packages before the build.
Builds the solution and copies the resulting binaries to the output folder. Each project will be copied to an individual folder. The script relies on build.sh to build the solution.
Builds the solution and creates a zipped package tar ball of the binaries. The resulting framework.tar.gz archive has the same structure as the output folder created by build-output.sh.
Creates and updates the XML documentation files which can be used to document the API. The script requires a successful release build. When using this script keep in mind that monodoc also writes assembly versions into the documentation files. The assembly versions in the documentation files should always reference a stable build.
A convenients script which builds the solution and updates the XML documentation files. This is a shorthand for running build.sh and docs-update.sh.
Creates HTML documentation out of the XML documentation files.
Creates a zipped package tar ball of the HTML documentation. The resulting framework-api-html.tar.gz is created in the output folder.
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. Each of these unit test projects need to be registered in a nunit project file in order to be executed by the continuous integration system. 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. Use cases are usually grouped in a separate project 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 ussually not tested.
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.
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 version of a release consists of a major version, a minor version, a revision number and the commit short hash. (major.minor-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.revision).
1.8.13