diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/developer/RELEASE.md | 69 |
1 files changed, 37 insertions, 32 deletions
diff --git a/docs/developer/RELEASE.md b/docs/developer/RELEASE.md index afc68d4f8..991cd4b69 100644 --- a/docs/developer/RELEASE.md +++ b/docs/developer/RELEASE.md @@ -27,7 +27,7 @@ To publish a snapshot, set up your credentials in `~/.m2/settings.xml` something </settings> ``` -Assuming that you are currently working on version 1.9.8-SNAPSHOT, you simply call: +Next, you simply call: ```shell mvn clean deploy @@ -173,34 +173,39 @@ under https://repo1.maven.org/maven2/org/aspectj/, e.g. AspectJ Tools 1.9.8.M2 w https://repo1.maven.org/maven2/org/aspectj/aspectjtools/1.9.8.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, you 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. - -## Deploying the AspectJ installer to aspectj.dev - -An easy way to quickly publish the installer is to simply deploy it to the Maven repository aspectj.dev. In order to do -that, you need to mount the target directory as a WebDAV share first (ask an AspectJ maintainer for credentials). This -can be done on all operating systems, for this example let us assume we are working on Windows and already have mounted -the share to drive letter M: (M like Maven). Command `net use` would show something like this (sorry, in German): - -```text -C:\Users\me>net use -... -Status Lokal Remote Netzwerk -------------------------------------------------------------------------------- -OK M: \\s000b153.kasserver.com\s000b153 - Microsoft Windows Network -... -``` - -Next, we need to tell Maven to - - actually deploy the installer (remember, by default only the artifacts listed above are deployed), - - override the default deployment repository (Sonatype OSSRH) by our WebDAV share. - -Before issuing the following command, make sure that you successfully built AspectJ before. Otherwise, Maven cannot find -the artifacts it needs to create the installer JAR. - -```shell -mvn --projects installer -Dmaven.deploy.skip=false -DaltDeploymentRepository=aspectj-dev::default::file:///M: deploy -``` +Finally, remember to publish the [release on GitHub](https://github.com/eclipse-aspectj/aspectj/releases), attaching +the AspectJ installer (`installer/target/aspectj-[VERSION].jar`) to it. + +## Publish documentation on website + +Content for the [AspectJ website](https://eclipse.dev/aspectj/) is maintained in GitHub repository +[eclipse-aspectj/aspectj-website](https://github.com/eclipse-aspectj/aspectj-website). As of writing this, there are a +few basic PHP pages (to be migrated to plain HTML by the end of 2024 when PHP support expires), but the bulk of the +project documentation is generated by the AspectJ project, i.e. this project. The asciidoc content and other +resources in module `docs` are transformed into what we want to publish on the website. Besides, the documentation is +also packaged into the AspectJ installer and published for offline use. On top of the `docs` content, we also publish +javadocs for the runtime and weaver APIs. + +After a full build, you can find the generated documentation including javadocs in folder `aj-build/dist/docs/doc`. +Conveniently, docs are also attached to GitHub CI builds, albeit currently without javadocs. The content goes to +folder `doc/latest` in the website repository or maybe to a folder named after the release, if we decide to do that in +the future. Presently, we only publish the latest documentation, always overwriting the preceding version. The entry +page for the generated docs is published [here](https://eclipse.dev/aspectj/doc/latest/index.html). + +Make sure to check the diffs before committing. If a certain part of the documentation (e.g. developer's notebook, +programming guide) has not changed HTML-wise, you also do not need to commit the corresponding PDF, even though it +might be binarily different. But if the HTML content is unchanged, the PDF should look the same as before, too, unless +you have reason to believe otherwise (e.g. changes in style in the generator options). Inspecting the diffs, you also +want to identify other generic changes, such as timestamps, years in copyright notices etc. It is an ongoing process +to optimise such changes away to achieve stable docs and small commit diffs. If you spot something, make sure to +optimise the build process accordingly. + +After pushing changes to the website repository, they should be published by a batch process automatically after a +short delay (usually a few minutes). + +**Caveat:** The publishing process currently relies on fast-forwarding changes, i.e. if you e.g. amend or squash website +commits and then force-push them, the changes might not be published at all, and you need to open an Eclipse helpdesk +issue like [this one]() for the infrastructure team to propagate the changes manually. Knowing that, it is best not to +force-push, unless absolutely necessary (e.g. removing commits with sensitive information). + +After the website has been published, smoke-test the changes, opening some pages you know must have changed. |