Use of cli.xconf to include release pages - discontinue?

[Kristian Waagan <kr...@oracle.com>]

Hi,

While working on the Derby web site I got frustrated by the 
complications involved when rebuilding the release pages.

cli.xconf has been used to make Forrest (or Cocoon) include the release 
pages. This means that both cli.xconf and derby_downloads.html have to 
be modified when adding a new release. This is not much of a problem in 
itself, but the use of cli.xconf causes the final release pages to be 
written to a directory inside FORREST_HOME (this is a Forrest bug). 
These has to be manually copied to the correct location.

All release pages linked to from derby_downloads.html are included 
automatically. This leaves us with the HTML-file(s) for releases with 
mirroring enabled missing - typically one or two releases [1].

I see two possible ways to fix this in Forrest 0.8:
  a) Add Forrest to the Derby web site repository. This allows us to 
specify a correct relative destination path *given* that the 
Forrest-installation included in the repository is used.
  b) Add an invisible link to the HTML page for mirrored releases in 
derby_downloads.html.

Option (a) adds around 40 MB to the repository.
Option (b) introduces the following changes in the publication process:
  b-1) Add link for new release in derby_downloads.html:
       cur: <li> <a href="releases/release-10.8.1.2.cgi">10.8.1.2</a>
       new: <li> <a href="releases/release-10.8.1.2.html"></a><a 
href="releases/release-10.8.1.2.cgi">10.8.1.2</a>
  b-2) When archiving release:
       cur: move lines and replace '.cgi' with '.html'
       new: move lines and delete everything between '</a>' and '">' - 
effectively removing the link to the CGI file.
There may be some quirks related to dealing with really old release 
pages (i.e. those no longer listed on derby_downloads.html), but they 
are rarely updated anyway.

I'm attaching a patch that shows what it takes to implement this change. 
This change will also cause the release pages for four of the oldest 
releases to be modified - the left side menu will be changed such that 
it is identical to the menu on the newer release pages.
In addition the release publication document on the wiki must be 
updated, and a few methods in ReleaseNotesTransformer can be removed 
(the code modifying cli.xconf).

I'm all ears for feedback on this, especially from those that has 
struggled with this issue in the past (i.e. will the new approach work 
out?).
See also the related issue DERBY-5388.


Regards,
-- 
Kristian

[1] The release with the highest version number will have mirroring 
enabled (currently 10.8.1.2). It is unclear to me if have any guidelines 
for maintenance releases off older branches (i.e. if we were to publish 
a 10.7 maintenance release today). To avoid having different processes 
for publication, we can consider the two cases as one. Mirroring should 
probably be disabled sooner for releases off older branches.

Re: Use of cli.xconf to include release pages - discontinue?

[Rick Hillegas <ri...@oracle.com>]

Hi Kristian,

I am one of the people who has struggled with 
https://issues.apache.org/jira/browse/FOR-480  in the past but I am 
afraid I can't give you much advice. I don't understand Forrest or 
Cocoon. FOR-480 has been fixed for five years now, but we're still stuck 
on the old buggy version. It's possible that upgrading our version of 
Forrest might fix other website problems we have, like the spurious 
checkouts of skins.

Your change might improve the situation. I don't know.

Thanks,
-Rick

On 8/22/11 3:27 PM, Kristian Waagan wrote:
> Hi,
>
> While working on the Derby web site I got frustrated by the 
> complications involved when rebuilding the release pages.
>
> cli.xconf has been used to make Forrest (or Cocoon) include the 
> release pages. This means that both cli.xconf and derby_downloads.html 
> have to be modified when adding a new release. This is not much of a 
> problem in itself, but the use of cli.xconf causes the final release 
> pages to be written to a directory inside FORREST_HOME (this is a 
> Forrest bug). These has to be manually copied to the correct location.
>
> All release pages linked to from derby_downloads.html are included 
> automatically. This leaves us with the HTML-file(s) for releases with 
> mirroring enabled missing - typically one or two releases [1].
>
> I see two possible ways to fix this in Forrest 0.8:
>  a) Add Forrest to the Derby web site repository. This allows us to 
> specify a correct relative destination path *given* that the 
> Forrest-installation included in the repository is used.
>  b) Add an invisible link to the HTML page for mirrored releases in 
> derby_downloads.html.
>
> Option (a) adds around 40 MB to the repository.
> Option (b) introduces the following changes in the publication process:
>  b-1) Add link for new release in derby_downloads.html:
>       cur: <li> <a href="releases/release-10.8.1.2.cgi">10.8.1.2</a>
>       new: <li> <a href="releases/release-10.8.1.2.html"></a><a 
> href="releases/release-10.8.1.2.cgi">10.8.1.2</a>
>  b-2) When archiving release:
>       cur: move lines and replace '.cgi' with '.html'
>       new: move lines and delete everything between '</a>' and '">' - 
> effectively removing the link to the CGI file.
> There may be some quirks related to dealing with really old release 
> pages (i.e. those no longer listed on derby_downloads.html), but they 
> are rarely updated anyway.
>
> I'm attaching a patch that shows what it takes to implement this 
> change. This change will also cause the release pages for four of the 
> oldest releases to be modified - the left side menu will be changed 
> such that it is identical to the menu on the newer release pages.
> In addition the release publication document on the wiki must be 
> updated, and a few methods in ReleaseNotesTransformer can be removed 
> (the code modifying cli.xconf).
>
> I'm all ears for feedback on this, especially from those that has 
> struggled with this issue in the past (i.e. will the new approach work 
> out?).
> See also the related issue DERBY-5388.
>
>
> Regards,