Skip to content

Latest commit

 

History

History
268 lines (197 loc) · 14.4 KB

CONTRIBUTING.md

File metadata and controls

268 lines (197 loc) · 14.4 KB

Contributing

Build

The build and the functional-test builds get every plugin and every Maven dependency from three Space proxies (gradle/repositories.settings.gradle.kts):

Proxy Holds
build-deps The release versions.
build-deps-eap The compiler-plugin-dev-kit and the Kotlin development builds.
build-deps-ide The Kotlin builds of the IDEs.

A proxy takes a package from one upstream repository only. So a new upstream repository goes into the proxy where no other upstream repository has its packages.

A proxy gives a version that it already has to every request. The first request of a new version needs a token. Put the token into the gradle.properties file of the Gradle user home:

space.username.watchdog=<username>
space.password.watchdog=<token>

The workflows get the token from the WATCHDOG_PROXY_USERNAME and WATCHDOG_PROXY_PASSWORD secrets. A pull request from a fork has no secrets. So before such a pull request can pass, run the build and the tests that use its new dependency versions with the token.

-Pwatchdog.proxies=false replaces the proxies with the original repositories for one run.

The devkit entry of gradle/libs.versions.toml sets the version of the compiler-plugin-dev-kit. The dev kit settings plugin gives the plugin coordinates and the functional-test publishing.

The repository is a composite build:

Build Holds
The root build The compiler plugin, the exemption fixer, and the Gradle plugin functional tests (:gradle-plugin-test).
gradle-plugin The Gradle plugin and the report aggregation plugin.
plugin-annotations The annotations.
build-logic-settings The settings plugins: devkit for the root build and devkit-included for the other builds. Both apply the dev kit settings plugin.
build-logic The project plugins: devkit.compiler, devkit.compiler-library, devkit.gradle, and the library-api-watchdog.* conventions.

A task name on the command line runs the task in the root build only. To run a task of an included build, put the build name first: ./gradlew :gradle-plugin:test. The root check task also runs check in gradle-plugin and plugin-annotations. The root publishAllPublicationsToSpaceRepository and publishPlugins tasks also run the publication tasks of the included builds. The root publishAllPublicationsToBuildRepository, dumpArtifacts, and checkArtifacts tasks also run in plugin-annotations, but not in gradle-plugin.

Tests

./gradlew :library-api-watchdog-compiler-plugin:allTests           # diagnostics tests against every supported Kotlin version
./gradlew :library-api-watchdog-compiler-plugin:latestKotlinTest   # diagnostics tests against the newest Kotlin dev build
./gradlew :library-api-watchdog-compiler-plugin:generateTests      # regenerate the JUnit classes from the test data
./gradlew :library-api-watchdog-compiler-plugin:benchmarkCorpusAudit # check that the corpus triggers every benchmark-eligible checker
./gradlew :library-api-watchdog-compiler-plugin:benchmarkBaseline   # compare checker allocation with the CI baseline
./gradlew :library-api-watchdog-exempts-fixer:allTests             # exemption fixer tests against every supported Kotlin version
./gradlew :gradle-plugin-test:allVersionedFunctionalTests                 # Gradle TestKit tests against every supported Kotlin version
./gradlew :gradle-plugin:test                                             # Gradle plugin unit tests
./gradlew :gradle-plugin:library-api-watchdog-report-aggregation:test # report aggregation tests
./gradlew :build-logic:test                                               # build logic tests

CI runs one functional test task for each supported Kotlin version. :gradle-plugin-test:printCiFunctionalTestMatrix lists those versions. The compiler plugin tests also run every day at 9:00 Berlin time, against the newest Kotlin dev build only (latestKotlinTest).

The report aggregation tests run the report scripts in the Chrome for Testing headless shell. The build downloads the headless shell and its chromedriver of the chromeForTesting version in gradle/libs.versions.toml into the Gradle user home. Chrome for Testing has no build for Linux on ARM, so these tests skip themselves there.

The benchmarks and the baseline check are in compiler-plugin/src/benchmark/README.md.

Modules

Artifact lists

The artifacts validator plugin compares the published files of each Maven Central module with a list in the artifacts directory of its build: the root build and plugin-annotations. ./gradlew checkArtifacts fails when a publication doesn't match its list. The artifact lists workflow runs the task.

After a change of a publication, run ./gradlew dumpArtifacts and commit the lists. A change of kotlinCliMin in the version catalog is such a change, because the lists of the compiler plugin and the fixer have that version in an artifact name, for example -k240. dumpArtifacts and checkArtifacts fail in the same Gradle invocation, so run them separately.

Documentation site

The site is a Docusaurus project in docs, built by docs-checks.yml. Run its checks in docs/ after npm ci:

npm test                            # the remark plugins
npm run check:diagnostic-exemptions # the exemption wording in the check pages matches diagnostics.json
npm run build                       # the site build, fails on a broken link or anchor

The build also writes the Markdown form of the site for LLM readers: llms.txt (the page index), llms-full.txt (every page), and a .md file next to each page. docs/plugins/llms-txt.mjs renders them from the page sources.

Only a manual run of docs.yml on main deploys the site. The run needs the version input, a release version with a tag, and the code samples show that version. The Post-publish workflow starts this run after each release.

Build scans and cache

The root build and its included builds use JetBrains Develocity for build scans and the remote build cache. CI publishes scans for authenticated builds. Local scans are disabled by default.

