-
Notifications
You must be signed in to change notification settings - Fork 4
Summer 2024 project
Creation of gist is still a not convenient.
Sometime config creation is not obvious, requires maintainers but they have limited keyboard time, creation of such content on phone is very complicated and error prone.
Our previous attempt for generation of list of configs for changed code in PR failed, it is complicated.
Having all module instances in single config is problematic, as report become a mess, impossible to validate by humans.
Some checks requires very specific config with very specific property values AND very specific projects (javadocSummary with japanese period; Indentation; …. ).
We should have prepared and ready to use bundles of config + list of projects.
All should be stored as plain text in some git repo of or org
All user need to do is provide name/path to config.
As bonus: requesting list of links to configs. now we use BDD in all tests we can simply reuse all configs that are in changed Input files or very specific from changed Input files.
All instances is one is special mode of testing when we expect no changes at all, some refactoring, pitest investigations.
Some test bundle should manually crafted and stored in our code base forever to be used as all other bundles.
We create repository: https://github.com/checkstyle/test-configs
This repo will contain script/application to generate content of config. There will two configs type, generated by script based on latest checkstyle:main:HEAD and some manually crafted.
Structure from root of repo should be something like:
├── extractor/
…. All files (java project) that we need to generate content below
……
├── AbbreviationAsWordInName
│ ├── all-examples-in-one
│ │ ├── config.xml
│ │ └── list-of-projects.properties
│ ├── Example1
│ │ ├── config.xml
│ │ └── list-of-projects.properties
│ ├── Example2
│ │ ├── config.xml
│ │ └── list-of-projects.properties
│ ├── Example3
│ │ ├── config.xml
│ │ └── list-of-projects.properties
│ ├── Example4
│ │ ├── config.xml
│ │ └── list-of-projects.properties
│ ├── Example5
│ │ ├── config.xml
│ │ └── list-of-projects.properties
│ ├── Example6
│ │ ├── config.xml
│ │ └── list-of-projects.properties
│ └── Example7
│ ├── config.xml
│ └── list-of-projects.properties
…….
└── SummaryJavadoc
│ ├── all-examples-in-one
│ │ ├── config.xml just dump of all examples in one config
│ │ └── list-of-projects.properties
│ ├── Example1
│ │ ├── config.xml
│ │ └── list-of-projects.properties
│ ├── Example2
│ │ ├── config.xml
│ │ └── list-of-projects.properties
│ ├── Example3
│ │ ├── config.xml
│ │ └── list-of-projects.properties
└── japan-period
├── config.xml
├── README.md occasional files that can give a bit more context on when to use
└── list-of-projects.properties special list might be required if Check is heavy to execute
List of configs should be taken from https://checkstyle.org/checks/naming/abbreviationaswordinname.html#Examples , no need to reinvent a wheel, lets take what we have, it is very good source of ideas for configs with all properties.
Source for them are at https://github.com/checkstyle/checkstyle/tree/master/src/xdocs-examples/resources/com/puppycrawl/tools/checkstyle/checks/naming/abbreviationaswordinname https://github.com/checkstyle/checkstyle/blob/f34e7c2d34d3bc579920fa789d8d812129bbfd49/src/xdocs-examples/resources/com/puppycrawl/tools/checkstyle/checks/naming/abbreviationaswordinname/Example1.java#L2-L6 better to that it form java files.
NOTE: we can abandon Default-projects.yaml and just force all folders to have 2 fies always, it will be much easier for outside contributors to understand.
Repo will contains extractor/ folder where will have script/application that generates all such folders. It will simply clone checkstyle master branch and parse all ExamplesX.java to get content of config and save it to upper/parent level folder. After generation we simply commit all changes and push to repo. Execution and commit should done automatically by cron execution of some github action in this repo.
Repo with all configs generated for each module from main repo by means of extractor.
Each ExampleX folder or any other folder with configs contains minimum 2 files (config.xml and list of list-of-projects.properties)
Extractor implementation that does override only ExampleX folders and all-examples-in-one folder. All other files and folders in this repo should not be touched.
All contributors of our project https://github.com/checkstyle/checkstyle use such config files and share feedback, usage of existing action by Github, generate report.
Extractor should have internal configuration for templates of files for list-of-projects.properties that might be not a default for specific Check as some Check are not quick and CI job might not finish before timeout, so we will have to remove some projects from property file. Example of config https://github.com/checkstyle/test-configs/issues/20
Most Configs are tested in main repo to be sure that they can finish execution without timeouts
New Github workflow in https://github.com/checkstyle/checkstyle that will use test-config files. So less configurations to provide by user in PR.
New Github workflow does not use checkstyle/contribution repo at all.
Diff.groovy is copied and updated to test-config repo and updated to use YML format of list-of-projects.properties and Extractor is updated to work with list-of-projects.yaml https://github.com/checkstyle/contribution/tree/master/patch-diff-report-tool is copied to not depend on “checkstyle/contribution” repo at all.
If we have time we should convert diff.groovy to java project to manage it easily and be able to generate final JAR file and use it by github new workflow action. JAR file can be committed in main repo for simplicity. CI is enforced over java code to demand basic code quality.
Usage for user:
Github, generate report for <path in test-congs repo>
Github, generate report AbstractClassName/Example1
Will use https://raw.githubusercontent.com/checkstyle/test-configs/main/AbstractClassName/Example1/list-of-projects.properties/config.xml And https://raw.githubusercontent.com/checkstyle/test-configs/main/AbstractClassName/Example1/list-of-projects.properties/ list-of-projects.properties And generate diff report and publishing as existing Github workflow is doing.
New trigger comment for Workflow to reuse changed Inputs of Pull Request.
Execution and commit should done automatically by cron execution of some github action in this repo.
Extract “patch-diff-report-tool” to separate repo under checksyle org and deploy JAR to come place to use it as jar.
Fixing any leftovers and postponed task from previous months.
Brief documentation.
New workflow should cover by functionality (copy of functionality) old workflow to allow us deprecate old workflow.
One of most desirable feature is to get config based on what is changed in code of Module/Check. As we demand full coverage, all configs that matters will be at Input files of diff on change
Example ("git show --stat HEAD”): https://github.com/checkstyle/checkstyle/commit/73120c4943ce07533e812a6b241869fca7eade80
https://github.com/checkstyle/checkstyle/commit/73120c4943ce07533e812a6b241869fca7eade80.patch
.../whitespace/MethodParamPadCheck.java | 3 ++
.../checks/whitespace/MethodParamPadCheck.xml | 2 +-
src/main/resources/google_checks.xml | 2 +-
.../whitespace/MethodParamPadCheckTest.java | 17 +++++++-
.../InputMethodParamPadRecords.java | 2 +-
.../InputMethodParamPadCheckConstructors.java | 40 +++++++++++++++++++
.../InputMethodParamPadWhitespaceAround.java | 3 +-
.../checks/whitespace/methodparampad.xml | 4 ++
So our target is:
.../InputMethodParamPadRecords.java
.../InputMethodParamPadCheckConstructors.java
.../InputMethodParamPadWhitespaceAround.java
We extract configs from it and can use for execution, list of projects will be some default.
Usage for user:
Github, generate report for configs in PR description
It will simply use configs as it was defined in original workflow, this will be in use for complicated cases when we need different configs for master and patch.
Github, generate report for config from <path to Input in checkstyle repo>
Github, generate report by config from src/test/resources/com/puppycrawl/tools/checkstyle/checks/whitespace/methodparampad/InputMethodParamPadWhitespaceAround.java
Github, generate report by config from InputMethodParamPadWhitespaceAround.java
Workflow just clone PR. Workflow takes config out of such Input and generate config.xml.
Workflow use some default list of projects file.
And simply executes diff report based on configs files that are just generated in execution. Diff.groovy already has path to checkstyle repo of branch, it just need to generate full xml from Input same/similar way as it is done in “extractor”. “Diff.groovy” should have special argument to define this mode of execution.
No need to publish generated content, it will be part of report. look at report: https://checkstyle-diff-reports.s3.us-east-2.amazonaws.com/e6cdb69_2024152818/reports/diff/index.html it has all configs that user provided, first two links in index.html
If there is duplicate file name (same name in different folders), workflow will fail.
In code of workflow we can check that config file is ending with “*.java” and run extractor over it to get ready to use xml for diff.groovy. So it is just extra call for extractor before regular diff.groovy call.
File search will be linux util based (“find . -path”):
✔ ~/java/github/romani/checkstyle [master|⚑ 2]
$ find . -path "*InputMethodParamPadWhitespaceAround.java"
./src/test/resources/com/puppycrawl/tools/checkstyle/checks/whitespace/methodparampad/InputMethodParamPadWhitespaceAround.java
✔ ~/java/github/romani/checkstyle [master|⚑ 2]
$ find . -path "*methodparampad/InputMethodParamPadWhitespaceAround.java"
./src/test/resources/com/puppycrawl/tools/checkstyle/checks/whitespace/methodparampad/InputMethodParamPadWhitespaceAround.java
Github, generate report for config from <path to Input in checkstyle repo> , list of targets <http link to raw content>
Github, generate report by config from src/test/resources/com/puppycrawl/tools/checkstyle/checks/whitespace/methodparampad/InputMethodParamPadWhitespaceAround.java , list of targets https://raw.githubusercontent.com/checkstyle/test-configs/main/SummaryJavadoc/Example1/list-of-projects.properties
If we have time we do what ever Piyush wants or:
Any from Piyush …..
Interactive bots that suggest folder where configs are stored.
Some ideas on how to make trigger comment more convenient to create/type.
Some ideas on how support new Checks (that does not have prepared configs)
Sequential execution of several configs to be triggered by single comment
“Github, generate report AbstractClassName/*”, several comment with report link posted to PR. ….
Deprecation of existing Workflow. I still think it will be useful, and we can do it far later on after new workflow get maturity. No automatic triggering on PR creation. Better to let user trigger it.