This is an automated email from the ASF dual-hosted git repository. airblader pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/flink.git
commit 4f6240848ed8b2cb2548239b49b7bcb392ee909e Author: Jing Ge <[email protected]> AuthorDate: Mon Jan 24 17:18:43 2022 +0100 [FLINK-25220][test] update README.md --- flink-architecture-tests/README.md | 48 +++++++++++------- .../flink-architecture-tests-production/README.md | 33 +++++++++++++ .../flink-architecture-tests-test/README.md | 57 ++++++++++++++++++++++ 3 files changed, 121 insertions(+), 17 deletions(-) diff --git a/flink-architecture-tests/README.md b/flink-architecture-tests/README.md index 11b2b64..d83292f 100644 --- a/flink-architecture-tests/README.md +++ b/flink-architecture-tests/README.md @@ -1,13 +1,30 @@ # flink-architecture-tests -This module contains architecture tests using [ArchUnit](https://www.archunit.org/). These tests -reside in their own module in order to control the classpath of which modules should be tested. -Running these tests together (rather than individually per module) allows caching the imported -classes for better performance. +This module contains architecture tests using [ArchUnit](https://www.archunit.org/). Considering the +isolation of classpath and rules for architectural tests, there are two top level categories: + +- production code architectural tests +- test code architectural tests + +Since both of them will need some common ArchUnit extensions, there are three submodules: + +- flink-architecture-tests-base - contains common ArchUnit extensions that will be used for both + production code architectural tests and test code architectural tests. +- flink-architecture-tests-production - contains all architectural rules and tests centrally for + production code. Please read the [README](flink-architecture-tests-production/README.md) of + flink-architecture-tests-production for further information. +- flink-architecture-tests - contains architectural rules centrally for test code. The architectural + test will be built individually in each submodule where the test code has been developed. Please + read the [README](flink-architecture-tests-test/README.md) of flink-architecture-tests-test for + further information. + +Following documentation is valid for building and maintaining the architectural tests both for the +production code and the test code. ## What should I do if the tests fail? -There are two cases in which the architectural tests may fail due to changes in the codebase: +There are two cases in which architectural tests may fail due to changes in the codebase: + 1. You have resolved an existing violation. 2. Your change introduced a new violation. @@ -15,29 +32,26 @@ In the former case, please add the updated violation store file to your commit. succeed. If you have added a new violation, consider how to proceed. New violations should be avoided at all -costs. First and foremost, evaluate whether the flagged violation is correct. If it is, try to rework -your change to avoid the violation in the first place. However, if you believe that your code should -not be flagged as a violation, open a JIRA issue so that the rule can be improved. +costs. First and foremost, evaluate whether the flagged violation is correct. If it is, try to +rework your change to avoid the violation in the first place. However, if you believe that your code +should not be flagged as a violation, open a JIRA issue so that the rule can be improved. -In order to have a new violation recorded, open `archunit.properties` and enable +In order to have a new violation recorded, open `archunit.properties` in the submodule and enable `freeze.refreeze=true`. Rerun the tests and revert the change to the configuration. The new violation should now have been added to the existing store. -## How do I add a module? - -In order to add a module to be tested against, add it as a test dependency in this module's -`pom.xml`. - ## How do I write a new architectural rule? Please refer to the [ArchUnit user guide](https://www.archunit.org/) for general documentation. However, there are a few points to consider when writing rules: 1. If there are existing violations which cannot be fixed right away, the rule must be _frozen_ by - wrapping it in `FreezingArchRule.freeze()`. This will add the rule to the violation store that - records the existing violations. Add the new stored violations file within `violations` to your + wrapping it in `FreezingArchRule.freeze()`. This will add the rule to the violation store that + records the existing violations. Add the new stored violations file within `violations` to your commit. -2. ArchUnit does not work well with Scala classes. All rules should exclude non-Java classes by +2. In order to allow creating new violation store file, open `archunit.properties` in the submodule + and enable `freeze.store.default.allowStoreCreation=true`. +3. ArchUnit does not work well with Scala classes. All rules should exclude non-Java classes by utilizing the methods in `GivenJavaClasses`. ## How do I test Scala classes? diff --git a/flink-architecture-tests/flink-architecture-tests-production/README.md b/flink-architecture-tests/flink-architecture-tests-production/README.md new file mode 100644 index 0000000..c6ab91d --- /dev/null +++ b/flink-architecture-tests/flink-architecture-tests-production/README.md @@ -0,0 +1,33 @@ +# flink-architecture-tests-production + +This submodule contains all architectural tests of production code. +Running these tests together (rather than individually per module) allows caching the imported +classes for better performance. + +## What should I do if the tests fail? + +Please refer to [README](../README.md). + +## How do I write a new architectural rule? + +Please refer to [README](../README.md). + +## How do I write a ArchUnit test? + +Please refer to the [ArchUnit user guide](https://www.archunit.org/) for general documentation. For +quick start, you could find an example +at [flink-architecture-tests-production/ArchitectureTest](./flink-architecture-tests-production/src/test/java/org/apache/flink/architecture/ArchitectureTest.java): + +```java +@ArchTest +public static final ArchTests API_ANNOTATIONS=ArchTests.in(ApiAnnotationRules.class); +``` + +## How do I add a module? + +In order to add a module to be tested against, add it as a test dependency in this module's +`pom.xml`. + +## How do I test Scala classes? + +Please refer to [README](../README.md). diff --git a/flink-architecture-tests/flink-architecture-tests-test/README.md b/flink-architecture-tests/flink-architecture-tests-test/README.md new file mode 100644 index 0000000..af687e3 --- /dev/null +++ b/flink-architecture-tests/flink-architecture-tests-test/README.md @@ -0,0 +1,57 @@ +# flink-architecture-tests-test + +This submodule contains rules defined centrally for test code architectural tests that will be +developed in each submodule individually where the test code has been developed. + +## Why the architecture test infra for production code and for test code are different + +Compared to `flink-architecture-tests-production` which implements and executes architectural rules +centrally, `flink-architecture-tests-test` implements the rules centrally, but they are executed +individually in each submodule. This is done for the following reasons: + +- Reduce the classpath complexity. In order to execute the tests centrally, each submodule would + have to provide a test-jar. However, this does not work well in IntelliJ which doesn't support all + Maven configurations (such as exclusion filters); this would cause the rules to behave differently + when executed from Maven versus IntelliJ. Furthermore, creating more test-jars is not desirable + and increases the project complexity. +- Separation of concerns. Test code should be viewed as internal to a module, and by separating the + violation stores for each submodule this separation can be maintained. Unlike the production code + tests there is few shared code between test code, and thus the performance benefits do not apply. +- Flexibility. Each submodule can not only import the generic rules defined + in `flink-architecture-tests-test` centrally, but also develop further module-specific + architectural tests locally. + +## How do I write a new architectural rule? + +Please refer to [README](../README.md). + +## How do I initialize and develop the first architectural test for a Flink submodule's test code? + +If there already exists any architectural test in the Flink submodule, you can skip this section and +start writing your architectural tests and rules. + +It is recommended to stick to the following template to setup and develop the first test code +architectural test for a Flink submodule. + +Under a Flink submodule where no architectural test has ever been developed. + +- Create `archunit.properties` and `flink-connector-file` under "<Flink Submodule> + /src/test/resources". Please use [archunit.properties](./src/test/resources/archunit.properties) + and [log4j2-test.properties](./src/test/resources/log4j2-test.properties) as template. +- Develop ArchUnit test under the package `org.apache.flink.architecture`. It is recommended to + use `TestCodeArchitectureTest` as the class name. +- Include the common tests + via `@ArchTest public static final ArchTests COMMON_TESTS = ArchTests.in(TestCodeArchitectureTestBase.class)` + . +- Develop individual rules under the package `org.apache.flink.architecture.rules` if it is + required. + +For practice purpose, please refer to the `flink-connector-file` as the reference implementation. + +## What should I do if the tests fail? + +Please refer to [README](../README.md). + +## How do I test Scala classes? + +Please refer to [README](../README.md).
