Update RELEASE.md

- Remove obsolete section "Deploying the AspectJ installer to
  aspectj.dev", because we are publishing releases on GitHub, attaching
  installers to them.

- Add section "Publish documentation on website".

Signed-off-by: Alexander Kriegisch <Alexander@Kriegisch.name>

diff --git a/docs/developer/RELEASE.md b/docs/developer/RELEASE.md
index afc68d4f824c718caf615f94acded4c055cbac4b..991cd4b690ffd4a3dca38068b0ef783cdf7c5a5c 100644 (file)
--- 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.