Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/quantummaid/quantummaid-opensource-parent
Contains the Java quality standards for QuantumMaid projects.
https://github.com/quantummaid/quantummaid-opensource-parent
architecture checkstyle ci-cd ddd java maven quality-assurance
Last synced: 3 months ago
JSON representation
Contains the Java quality standards for QuantumMaid projects.
- Host: GitHub
- URL: https://github.com/quantummaid/quantummaid-opensource-parent
- Owner: quantummaid
- License: apache-2.0
- Created: 2019-12-12T15:37:38.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2021-05-15T12:26:17.000Z (over 3 years ago)
- Last Synced: 2023-12-20T06:57:20.536Z (about 1 year ago)
- Topics: architecture, checkstyle, ci-cd, ddd, java, maven, quality-assurance
- Homepage: https://quantummaid.de
- Size: 208 KB
- Stars: 5
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/quantummaid/quantummaid-opensource-parent)
[](https://maven-badges.herokuapp.com/maven-central/de.quantummaid/quantummaid-opensource-parent)
[](https://github.com/quantummaid/quantummaid-opensource-parent)
[](https://opensource.org/licenses/Apache-2.0)
[](https://quantummaid.de/community.html)
[](https://gitter.im/quantum-maid-framework/community)
[](https://twitter.com/quantummaid)
# quantummaid-java-standards
Contains the Java quality standards for QuantumMaid projects.
## Usage
Replace the top section of your `pom.xml` with the following:
```xml
4.0.0
de.quantummaid
quantummaid-opensource-parent
0.9.24
```
Also make sure that the `README.md` of the project clearly recommends the usage of the `pgpverify-maven-plugin` by
providing the link . It can be found under
(usage instructions).
## Checkstyle
Checkstyle is enabled after using this POM as parent in a Maven project. It is executed before tests are run.
### Registering Checkstyle suppressions
Add the following to your `pom.xml`:
```xml
4.0.0
...
...
${project.basedir}/src/test/checkstyle/checkstyle-suppressions.xml
...
```
Create a suppression configuration file under `/src/test/checkstyle/checkstyle-suppressions.xml` with the
contents of your choice based on the following example:
```xml
```
The checkstyle step can be skipped for a run with `-Dcheckstyle.skip`.
### IntelliJ IDEA integration
Install the CheckStyle-IDEA plugin. Afterwards, open `Settings -> Other Settings -> Checkstyle` and add a new Checkstyle
configuration file, name it `QuantumMaidOpenSource` and use
as a URL location.
## Spotbugs
Spotbugs is enabled after using this POM as parent in a Maven project. It is executed before tests are run.
### Registering Spotbugs exclusions
Add the following to your `pom.xml`:
```xml
4.0.0
...
...
${project.basedir}/src/test/spotbugs/spotbugs-exclude.xml
...
```
Create a suppression configuration file under `/src/test/spotbugs/spotbugs-exclude.xml` with the contents of your
choice based on the following example:
```xml
```
More information about exclusions can be found on the [spotbugs website](https://spotbugs.readthedocs.io/en/stable/filter.html#examples).
### IntelliJ IDEA integration
Install the Findbugs-IDEA plugin.
## Compiler
The compiler is configured for all child projects and should not be modified in any of the child projects of this POM.
Following this recommendation provides child projects with the following benefits:
- Encoding and Java version of the sources and compiled classes are managed
- A configuration bug fix, that will prevent the maven-compiler-plugin from swallowing compilation errors and hence
failing with 'unknown compilation error'
- Building the child project in Intellij IDEA will be possible with warnings
- Building the child project using maven will be possible with warnings, if built with `-DskipTests=true`
- Testing the child project using maven will be possible with warnings, if built with
`-Dmaven.compiler.failOnWarning=false`
- Building/Testing the child project will fail, if the source code is causing compiler warnings
- Releasing the child project will fail, if the source code is causing compiler warnings
## Skipping tests
Just run the Maven command with `-DskipTests=true`.
## Long running tests, that should be executed before every release, but not on every verify
Surefire will set a system property `testMode` to either `NORMAL` or `RELEASE` depending on the active profile.
In the test, an `if` statement can be used:
```java
final Boolean runThisTest = Optional.ofNullable(System.getProperty("testMode")).map(s -> s.equals("RELEASE")).orElse(false);
if (runThisTest) {
//test you long running stuff
} else {
System.out.println("Skipping this test, since system property testMode is not set to RELEASE");
}
```
## Releasing a version to Maven Central
The problem with releasing to Maven Central using a CI/CD pipeline is complicated, since both, the nexus staging account
and the gpg key must be kept private. If an attacker gains access to one or both of these credentials users of
our open source products are in grave danger (). A bitbucket pipeline can output
secure environmental variables with some neat tricks. Since we would need to store both valuable credentials as such,
that operation can only be done manually outside the GitHub cloud environment:
* Ensure the gpg private key with the id `0xACB977BA5C6D5C6E` installed in the gpg key store.
* Ensure the maven settings.xml file contains the following section:
```xml
...
quantummaid.opensource.sonatype.staging
the username of the sonatype nexus staging account
{the encrypted password of the Sonatype nexus staging account created using mvn --encrypt-password}
...
```
* Ensure the project version has been set to the appropriate value
* Run the following command to test the project:
```bash
mvn clean verify
```
* run the following command to release the project in case the tests passed:
```bash
mvn -DdeployToMavenCentral -DskipTests=true clean deploy
```
## Excluding modules from being released to maven central
Sometimes a project needs a (test-)module that is not supposed to be released as an artifact to Maven Central. This is
complicated because the nexus staging plugin will only deploy to staging if the last module of a multi modules build
is actually one that is supposed to be released. Especially test modules tend to be the last ones built and are not
to be deployed, so disabling the staging plugin in these modules will essentially end up in the whole project not being
released to staging. In these cases two profiles will do the trick. One that is called `development`, which includes
ALL the modules and is activated on the missing property named `deployToMavenCentral`.
The other profile is called `deployToMavenCentral`, contains only the modules that are intended to be released to
maven central and is activated on the presence of the property named `deployToMavenCentral`. Example:
```xml
development
false
!deployToMavenCentral
core
integrations
tests
deployToMavenCentral
false
deployToMavenCentral
core
integrations
```
## The reason for having a prepareForMavenCentral profile
The `prepareForMavenCentral` and `deployToMavenCentral` include the exact same configuration except a excluded modules.
To apply all plugins, checks and verifications on all modules and not only the released ones, the `prepareForMavenCentral`
profile is used.
## Coverage reports in multi-module projects
Multi-module projects need to contain a special module `coverage` that **directly** depends on all modules
for which coverage needs to be reported, i.e. all modules that contain code. A transitive dependency is **not** sufficient.
The module needs to contain this plugin section:
```xml
org.jacoco
jacoco-maven-plugin
0.8.5
report-aggregate2
verify
report-aggregate
```
All modules need to contain a property to point sonar to `target/site/jacoco-aggregate/jacoco.xml` **in the `coverage` module**.
This has to be a relative path that needs to be tweaked to point to the `coverage` module, depending on the module it is declared in.
Example:
```xml
../coverage/target/site/jacoco-aggregate/jacoco.xml
```
## Running sonar
The sonar plugin requires an access token to be set using the `SONAR_TOKEN` env variable.
Then the sonar plugin can be run with:
```
mvn verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar -P sonar
```