{"id":15009236,"url":"https://github.com/quantummaid/quantummaid-opensource-parent","last_synced_at":"2025-04-09T17:23:17.732Z","repository":{"id":54511493,"uuid":"227639646","full_name":"quantummaid/quantummaid-opensource-parent","owner":"quantummaid","description":"Contains the Java quality standards for QuantumMaid projects.","archived":false,"fork":false,"pushed_at":"2021-05-15T12:26:17.000Z","size":213,"stargazers_count":5,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2023-12-20T06:57:20.536Z","etag":null,"topics":["architecture","checkstyle","ci-cd","ddd","java","maven","quality-assurance"],"latest_commit_sha":null,"homepage":"https://quantummaid.de","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/quantummaid.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-12-12T15:37:38.000Z","updated_at":"2021-12-25T05:13:39.000Z","dependencies_parsed_at":"2022-08-13T18:10:57.724Z","dependency_job_id":null,"html_url":"https://github.com/quantummaid/quantummaid-opensource-parent","commit_stats":null,"previous_names":[],"tags_count":0,"template":null,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantummaid%2Fquantummaid-opensource-parent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantummaid%2Fquantummaid-opensource-parent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantummaid%2Fquantummaid-opensource-parent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantummaid%2Fquantummaid-opensource-parent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quantummaid","download_url":"https://codeload.github.com/quantummaid/quantummaid-opensource-parent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248075362,"owners_count":21043570,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["architecture","checkstyle","ci-cd","ddd","java","maven","quality-assurance"],"created_at":"2024-09-24T19:23:55.398Z","updated_at":"2025-04-09T17:23:17.707Z","avatar_url":"https://github.com/quantummaid.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Last Commit](https://img.shields.io/github/last-commit/quantummaid/quantummaid-opensource-parent)](https://github.com/quantummaid/quantummaid-opensource-parent)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/de.quantummaid/quantummaid-opensource-parent/badge.svg)](https://maven-badges.herokuapp.com/maven-central/de.quantummaid/quantummaid-opensource-parent)\n[![Code Size](https://img.shields.io/github/languages/code-size/quantummaid/quantummaid-opensource-parent)](https://github.com/quantummaid/quantummaid-opensource-parent)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Slack](https://img.shields.io/badge/chat%20on-Slack-brightgreen)](https://quantummaid.de/community.html)\n[![Gitter](https://img.shields.io/badge/chat%20on-Gitter-brightgreen)](https://gitter.im/quantum-maid-framework/community)\n[![Twitter](https://img.shields.io/twitter/follow/quantummaid)](https://twitter.com/quantummaid)\n\n\n\u003cimg src=\"quantummaid_logo.png\" align=\"left\"/\u003e\n\n# quantummaid-java-standards\n\nContains the Java quality standards for QuantumMaid projects.\n\n## Usage\nReplace the top section of your `pom.xml` with the following:\n```xml\n\u003c!--\n  ~ Copyright (c) 2020 Richard Hauswald - https://quantummaid.de/.\n  ~\n  ~ Licensed to the Apache Software Foundation (ASF) under one\n  ~ or more contributor license agreements.  See the NOTICE file\n  ~ distributed with this work for additional information\n  ~ regarding copyright ownership.  The ASF licenses this file\n  ~ to you under the Apache License, Version 2.0 (the\n  ~ \"License\"); you may not use this file except in compliance\n  ~ with the License.  You may obtain a copy of the License at\n  ~\n  ~   http://www.apache.org/licenses/LICENSE-2.0\n  ~\n  ~ Unless required by applicable law or agreed to in writing,\n  ~ software distributed under the License is distributed on an\n  ~ \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n  ~ KIND, either express or implied.  See the License for the\n  ~ specific language governing permissions and limitations\n  ~ under the License.\n  --\u003e\n\n\u003cproject xmlns=\"http://maven.apache.org/POM/4.0.0\"\n         xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n         xsi:schemaLocation=\"http://maven.apache.org/POM/4.0.0\n                      http://maven.apache.org/xsd/maven-4.0.0.xsd\"\u003e\n    \u003cmodelVersion\u003e4.0.0\u003c/modelVersion\u003e\n    \u003cparent\u003e\n        \u003cgroupId\u003ede.quantummaid\u003c/groupId\u003e\n        \u003cartifactId\u003equantummaid-opensource-parent\u003c/artifactId\u003e\n        \u003cversion\u003e0.9.24\u003c/version\u003e\n    \u003c/parent\u003e\n```\n\nAlso make sure that the `README.md` of the project clearly recommends the usage of the `pgpverify-maven-plugin` by\nproviding the link \u003chttps://youtu.be/ES9hWkn_WBA?t=27m29s\u003e. It can be found under \n\u003chttps://www.simplify4u.org/pgpverify-maven-plugin/\u003e (usage instructions). \n \n## Checkstyle\nCheckstyle is enabled after using this POM as parent in a Maven project. It is executed before tests are run.\n\n### Registering Checkstyle suppressions\nAdd the following to your `pom.xml`:\n```xml\n\u003cproject xmlns=\"http://maven.apache.org/POM/4.0.0\"\n         xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n         xsi:schemaLocation=\"http://maven.apache.org/POM/4.0.0\n                      http://maven.apache.org/xsd/maven-4.0.0.xsd\"\u003e\n    \u003cmodelVersion\u003e4.0.0\u003c/modelVersion\u003e\n        ...\n    \u003cproperties\u003e\n        ...\n        \u003ccheckstyle.suppressions.location\u003e\n            ${project.basedir}/src/test/checkstyle/checkstyle-suppressions.xml\n        \u003c/checkstyle.suppressions.location\u003e\n    \u003c/properties\u003e\n    ...\n\u003c/project\u003e\n```\nCreate a suppression configuration file under `/src/test/checkstyle/checkstyle-suppressions.xml` with the \ncontents of your choice based on the following example:\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!--\n  ~ Copyright (c) 2020 Richard Hauswald - https://quantummaid.de/.\n  ~\n  ~ Licensed to the Apache Software Foundation (ASF) under one\n  ~ or more contributor license agreements.  See the NOTICE file\n  ~ distributed with this work for additional information\n  ~ regarding copyright ownership.  The ASF licenses this file\n  ~ to you under the Apache License, Version 2.0 (the\n  ~ \"License\"); you may not use this file except in compliance\n  ~ with the License.  You may obtain a copy of the License at\n  ~\n  ~   http://www.apache.org/licenses/LICENSE-2.0\n  ~\n  ~ Unless required by applicable law or agreed to in writing,\n  ~ software distributed under the License is distributed on an\n  ~ \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n  ~ KIND, either express or implied.  See the License for the\n  ~ specific language governing permissions and limitations\n  ~ under the License.\n  --\u003e\n\n\u003c!DOCTYPE suppressions PUBLIC\n        \"-//Puppy Crawl//DTD Suppressions 1.1//EN\"\n        \"http://www.puppycrawl.com/dtds/suppressions_1_1.dtd\"\u003e\n\u003csuppressions\u003e\n    \u003csuppress checks=\"VisibilityModifier\" files=\".*AggregatedValidationException.java\" /\u003e\n    \u003csuppress checks=\"IllegalCatchCheck\" files=\"NamedMethodSerializationCPMethod.java\" /\u003e\n    \u003csuppress checks=\"IllegalCatchCheck\" files=\"Deserializer.java\" /\u003e\n\u003c/suppressions\u003e\n```\n\nThe checkstyle step can be skipped for a run with `-Dcheckstyle.skip`.\n\n### IntelliJ IDEA integration\nInstall the CheckStyle-IDEA plugin. Afterwards, open `Settings -\u003e Other Settings -\u003e Checkstyle` and add a new Checkstyle\nconfiguration file, name it `QuantumMaidOpenSource` and use \n\u003chttps://raw.githubusercontent.com/quantummaid/quantummaid-opensource-parent/master/checkstyle/checkstyle.xml\u003e as a URL location.\n\n## Spotbugs\nSpotbugs is enabled after using this POM as parent in a Maven project. It is executed before tests are run.\n\n### Registering Spotbugs exclusions\nAdd the following to your `pom.xml`:\n```xml\n\u003cproject xmlns=\"http://maven.apache.org/POM/4.0.0\"\n         xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n         xsi:schemaLocation=\"http://maven.apache.org/POM/4.0.0\n                      http://maven.apache.org/xsd/maven-4.0.0.xsd\"\u003e\n    \u003cmodelVersion\u003e4.0.0\u003c/modelVersion\u003e\n        ...\n    \u003cproperties\u003e\n        ...\n        \u003cspotbugs.excludeFilterFile\u003e\n            ${project.basedir}/src/test/spotbugs/spotbugs-exclude.xml\n        \u003c/spotbugs.excludeFilterFile\u003e\n    \u003c/properties\u003e\n    ...\n\u003c/project\u003e\n```\nCreate a suppression configuration file under `/src/test/spotbugs/spotbugs-exclude.xml` with the contents of your\nchoice based on the following example:\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003c!--\n  ~ Copyright (c) 2020 Richard Hauswald - https://quantummaid.de/.\n  ~\n  ~ Licensed to the Apache Software Foundation (ASF) under one\n  ~ or more contributor license agreements.  See the NOTICE file\n  ~ distributed with this work for additional information\n  ~ regarding copyright ownership.  The ASF licenses this file\n  ~ to you under the Apache License, Version 2.0 (the\n  ~ \"License\"); you may not use this file except in compliance\n  ~ with the License.  You may obtain a copy of the License at\n  ~\n  ~   http://www.apache.org/licenses/LICENSE-2.0\n  ~\n  ~ Unless required by applicable law or agreed to in writing,\n  ~ software distributed under the License is distributed on an\n  ~ \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n  ~ KIND, either express or implied.  See the License for the\n  ~ specific language governing permissions and limitations\n  ~ under the License.\n  --\u003e\n\n\u003cFindBugsFilter\n\t\txmlns=\"https://github.com/spotbugs/filter/3.0.0\"\n\t\txmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n\t\txsi:schemaLocation=\"https://github.com/spotbugs/filter/3.0.0 https://raw.githubusercontent.com/spotbugs/spotbugs/3.1.0/spotbugs/etc/findbugsfilter.xsd\"\u003e\n    \u003cMatch\u003e\n         \u003cClass name=\"de.quantummaid.someClass\"/\u003e\n         \u003cMethod name=\"aSpecificMethod\"/\u003e\n         \u003cBug pattern=\"RCN_REDUNDANT_NULLCHECK_OF_NONNULL_VALUE\"/\u003e\n    \u003c/Match\u003e\n    \n    \u003cMatch\u003e\n         \u003cClass name=\"de.quantummaid.differentClass\"/\u003e\n         \u003cBug category=\"PERFORMANCE\"/\u003e\n    \u003c/Match\u003e\n\n\u003c/FindBugsFilter\u003e\n```\n\nMore information about exclusions can be found on the [spotbugs website](https://spotbugs.readthedocs.io/en/stable/filter.html#examples).\n\n### IntelliJ IDEA integration\nInstall the Findbugs-IDEA plugin.\n\n## Compiler\nThe compiler is configured for all child projects and should not be modified in any of the child projects of this POM.\nFollowing this recommendation provides child projects with the following benefits:\n- Encoding and Java version of the sources and compiled classes are managed\n- A configuration bug fix, that will prevent the maven-compiler-plugin from swallowing compilation errors and hence \n  failing with 'unknown compilation error'\n- Building the child project in Intellij IDEA will be possible with warnings\n- Building the child project using maven will be possible with warnings, if built with `-DskipTests=true` \n- Testing the child project using maven will be possible with warnings, if built with \n  `-Dmaven.compiler.failOnWarning=false` \n- Building/Testing the child project will fail, if the source code is causing compiler warnings\n- Releasing the child project will fail, if the source code is causing compiler warnings\n\n## Skipping tests\nJust run the Maven command with `-DskipTests=true`.\n\n## Long running tests, that should be executed before every release, but not on every verify\nSurefire will set a system property `testMode` to either `NORMAL` or `RELEASE` depending on the active profile.\n\nIn the test, an `if` statement can be used:\n```java\nfinal Boolean runThisTest = Optional.ofNullable(System.getProperty(\"testMode\")).map(s -\u003e s.equals(\"RELEASE\")).orElse(false);\nif (runThisTest) {\n    //test you long running stuff\n} else {\n    System.out.println(\"Skipping this test, since system property testMode is not set to RELEASE\");\n}\n```\n\n## Releasing a version to Maven Central\nThe problem with releasing to Maven Central using a CI/CD pipeline is complicated, since both, the nexus staging account\nand the gpg key must be kept private. If an attacker gains access to one or both of these credentials users of\nour open source products are in grave danger (\u003chttps://youtu.be/ES9hWkn_WBA?t=27m29s\u003e). A bitbucket pipeline can output \nsecure environmental variables with some neat tricks. Since we would need to store both valuable credentials as such,\nthat operation can only be done manually outside the GitHub cloud environment:\n\n* Ensure the gpg private key with the id `0xACB977BA5C6D5C6E` installed in the gpg key store.\n* Ensure the maven settings.xml file contains the following section:\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003csettings xmlns=\"http://maven.apache.org/SETTINGS/1.0.0\" xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\"\n\t\t  xsi:schemaLocation=\"http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd\"\u003e\n\t...\n\t\u003cservers\u003e\n\t\t\u003cserver\u003e\n\t\t\t\u003cid\u003equantummaid.opensource.sonatype.staging\u003c/id\u003e\n\t\t\t\u003cusername\u003ethe username of the sonatype nexus staging account\u003c/username\u003e\n\t\t\t\u003cpassword\u003e{the encrypted password of the Sonatype nexus staging account created using mvn --encrypt-password}\u003c/password\u003e\n\t\t\u003c/server\u003e\n\t\u003c/servers\u003e\n\t...\n\u003c/settings\u003e\n```\n* Ensure the project version has been set to the appropriate value\n* Run the following command to test the project:\n```bash\nmvn clean verify\n```\n* run the following command to release the project in case the tests passed:\n```bash\nmvn -DdeployToMavenCentral -DskipTests=true clean deploy\n```\n\n## Excluding modules from being released to maven central\nSometimes a project needs a (test-)module that is not supposed to be released as an artifact to Maven Central. This is\ncomplicated because the nexus staging plugin will only deploy to staging if the last module of a multi modules build\nis actually one that is supposed to be released. Especially test modules tend to be the last ones built and are not\nto be deployed, so disabling the staging plugin in these modules will essentially end up in the whole project not being\nreleased to staging. In these cases two profiles will do the trick. One that is called `development`, which includes \nALL the modules and is activated on the missing property named `deployToMavenCentral`. \nThe other profile is called `deployToMavenCentral`, contains only the modules that are intended to be released to\nmaven central and is activated on the presence of the property named `deployToMavenCentral`. Example:\n```xml\n\u003cprofiles\u003e\n    \u003cprofile\u003e\n        \u003cid\u003edevelopment\u003c/id\u003e\n        \u003cactivation\u003e\n            \u003cactiveByDefault\u003efalse\u003c/activeByDefault\u003e\n            \u003cproperty\u003e\n                \u003cname\u003e!deployToMavenCentral\u003c/name\u003e\n            \u003c/property\u003e\n        \u003c/activation\u003e\n        \u003cmodules\u003e\n            \u003cmodule\u003ecore\u003c/module\u003e\n            \u003cmodule\u003eintegrations\u003c/module\u003e\n            \u003cmodule\u003etests\u003c/module\u003e\n        \u003c/modules\u003e\n    \u003c/profile\u003e\n    \u003cprofile\u003e\n        \u003cid\u003edeployToMavenCentral\u003c/id\u003e\n        \u003cactivation\u003e\n            \u003cactiveByDefault\u003efalse\u003c/activeByDefault\u003e\n            \u003cproperty\u003e\n                \u003cname\u003edeployToMavenCentral\u003c/name\u003e\n            \u003c/property\u003e\n        \u003c/activation\u003e\n        \u003cmodules\u003e\n            \u003cmodule\u003ecore\u003c/module\u003e\n            \u003cmodule\u003eintegrations\u003c/module\u003e\n        \u003c/modules\u003e\n    \u003c/profile\u003e\n\u003c/profiles\u003e\n```\n\n## The reason for having a prepareForMavenCentral profile\nThe `prepareForMavenCentral` and `deployToMavenCentral` include the exact same configuration except a excluded modules.\nTo apply all plugins, checks and verifications on all modules and not only the released ones, the `prepareForMavenCentral` \nprofile is used.\n\n## Coverage reports in multi-module projects\nMulti-module projects need to contain a special module `coverage` that **directly** depends on all modules\nfor which coverage needs to be reported, i.e. all modules that contain code. A transitive dependency is **not** sufficient.\nThe module needs to contain this plugin section:\n```xml\n   \u003cbuild\u003e\n        \u003cplugins\u003e\n            \u003cplugin\u003e\n                \u003cgroupId\u003eorg.jacoco\u003c/groupId\u003e\n                \u003cartifactId\u003ejacoco-maven-plugin\u003c/artifactId\u003e\n                \u003cversion\u003e0.8.5\u003c/version\u003e\n                \u003cexecutions\u003e\n                    \u003cexecution\u003e\n                        \u003cid\u003ereport-aggregate2\u003c/id\u003e\n                        \u003cphase\u003everify\u003c/phase\u003e\n                        \u003cgoals\u003e\n                            \u003cgoal\u003ereport-aggregate\u003c/goal\u003e\n                        \u003c/goals\u003e\n                    \u003c/execution\u003e\n                \u003c/executions\u003e\n            \u003c/plugin\u003e\n        \u003c/plugins\u003e\n    \u003c/build\u003e\n```\nAll modules need to contain a property to point sonar to `target/site/jacoco-aggregate/jacoco.xml` **in the `coverage` module**.\nThis 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.\nExample:\n```xml\n    \u003cproperties\u003e\n        \u003csonar.coverage.jacoco.xmlReportPaths\u003e../coverage/target/site/jacoco-aggregate/jacoco.xml\u003c/sonar.coverage.jacoco.xmlReportPaths\u003e\n    \u003c/properties\u003e\n```\n\n## Running sonar\nThe sonar plugin requires an access token to be set using the `SONAR_TOKEN` env variable.\n\nThen the sonar plugin can be run with:\n```\nmvn verify org.sonarsource.scanner.maven:sonar-maven-plugin:sonar -P sonar\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquantummaid%2Fquantummaid-opensource-parent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquantummaid%2Fquantummaid-opensource-parent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquantummaid%2Fquantummaid-opensource-parent/lists"}