To enable local scans, copy local.properties.template to local.properties and set develocity.buildScan.enabled=true.

Use --scan or --no-scan to override this setting for one build. CI waits for scan uploads before each Gradle command exits.

To authenticate locally, run:

./gradlew provisionDevelocityAccessKey

Gradle stores the key in ~/.gradle/develocity/keys.properties. The same key authenticates scan uploads and remote cache access.

For GitHub Actions, add the repository secret DEVELOCITY_ACCESS_KEY with the value ge.jetbrains.com=<access-key>. The key needs permission to publish scans and read and write the build cache.

Local builds and pull requests only read the remote cache. CI on main sets DEVELOCITY_CACHE_PUSH=true to write cache entries.

Version

library.properties sets the next development version, for example 0.3.0 after the 0.2.0 release. Local builds and the development builds of main use it. The release commit of the Pre-release workflow sets it. To change the build and website package versions by hand, run:

./scripts/update-version.sh 0.3.0
./scripts/verify-version-alignment.sh

LIBRARY_VERSION overrides that version in every Gradle project, generated plugin coordinates, reports, and website code samples. A release and a docs deploy set it to the release version:

LIBRARY_VERSION=0.2.0-dev-1 ./gradlew assemble

The override doesn't change any source file. The build ignores -Pversion. An empty or invalid value fails the build.

Pull request checks

The ruleset of main requires one check, all_green of the Pull request checks workflow. The workflow runs on every pull request. Its changes job has a list of paths for each check workflow. The workflow calls a check workflow when the pull request changes a path of its list. all_green fails when a called workflow fails.

A check workflow has no pull_request trigger of its own. To add a check workflow to the pull request checks:

  1. Add the workflow_call trigger to the check workflow.
  2. Add its list of paths and an output to the changes job.
  3. Add a job that calls the workflow when the output is true.
  4. Add the job to the needs of all_green.

Enable auto-merge on a pull request merges it when all_green passes. The button needs the repository setting Settings > General > Allow auto-merge.

Watchdog bot

The Dev kit update, Pre-release, and Post-publish workflows push their branches and open their pull requests as the Watchdog bot, a GitHub App. A pull request of GITHUB_TOKEN starts pull_request runs that wait for an approval (Events that trigger workflows). GitHub signs the commits of the bot, because the workflows make them through the GraphQL API.

Register the app in Settings > Developer settings > GitHub Apps of the repository owner:

Setting Value
Webhook Off
Repository permissions Contents: read and write. Issues: read and write (the release label). Pull requests: read and write.
Where can this GitHub App be installed? Only on this account

Then generate a private key, install the app on this repository, and add the repository settings:

Name Kind Value
WATCHDOG_BOT_CLIENT_ID Variable The client ID of the app
WATCHDOG_BOT_PRIVATE_KEY Secret The private key, the content of the .pem file
WATCHDOG_BOT_LOGIN Variable The user of the app, <app slug>[bot], for example library-api-watchdog[bot]

The Dev kit update and the Pre-release workflows check the commit of their pull request themselves. So the compiler plugin tests, the Gradle tests, the docs checks, the version alignment check, the artifact list check, and the benchmark check skip a pull_request run of WATCHDOG_BOT_LOGIN. A push of another user to the branch runs them.

Dependency updates

Renovate reads .github/renovate.json. To activate it, install the Renovate GitHub App for this repository and merge the configuration into main.

Renovate opens pull requests for Gradle, npm, and GitHub Actions updates. Automatic merging is disabled. Renovate groups Kotlin updates for compatibility review. Docusaurus packages also share one pull request.

Renovate skips the compiler-plugin-dev-kit. Dev kit update updates it every day at 6:00 Berlin time, or when you run the workflow:

  1. The workflow compares the devkit entry of the version catalog on main with the newest version in the Space repository. When they differ, it commits the newest version to the devkit-update branch and opens a pull request as the Watchdog bot.
  2. The workflow runs the compiler plugin tests, the Gradle tests, the artifact list check, and the benchmark check on that commit.
  3. When all of them pass, the workflow squash-merges the pull request. When one fails, the pull request stays open.

Each run makes the branch again from main. When the branch of the open pull request has a commit of another author, the run doesn't change the branch. To fix a failed update, push the fix to the branch and merge the pull request yourself.

A custom manager tracks the Android Gradle plugin test versions in the version catalog. The agp8 entry stays on version 8, and agp9 stays on version 9. The minimum supported Kotlin and IntelliJ IDEA versions remain manual compatibility decisions.

To validate the configuration:

npm exec --yes --package=node@24 --package=renovate@44.164.6 -- renovate-config-validator --strict --no-global .github/renovate.json

Changelog

The Pre-release workflow writes the section of each release in CHANGELOG.md, so a pull request doesn't edit the changelog. The section holds the GitHub generated release notes: the pull requests since the previous release tag. The title of a pull request is its changelog entry. The notes skip the pull requests with the release label of .github/release.yml.

For text above the generated notes of the next release, add a ## Unreleased section at the top of CHANGELOG.md. The release moves that text into its section and removes the ## Unreleased section. The release sections are in version order, the latest first.

After an edit of CHANGELOG.md, generate the website page:

cd docs
npm run sync:changelog

CI checks that the website changelog matches the root file. The version script leaves historical changelog entries and dependency versions unchanged.

Release

See Release for more details about the release process.