demery-pivotal commented on a change in pull request #6878:
URL: https://github.com/apache/geode/pull/6878#discussion_r711368370
##########
File path: geode-serialization/ANALYZE_SERIALIZABLES.md
##########
@@ -0,0 +1,129 @@
+# Analyze Serializables
+
+## Adding AnalyzeSerializables test to a new geode module
+
+If you've created a new geode module, then add an integration test to detect
any additions or
+changes to serializable classes in the module.
+
+Change the module's build.gradle to add a dependency on geode-serialization:
+```
+integrationTestImplementation(project(':geode-serialization'))
+```
+
+Create `AnalyzeModuleSerializablesIntegrationTest` that extends
+`AnalyzeSerializablesJUnitTestBase`. It needs to be in package
`org.apache.geode.codeAnalysis`.
+
+## Implementing SanctionedSerializablesService
+
+If you've changed or added any serializable classes to a geode module, the
previously added
+integration test should fail. You'll need to implement
SanctionedSerializablesService for the geode
+module.
+
+Change the module's build.gradle to add a dependency on geode-serialization:
+```
+implementation(project(':geode-serialization'))
+```
+
+Create a new ModuleSanctionedSerializablesService that implements
SanctionedSerializablesService:
+```
+src/main/java/org/apache/geode/module/internal/ModuleSanctionedSerializablesService.java
+```
+
+Add a service file for SanctionedSerializablesService:
+```
+src/main/resources/META-INF/services/org.apache.geode.internal.serialization.SanctionedSerializablesService
+```
+
+Add a line to the service file specifying the fully qualified name of the
service implementation:
+```
+org.apache.geode.module.internal.ModuleSanctionedSerializablesService
+```
+
+Update AnalyzeModuleSerializablesIntegrationTest to return the new
SanctionedSerializablesService
+implementation from `getModuleClass`:
+```java
+@Override
+protected Optional<Class<?>> getModuleClass() {
+ return Optional.of(ModuleSanctionedSerializablesService.class);
+}
+```
+
+## Fixing failures in AnalyzeModuleSerializablesIntegrationTest
+
+AnalyzeModuleSerializablesIntegrationTest analyzes serializable classes in a
module. It fails if
+either:
+- a new serializable class is added to the main src
+- an existing serializable class in main src is modified
+
+The content of the failure message depends on whether the module implements
+SanctionedSerializablesService.
+
+If it implements SanctionedSerializablesService, the failure message looks
like:
+```
+New or moved classes----------------------------------------
+org/apache/geode/CancelException,true,3215578659523282642
+
+If the class is not persisted or sent over the wire, add it to the file
+
/Users/klund/dev/geode3/geode-core/src/integrationTest/resources/org/apache/geode/codeAnalysis/excludedClasses.txt
+Otherwise, if this doesn't break backward compatibility, copy the file
+
/Users/klund/dev/geode3/geode-core/build/integrationTest/test-worker-000009/actualSerializables.dat
+ to
+
/Users/klund/dev/geode3/geode-core/src/main/resources/org/apache/geode/internal/sanctioned-geode-core-serializables.txt
+If this potentially breaks backward compatibility, follow the instructions in
+ README.MD
Review comment:
Change `README.MD` to the new path to the instructions.
##########
File path: geode-serialization/ANALYZE_SERIALIZABLES.md
##########
@@ -0,0 +1,129 @@
+# Analyze Serializables
+
+## Adding AnalyzeSerializables test to a new geode module
+
+If you've created a new geode module, then add an integration test to detect
any additions or
+changes to serializable classes in the module.
+
+Change the module's build.gradle to add a dependency on geode-serialization:
+```
+integrationTestImplementation(project(':geode-serialization'))
+```
+
+Create `AnalyzeModuleSerializablesIntegrationTest` that extends
+`AnalyzeSerializablesJUnitTestBase`. It needs to be in package
`org.apache.geode.codeAnalysis`.
+
+## Implementing SanctionedSerializablesService
+
+If you've changed or added any serializable classes to a geode module, the
previously added
+integration test should fail. You'll need to implement
SanctionedSerializablesService for the geode
+module.
+
+Change the module's build.gradle to add a dependency on geode-serialization:
+```
+implementation(project(':geode-serialization'))
+```
+
+Create a new ModuleSanctionedSerializablesService that implements
SanctionedSerializablesService:
+```
+src/main/java/org/apache/geode/module/internal/ModuleSanctionedSerializablesService.java
+```
+
+Add a service file for SanctionedSerializablesService:
+```
+src/main/resources/META-INF/services/org.apache.geode.internal.serialization.SanctionedSerializablesService
+```
+
+Add a line to the service file specifying the fully qualified name of the
service implementation:
+```
+org.apache.geode.module.internal.ModuleSanctionedSerializablesService
+```
+
+Update AnalyzeModuleSerializablesIntegrationTest to return the new
SanctionedSerializablesService
+implementation from `getModuleClass`:
+```java
+@Override
+protected Optional<Class<?>> getModuleClass() {
+ return Optional.of(ModuleSanctionedSerializablesService.class);
+}
+```
+
+## Fixing failures in AnalyzeModuleSerializablesIntegrationTest
+
+AnalyzeModuleSerializablesIntegrationTest analyzes serializable classes in a
module. It fails if
+either:
+- a new serializable class is added to the main src
+- an existing serializable class in main src is modified
+
+The content of the failure message depends on whether the module implements
+SanctionedSerializablesService.
+
+If it implements SanctionedSerializablesService, the failure message looks
like:
+```
+New or moved classes----------------------------------------
+org/apache/geode/CancelException,true,3215578659523282642
+
+If the class is not persisted or sent over the wire, add it to the file
+
/Users/klund/dev/geode3/geode-core/src/integrationTest/resources/org/apache/geode/codeAnalysis/excludedClasses.txt
Review comment:
Do you want your username immortalized in these file paths?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
