Newer
Older
## Requirements
The repository must implement the requirements defined by [MinimalRequirements](./MinimalRequirements.md).
The `ReadMe.md`-file must contain a runtime-dependency-list and a development-dependency-list for the project.
Furthermore the repository must contain the following file with appropriate content:
- [`GitVersion.yml`](https://github.com/GitTools/GitVersion)
- [`<projectname>.code-workspace`](https://code.visualstudio.com/docs/editor/workspaces)
If the source-code of the project is publicly available then also the following file must be contained:
- [`.well-known/security.txt`](https://securitytxt.org/)
A project can contain multiple (but at least one) codeunits.
A codeunit is a compilable part of the project. Small projects may often have only one codeunit, that is no problem. A typical web-application which processes data for example will probably have at least 2 codeunits (e. g. for web-part and backend-part).
Testcases for a codeunit are a mandatory part of the codeunit and are not a further codeunit.
For each codeunit the repository must contain the following files and folder with appropriate content:
- `<codeunit>/Other/QualityCheck/TestCoverage/TestCoverage.xml`
- `<codeunit>/Other/Reference/GenerateReference.py`
- `<codeunit>/Other/Reference/ReferenceContent`
Additional to that there are the following folder which must be git-ignored but must be generated by the scripts listed above:
- `<codeunit>/Other/QualityCheck/TestCoverage/TestCoverageReport`
- `<codeunit>/Other/Reference/GeneratedReference`
`<codeunit>` must be replaced by the name of the codeunit which must be in [Pascal-case](https://www.theserverside.com/definition/Pascal-case).
A merge on the main-branch is only allowed if the scripts `CommonTasks.py`, `RunTestcases.py`, `Linting.py`, `GenerateReference.py` exits with 0 for each codeunit. It is also recommended to run `Build.py` for each codeunit to ensure that the build-script also runs without any errors.
The project's version is defined by the output of `gitversion /showVariable MajorMinorPatch`.
## Further explanations
It is expected that the folder `<codeunit>` contains the source-code of the codeunit including its testcases and (if available) the ui-translations of the project (e. g. `.arb`-files or `.xlf`-files).
If the used programming language provides a specific sourcecode-structure recommended by the maintainer of the programming-language then it is recommended to follow these conventions. This recommendation still applies even the recommendations are contrary to the other regulations described here. The purpose of this is that some programming languages enforce a more or less strictly defined structure. It is often advisable to follow them and sometimes nearly impossible to not follow them. But it is definitely impossible in practice to find two programming languages or frameworks which have exactly the same project-structure, style-guide, etcetera.
The aim of the common project structure is to be flexible and usable for many programming languages and frameworks, no matter what their requirements and recommendations say.Style-mixtures are inevitable when you use different programming languages for frontend and backend (and this is often the case). And this is absolutely fine because on the one hand this is normal and no problem in practice. And on the other hand codeunits should be independent and there is no requirement to adjust the structure and style of a codeunit to another not recommended structure and style.
It is expected that the file `CommonTasks.py` is a python3-script which exits with a non-zero-exitcode if it fails.
This script is supposed to do things like update the version in `<codeunit>.codeunit` or other files of the codeunit.
It is expected that the file `RunTestcases.py` is a python3-script which exits with a non-zero-exitcode if at least one testcase fails. This script does not have to check the minimum test-coverage defined by `<codeunit>.codeunit` (because this is a task of a merge-script).
If something like compiling is required to run the testcases then this script must also do that. These compiled files may not be placed in git-ignored-folder.
This script must generate or update `TestCoverage.xml` and `TestCoverageReport`.
It is expected that `TestCoverage.xml` contains a test-coverage-report of the codeunit in the cobertura-format.
It is expected that after running `RunTestcases.py` the folder `TestCoverageReport` contains a `index.html` containing a html-report about the unittest-coverage based on `TestCoverage.xml`.
The `TestCoverageReport`-folder must be git-ignored.
It is expected that the file `Linting.py` is a python3-script which exits with a non-zero-exitcode if there is at least one linting-issue.
It is expected that the file `GenerateReference.py` is a python3-script which generates or updates the reference based on `ReferenceContent` in `GeneratedReference` and exits with a non-zero-exitcode if at least one error occurs.
The folder `ReferenceContent` must contain a reference for the codeunit. The content of this folder is the source of the `GeneratedReference`-folder.
The `ReferenceContent`-folder must be committed.
It is expected that after running `GenerateReference.py` the folder `GeneratedReference` contains an `index.html`-file (and possibly other files) containing a html-reference of the codeunit based on `ReferenceContent`.
The `GeneratedReference`-folder must be git-ignored.
It is expected that the file `Build.py` is a python3-script which creates the build-artefact of the codeunit for productive usage and exits with a non-zero-exitcode if the build fails for any reason.
The build-artefact must be placed in `BuildArtifact`.
The folder `BuildArtifact` must be git-ignored.
It is expected that the folder `<codeunit>` contains the file `<codeunit>.codeunit` with the following xml-content:
<codeunit:codeunit codeunitspecificationversion="1.0.0" xmlns:codeunit="https://github.com/anionDev/ProjectTemplates" xmlns:schemaLocation="https://raw.githubusercontent.com/anionDev/ProjectTemplates/main/Templates/Conventions/RepositoryStructure/codeunit.xsd">
<codeunit:name>codeunit</codeunit:name>
<codeunit:version>1.0.0</codeunit:version>
<codeunit:minimalcodecoverageinpercent>90</codeunit:minimalcodecoverageinpercent>
</codeunit:codeunit>
The values inside the xml-document must obviously be adapted.
While the project-version-specification is defined by [MinimalRequirements](./MinimalRequirements.md) a codeunit-version is independent of the project version but the rules to change codeunit-versions are the same as the rules for changing the project-version. So a codeunit-version can always be the same as the project-version but it does not have to.