This is an automated email from the ASF dual-hosted git repository.
pottlinger pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/creadur-site.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 5e0224d2a RAT-480: Improve documentation on how to work on the site
itself
5e0224d2a is described below
commit 5e0224d2a520930067e683268039076143baf56c
Author: P. Ottlinger <[email protected]>
AuthorDate: Thu Oct 9 20:54:43 2025 +0200
RAT-480: Improve documentation on how to work on the site itself
---
README.md | 49 +++++++++++++++++++++++++++++++++++--------------
1 file changed, 35 insertions(+), 14 deletions(-)
diff --git a/README.md b/README.md
index 51bedab1f..d4228ae3a 100644
--- a/README.md
+++ b/README.md
@@ -1,18 +1,31 @@
# Apache Creadur Website
-This project contains the project's webpage.
+This repository contains our webpage.
-Its deployment is done via [asf.yaml](./.asf.yaml). Every commit is directly
pushed and available on https://creadur.apache.org/
+Every commit is directly pushed and available on
[https://creadur.apache.org/](https://creadur.apache.org/), as its deployment
is done via [asf.yaml](./.asf.yaml).
-## How to generate new page versions for RAT
+## Prerequisites for working with on the webpage
-## SNAPSHOT
+In order to work with Creadur's git repositories some scripts expect that all
projects are checked out in one directory. Thus you should have the following
directory structure on your local box:
+
+```
+$ cd ~/myworkspace
+$ ls -l
+drwxrwxr-x 16 hirsch hirsch 4096 Okt 9 19:37 creadur-rat
+drwxrwxr-x 13 hirsch hirsch 4096 Okt 9 20:28 creadur-site
+drwxrwxr-x 10 hirsch hirsch 4096 Okt 9 18:25 creadur-tentacles
+drwxrwxr-x 16 hirsch hirsch 4096 Okt 9 17:17 creadur-whisker
+```
+
+## How to generate new page versions for Creadur subprojects
+
+## RAT - SNAPSHOT
The current SNAPSHOT version of RAT can be found in
[rat017](https://creadur.apache.org/rat017/) and is generated manually.
RAT uses
[Jira](https://issues.apache.org/jira/secure/RapidBoard.jspa?rapidView=625&quickFilter=2851)
to track issues of the currently planned release.
-### RAT
+### Apache RAT
In order to sync the current webpage (taken from current SNAPSHOT) you need to
run the following commands:
```
@@ -29,7 +42,7 @@ $ git commit -am "Update site build for RAT"
Have a look in [RAT's buildtools
folder](https://github.com/apache/creadur-rat/tree/master/.buildtools) if you
want to generate a preview webpage.
-### Tentacles
+### Apache Tentacles
Same, but:
```
@@ -43,7 +56,7 @@ $ git commit -am "Update site build for TENTACLES"
```
Have a look in [TENTACLES' buildtools
folder](https://github.com/apache/creadur-tentacles/tree/master/.buildtools) if
you want to generate a preview webpage.
-### Whisker
+### Apache Whisker
Same, but:
```
@@ -57,15 +70,22 @@ $ git commit -am "Update site build for WHISKER"
```
Have a look in [WHISKER's buildtools
folder](https://github.com/apache/creadur-whisker/tree/master/.buildtools) if
you want to generate a preview webpage.
-## Releases
+## Release troubleshooting
-Due to problems when generating Javadoc do only use JDK16! Newer versions run
into NPE during path traversal.
+### No site can be generated - build failure during javadoc generation
+
+Due to problems when generating Javadoc do only use JDK16! Newer versions
cannot generate the project's javadoc and run into an NPE during path
traversal. This is documented in
[RAT-497](https://issues.apache.org/jira/browse/RAT-497) und reported upstream
as a JDK bug.
+
+### Keeping release artifacts locally
It may happen that you need access to the original release candidate JARs in
order to have all of the necessary test JARs to perform a site build,
-see [RAT-341](https://issues.apache.org/jira/browse/RAT-341) for details. As a
workaround copy these files into your local .m2 repository and run a site build:
+see [RAT-341](https://issues.apache.org/jira/browse/RAT-341) for details.
+
+As a workaround copy these files into your local .m2 repository as a
deployment of an already released artifact is not possible. Run a site build
afterwards:
```
$ mvn site:site site:stage
```
+or
```
$ cd creadur-rat
@@ -84,23 +104,24 @@ $ git commit -am "Push new preview version of RAT 0.16.1"
```
This will allow a preview of the release site build at [rat0161](./rat0161)
-### Release Notes / RAT-306
+### RAT-306: Fix errors in release notes
Make sure that https://creadur.apache.org/rat/RELEASE_NOTES.txt does not yield
a 404.
+
RAT's changelog consists of 2 versions:
* [generated changelog of the current
release](https://github.com/apache/creadur-rat/blob/master/RELEASE-NOTES.txt)
* [complete/historical
changelog](https://github.com/apache/creadur-rat/blob/master/RELEASE_NOTES.txt)
-Usually it helps to copy over the release-generated version into the subfolder
/rat of this project
+Usually it helps to copy over the release-generated version into the subfolder
[./rat](/rat) of this project.
### Combined release notes
Make sure to generate a combined changelog that includes the most current
release, available under [relase-notes/rat.txt](/release-notes/rat.txt)
-## Local hacking
+## Local development with docker
The whole page can be started locally with the help of
[docker-compose](https://docs.docker.com/compose/) and will provide the
contents via http://localhost:8888
-Depending on your docker version this means:
+Depending on your docker version this means in the current repository:
```
$ docker-compose up
OR
