From aa9f29695cdb35250c90e027cb53cda9fb158586 Mon Sep 17 00:00:00 2001 From: Alexander Kriegisch Date: Mon, 24 May 2021 13:49:08 +0700 Subject: [PATCH] Add "how to release" guide and point to it from README.md Also fix a few minor wording and formatting things in the main read-me. Signed-off-by: Alexander Kriegisch --- README.md | 23 +++--- docs/developer/RELEASE.md | 154 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 167 insertions(+), 10 deletions(-) create mode 100644 docs/developer/RELEASE.md diff --git a/README.md b/README.md index daf99bb47..2641506dc 100644 --- a/README.md +++ b/README.md @@ -10,38 +10,41 @@ AspectJ enables: ## Building -AspectJ has a multi module maven build. Although various modules produce intermediate results, the key artifacts at the end of the build are: +AspectJ has a multi-module Maven build. Although various modules produce intermediate results, the key artifacts at the end of the build are: * `aspectjrt` - the AspectJ runtime * `aspectjweaver` - the AspectJ weaver * `aspectjtools` - the AspectJ compiler +* `aspectjmatcher` - the AspectJ matcher -These are the artifacts published to maven central for each release. In addition there is an installer that can be run with `java -jar` to install AspectJ onto Windows/Mac/Linux. This installer is produced by the installer sub module. +These are the artifacts published to Maven Central for each release. In addition, there is an installer that can be run with `java -jar` to install AspectJ onto Windows/Mac/Linux. This installer is produced by the `installer` sub-module. In the root of a cloned AspectJ simply run: `./mvnw clean install` This will build all the modules, run all the tests and install the key artifacts in your local repository. -Once built access the maven dependencies from your local repository or run the installer to install AspectJ locally: +Once built, access the Maven dependencies from your local repository or run the installer to install AspectJ locally: ``` java -jar installer/target/aspectj-.jar ``` -## Running the tests in eclipse +## Running the tests in Eclipse Once you have imported all the projects using `m2e`, there is a special module called `run-all-junit-tests` and within that a `RunTheseBeforeYouCommitTests` class that can be run with the JUnit launcher to execute thousands of tests. Ensure you run this with a JDK - the more recent the better since some tests will not execute on older JDKs - tests that verify language features that only exist in the more up to date JDK version. -## Documentation +## Documentation for AspectJ users -[Complete documentation quicklinks](https://www.eclipse.org/aspectj/docs.php) +* [Complete documentation quicklinks](https://www.eclipse.org/aspectj/docs.php) +* [Getting started with AspectJ](https://www.eclipse.org/aspectj/doc/released/progguide/starting.html) +* [Programming Guide](https://www.eclipse.org/aspectj/doc/released/progguide/index.html) +* [READMEs for each version of AspectJ](docs/dist/doc) -[Getting started with AspectJ](https://www.eclipse.org/aspectj/doc/released/progguide/starting.html) +## Documentation for AspectJ developers -[Programming Guide](https://www.eclipse.org/aspectj/doc/released/progguide/index.html) - -[READMEs for each version of AspectJ](https://github.com/eclipse/org.aspectj/tree/master/docs/dist/doc) +* [How to contribute to AspectJ](CONTRIBUTING.md) +* [How to release AspectJ](docs/developer/RELEASE.md) ## Maven releases diff --git a/docs/developer/RELEASE.md b/docs/developer/RELEASE.md new file mode 100644 index 000000000..5ef7eb620 --- /dev/null +++ b/docs/developer/RELEASE.md @@ -0,0 +1,154 @@ +# How to release AspectJ + +AspectJ is built and released with Maven. As of writing this, there is a Maven wrapper in the project root folder, +pointing to Maven 3.6.3, but we are going to use simple `mvn` commands instead of `./mvnw` here, assuming that there is +a local Maven installation on your workstation. You can easily substitute one for the other command. + +When deploying final releases to Sonatype OSSRH, the build uses Nexus Staging Maven plugin instead of Maven Deploy +plugin. This helps to create a staging repository for the release and later release it to Maven Central without having +to log into the [Sonatype Nexus web UI](https://oss.sonatype.org/). Everything can be done from the command line. + +Snapshots do not need to be staged and released separately, Maven Deploy does the job in this case. so let us begin with +the simple case: + +## Snapshot releases + +Assuming that you are currently working on version 1.9.7-SNAPSHOT, you simply call: + +```shell +mvn clean deploy + +# OR: If you ran tests locally before, or the CI workflow on GitHub did +mvn -DskipTests=true clean deploy + +# OR: Speed it up some more, skipping documentation generation. Depending on +# your shell, you might not have to escape the '!' character for deactivating +# the 'create-docs' profile. On a (Git) Bash you have to, though. +mvn -P \!create-docs -DskipTests=true clean deploy +``` + +This only deploys the main artifacts + - AspectJ runtime `aspectjrt-[VERSION].jar`, + - AspectJ tools/compiler `aspecttools-[VERSION].jar`, + - AspectJ weaver `aspectjweaver-[VERSION].jar`, + - AspectJ matcher `aspectjmatcher-[VERSION].jar`. + +The AspectJ installer (`installer/target/aspectj-[VERSION].jar`) needs to be published separately, if you wish to make +it available to the public for this snapshot. + +## Public releases (milestone, release candidate, final) + +The artifacts released are the same as for snapshots, the procedure needs a few more steps, though. I am explaining the +manual versioning process without using Maven Release plugin. It might work using Maven Release too, i.e. + - setting the release version in all POMs, + - building a release, + - running tests (can be skipped), + - committing the release POMs, + - tagging the release, + - deploying the release, + - setting the next snapshot version in all POMs, + - committing the snapshot POMs, + - pushing the previous commits and the release tag to the upstream Git repository. + +In order to show the details and give you more control over the process, you can do it step by step as follows: + +```shell +# Make sure we are on JDK 16, because javadoc generation is JDK version sensitive +# and might throw unexpected errors on other versions +java -version +# java version "16" 2021-03-16 (...) + +# Verify that we are working on a clean working directory. +# There should be no staged, unstaged or untracked files. +git status + +# Set release version in all POMs +mvn versions:set -DnewVersion=1.9.7.M2 + +# Verify if the POM changes are OK, then remove the POM backup files +mvn versions:commit + +# Commit the release POMs to Git +git commit -am "Set version to 1.9.7.M2" + +# Set some environment variables needed by Nexus Staging Maven plugin on JDK 16, +# until https://issues.sonatype.org/browse/OSSRH-66257 is resolved +export MAVEN_OPTS="--add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.text=ALL-UNNAMED --add-opens=java.desktop/java.awt.font=ALL-UNNAMED" + +# Build and deploy the release to a Nexus staging repository. +# The 'release' profile will activate +# - Maven GPG plugin for signing artifacts (stand by to enter your passpharase!), +# - Maven Javadoc plugin, +# - Nexus Staging Maven plugin. +# Optionally, use '-DskipTests=true', if you ran all tests before. +mvn -P release clean deploy +``` + +If this command was successful, it means we have created a staging repository on Sonatype OSSRH, uploaded all artifacts +and all pre-release checks on the Sonatype server passed, i.e. if the POMs contain all necessary information and if +there are source and javadoc artifacts attached to the build. Now the only step left is to release the staging +repository to Maven Central. + +Actually, Nexus Staging Maven plugin can also be configured deploy and release to Maven Central in a single command, but +in order to give you a chance to manually download and verify the artifacts from the staging repository, the default +plugin configuration in the parent POM is `false`. Switching the value to +`true` would release straight to Maven Central, given all previous steps were successful. + +Before we release the staging repository though, we want to commit and tag the release, then set a new snapshot version: + +```shell +# Commit the release POMs to Git (better do this from your IDE, verifying the +# changes before staging them for Git commit) +git commit -am "Set version to 1.9.7.M2" + +# Tag release +git tag V1_9_7_M2 + +# Set new snapshot version, increasing the version number after a final release +mvn versions:set -DnewVersion=1.9.7-SNAPSHOT + +# Verify if the POM changes are OK, then remove the POM backup files +mvn versions:commit + +# Commit the snapshot POMs to Git +git commit -am "Set version to 1.9.7-SNAPSHOT" + +# Push the previous commits to GitHub +git push origin + +# Push the release tag to GitHub +git push origin V1_9_7_M2 +``` + +OK, the Git house-keeping is done. Now finally, let us enjoy the fruits of our work and release the staging repository +to Maven Central: + +```shell +# Probably we forgot to write down the staging repository ID before. +# It was written somewhere in the Maven log: +# [INFO] * Created staging repository with ID "orgaspectj-1106". +# [INFO] * Staging repository at https://oss.sonatype.org:443/service/local/staging/deployByRepositoryId/orgaspectj-1106 +# ... +# [INFO] * Uploading locally staged artifacts to profile org.aspectj +# [INFO] * Upload of locally staged artifacts finished. +# [INFO] * Closing staging repository with ID "orgaspectj-1106". +# +# But it is too far to scroll up. So let us just ask Nexus, which staging +# repositories there are. +mvn nexus-staging:rc-list +# [INFO] ID State Description +# [INFO] orgaspectj-1106 CLOSED org.aspectj:aspectjrt:1.9.7.M2 + +# Use the ID of the corresponding CLOSED staging repository for releasing to +# Maven Central + mvn nexus-staging:rc-release -DstagingRepositoryId=orgaspectj-1106 +``` + +Tadaa! We have performed an AspectJ release. In a few minutes, the artifacts should appear on Maven Central somewhere +under https://repo1.maven.org/maven2/org/aspectj/, e.g. AspectJ Tools 1.9.7.M2 would appear under +https://repo1.maven.org/maven2/org/aspectj/aspectjtools/1.9.7.M2/. As soon as you see the artifacts there instead of +"404 not found", you can announce release availability on the AspectJ mailing list and wherever else appropriate. + +Finally, probably want to publish the AspectJ installer (`installer/target/aspectj-[VERSION].jar`), e.g. by creating a +GitHub release and attaching artifacts and/or updating the Eclipse AspectJ website. You also want to update the AspectJ +documentation, if there were any changes. -- 2.39.5