[log4j] Project URLs per major version

[Volkan Yazıcı]

Currently, we have the following folder structure in the
`logging-log4j-site` repository for the Log4j project:

   - `log4j-1.2.17` – the website generated by the last Log4j 1 release,
   i.e, `1.2.17`
   - `log4j-1.2` – symlinks to `log4j-1.2.17`
   - `1.x` – symlinks to `log4j-1.2.17`
   - ...
   - `log4j-2.19.0` – the website generated by the `2.19.0` release
   - `log4j-2.20.0` – the website generated by the `2.20.0` release
   - `log4j-2.21.0` – the website generated by the `2.21.0` release
   - `2.x` – symlinks to `log4j-2.21.0` (the latest Log4j 2 release)

I propose keeping existing folders as is (hence, *no changes to the
existing URLs!*) and applying following practices:

   1. *Add a `latest` symlink* pointing to the latest stable version. Today
   it will point to `2.x`, sometime in the future it will point to `3.x`.
  - This will make following URLs possible:
  https://logging.apache.org/log4j/latest
  - This convention is practiced by several other projects, e.g.,
  Spring Boot: https://docs.spring.io/spring-boot/docs/current
   2. *Redirect root to `latest`*, i.e., `logging.apache.org/log4j` will
   redirect to `logging.apache.org/log4j/latest`
   3. *Don't create a new folder for every release, but override the `2.x`
   folder.*
  - This is okay, since we keep backward compatibility in minor+patch
  releases and explicitly provide version for features that are added later
  on (e.g., "starting from 2.17.0 Log4j provides X...")
  - We can set up CI jobs to periodically populate `1.x`, `2.x`, `3.x`,
  `4.x`, etc. websites and avoid the need to generate the website once and
  for all.
  - We will stop polluting the folder structure.

As a matter of fact, I already implemented this convention for some
projects. All the following URLs work:

   - `logging-parent`
  - logging.apache.org/logging-parent
  - logging.apache.org/logging-parent/latest
  - logging.apache.org/logging-parent/10.x
   - `logging-log4j-kotlin`
  - logging.apache.org/log4j/kotlin
  - logging.apache.org/log4j/kotlin/latest
  - logging.apache.org/log4j/kotlin/1.x
   - `logging-log4j-scala`
  - logging.apache.org/log4j/scala
  - logging.apache.org/log4j/scala/latest
  - logging.apache.org/log4j/scala/13.x
   - `logging-log4j-tools`
  - logging.apache.org/log4j/tools
  - logging.apache.org/log4j/tools/latest
  - logging.apache.org/log4j/tools/0.x
   - `logging-log4j-transform`
  - logging.apache.org/log4j/transform
  - logging.apache.org/log4j/transform/latest
  - logging.apache.org/log4j/transform/0.x

Unless there are objections, I will update the CI in this direction and we
all will enjoy automatically populated Log4j websites.

Re: [log4j] Project URLs per major version

[Christian Grobmeier]

This sounds pretty cool Volkan, if I didn't get anything I pretty much like it.
One question - you wrote:

"we all will enjoy automatically populated Log4j websites."

Does this mean we will see our website is updated automatically by CI so we can 
see in example /log4j/dev?
Or what else is "automatically updated"?



On Sun, Oct 22, 2023, at 22:20, Volkan Yazıcı wrote:
> Currently, we have the following folder structure in the
> `logging-log4j-site` repository for the Log4j project:
>
>- `log4j-1.2.17` – the website generated by the last Log4j 1 release,
>i.e, `1.2.17`
>- `log4j-1.2` – symlinks to `log4j-1.2.17`
>- `1.x` – symlinks to `log4j-1.2.17`
>- ...
>- `log4j-2.19.0` – the website generated by the `2.19.0` release
>- `log4j-2.20.0` – the website generated by the `2.20.0` release
>- `log4j-2.21.0` – the website generated by the `2.21.0` release
>- `2.x` – symlinks to `log4j-2.21.0` (the latest Log4j 2 release)
>
> I propose keeping existing folders as is (hence, *no changes to the
> existing URLs!*) and applying following practices:
>
>1. *Add a `latest` symlink* pointing to the latest stable version. Today
>it will point to `2.x`, sometime in the future it will point to `3.x`.
>   - This will make following URLs possible:
>   https://logging.apache.org/log4j/latest
>   - This convention is practiced by several other projects, e.g.,
>   Spring Boot: https://docs.spring.io/spring-boot/docs/current
>2. *Redirect root to `latest`*, i.e., `logging.apache.org/log4j` will
>redirect to `logging.apache.org/log4j/latest`
>3. *Don't create a new folder for every release, but override the `2.x`
>folder.*
>   - This is okay, since we keep backward compatibility in minor+patch
>   releases and explicitly provide version for features that are added 
> later
>   on (e.g., "starting from 2.17.0 Log4j provides X...")
>   - We can set up CI jobs to periodically populate `1.x`, `2.x`, `3.x`,
>   `4.x`, etc. websites and avoid the need to generate the website once and
>   for all.
>   - We will stop polluting the folder structure.
>
> As a matter of fact, I already implemented this convention for some
> projects. All the following URLs work:
>
>- `logging-parent`
>   - logging.apache.org/logging-parent
>   - logging.apache.org/logging-parent/latest
>   - logging.apache.org/logging-parent/10.x
>- `logging-log4j-kotlin`
>   - logging.apache.org/log4j/kotlin
>   - logging.apache.org/log4j/kotlin/latest
>   - logging.apache.org/log4j/kotlin/1.x
>- `logging-log4j-scala`
>   - logging.apache.org/log4j/scala
>   - logging.apache.org/log4j/scala/latest
>   - logging.apache.org/log4j/scala/13.x
>- `logging-log4j-tools`
>   - logging.apache.org/log4j/tools
>   - logging.apache.org/log4j/tools/latest
>   - logging.apache.org/log4j/tools/0.x
>- `logging-log4j-transform`
>   - logging.apache.org/log4j/transform
>   - logging.apache.org/log4j/transform/latest
>   - logging.apache.org/log4j/transform/0.x
>
> Unless there are objections, I will update the CI in this direction and we
> all will enjoy automatically populated Log4j websites.

Re: [log4j] Project URLs per major version

[Piotr P. Karwasz]

Hi Volkan,

On Sun, 22 Oct 2023 at 22:20, Volkan Yazıcı  wrote:
>3. *Don't create a new folder for every release, but override the `2.x`
>folder.*
>   - This is okay, since we keep backward compatibility in minor+patch
>   releases and explicitly provide version for features that are added 
> later
>   on (e.g., "starting from 2.17.0 Log4j provides X...")
>   - We can set up CI jobs to periodically populate `1.x`, `2.x`, `3.x`,
>   `4.x`, etc. websites and avoid the need to generate the website once and
>   for all.
>   - We will stop polluting the folder structure.

+1 on keeping just `1.x`, `2.x`, etc.

We just need to keep in mind that not all public methods have a
correct `@since` Javadoc tag. We would need to fix that.

Piotr

Re: [log4j] Project URLs per major version

[Apache]

I am ok with 1 and 2, but not 3. Doing that means older releases web sites are 
no longer available. Just because the latest includes release notes for all 
versions doesn’t mean it fully documents what was in prior releases. However, I 
am not surprised you are suggesting this as I posted in an earlier email that 
CI of the web site would be difficult due to this.

Ralph

> On Oct 22, 2023, at 2:03 PM, Piotr P. Karwasz  wrote:
> 
> Hi Volkan,
> 
>> On Sun, 22 Oct 2023 at 22:20, Volkan Yazıcı  wrote:
>>   3. *Don't create a new folder for every release, but override the `2.x`
>>   folder.*
>>  - This is okay, since we keep backward compatibility in minor+patch
>>  releases and explicitly provide version for features that are added 
>> later
>>  on (e.g., "starting from 2.17.0 Log4j provides X...")
>>  - We can set up CI jobs to periodically populate `1.x`, `2.x`, `3.x`,
>>  `4.x`, etc. websites and avoid the need to generate the website once and
>>  for all.
>>  - We will stop polluting the folder structure.
> 
> +1 on keeping just `1.x`, `2.x`, etc.
> 
> We just need to keep in mind that not all public methods have a
> correct `@since` Javadoc tag. We would need to fix that.
> 
> Piotr

Re: [log4j] Project URLs per major version

[Volkan Yazıcı]

> it [doesn't] fully documents what was in prior releases

Why is this a problem? We document newly added features with "starting from
version X, Log4j ships Y...". Doesn't this address your concern?

Many projects follow this convention, even Java itself:
https://docs.oracle.com/en/java/javase/index.html I think we can perfectly
make it work for us too.

Plus, we provide no public links to previous releases. That is, we provide
no links nowhere to `logging.apache.org/log4j/log4j-2.19.0`, hence, it is
practically hidden. As a matter of fact the following command returns empty
on `asf-site` branch of `logging-log4j-site` repository:

find . -type f -not -path "*/.git/*" -and -not -path "*/log4j-2.19.0/*"
| grep log4j-2.19.0

This proves we don't link `log4j-2.19.0` anywhere. (Please correct me if I
am wrong.)

On Mon, Oct 23, 2023 at 10:10 AM Apache  wrote:

> I am ok with 1 and 2, but not 3. Doing that means older releases web sites
> are no longer available. Just because the latest includes release notes for
> all versions doesn’t mean it fully documents what was in prior releases.
> However, I am not surprised you are suggesting this as I posted in an
> earlier email that CI of the web site would be difficult due to this.
>
> Ralph
>
> > On Oct 22, 2023, at 2:03 PM, Piotr P. Karwasz 
> wrote:
> >
> > Hi Volkan,
> >
> >> On Sun, 22 Oct 2023 at 22:20, Volkan Yazıcı  wrote:
> >>   3. *Don't create a new folder for every release, but override the
> `2.x`
> >>   folder.*
> >>  - This is okay, since we keep backward compatibility in minor+patch
> >>  releases and explicitly provide version for features that are
> added later
> >>  on (e.g., "starting from 2.17.0 Log4j provides X...")
> >>  - We can set up CI jobs to periodically populate `1.x`, `2.x`,
> `3.x`,
> >>  `4.x`, etc. websites and avoid the need to generate the website
> once and
> >>  for all.
> >>  - We will stop polluting the folder structure.
> >
> > +1 on keeping just `1.x`, `2.x`, etc.
> >
> > We just need to keep in mind that not all public methods have a
> > correct `@since` Javadoc tag. We would need to fix that.
> >
> > Piotr
>
>

Re: [log4j] Project URLs per major version

[Piotr P. Karwasz]

Hi Volkan,

On Mon, 23 Oct 2023 at 10:40, Volkan Yazıcı  wrote:
>
> > it [doesn't] fully documents what was in prior releases
>
> Why is this a problem? We document newly added features with "starting from
> version X, Log4j ships Y...". Doesn't this address your concern?

I prefer to document each new public/protected class or method with a
`@since` tag. We often don't do that (e.g. even in 2.21.0 there are a
couple of new methods).

Maybe there is an automatic scanner that can do it.

Piotr

Re: [log4j] Project URLs per major version

[Volkan Yazıcı]

Agreed, we should use `@since` tags. Though this doesn't warrant a new
website folder for each release, does it? Given we never disclosed these
folders, I want to understand the value it delivered in the past that can't
be achieved if we switch to using a single folder.

On Mon, Oct 23, 2023 at 12:49 PM Piotr P. Karwasz 
wrote:

> Hi Volkan,
>
> On Mon, 23 Oct 2023 at 10:40, Volkan Yazıcı  wrote:
> >
> > > it [doesn't] fully documents what was in prior releases
> >
> > Why is this a problem? We document newly added features with "starting
> from
> > version X, Log4j ships Y...". Doesn't this address your concern?
>
> I prefer to document each new public/protected class or method with a
> `@since` tag. We often don't do that (e.g. even in 2.21.0 there are a
> couple of new methods).
>
> Maybe there is an automatic scanner that can do it.
>
> Piotr
>

Re: [log4j] Project URLs per major version

[Matt Sicker]

Considering I’m one of the only people who adds @since tags (or Javadocs in 
general), I think we’ll need some tooling to help with this. In Jenkins, we had 
some sort of script for this so that we could add “@since TODO” to new files, 
and the script would replace them all before tagging a release (which is more 
relevant when you have weekly releases).

> On Oct 23, 2023, at 6:28 AM, Volkan Yazıcı  wrote:
> 
> Agreed, we should use `@since` tags. Though this doesn't warrant a new
> website folder for each release, does it? Given we never disclosed these
> folders, I want to understand the value it delivered in the past that can't
> be achieved if we switch to using a single folder.
> 
> On Mon, Oct 23, 2023 at 12:49 PM Piotr P. Karwasz 
> wrote:
> 
>> Hi Volkan,
>> 
>> On Mon, 23 Oct 2023 at 10:40, Volkan Yazıcı  wrote:
>>> 
 it [doesn't] fully documents what was in prior releases
>>> 
>>> Why is this a problem? We document newly added features with "starting
>> from
>>> version X, Log4j ships Y...". Doesn't this address your concern?
>> 
>> I prefer to document each new public/protected class or method with a
>> `@since` tag. We often don't do that (e.g. even in 2.21.0 there are a
>> couple of new methods).
>> 
>> Maybe there is an automatic scanner that can do it.
>> 
>> Piotr
>> 

Re: [log4j] Project URLs per major version

[Volkan Yazıcı]

Let me elaborate on what I want to achieve with CI automation.

*[I will focus on Log4j, but my statements apply to other Maven-based
products as well; Log4j Tools, Log4j Kotlin, etc.]*

   1. When a new Log4j `release/A.B.C` branch is detected, `logging
   *-log4j-A_B_C.staged*.apache.org` will be automatically populated using
   `./mvnw site`
   2. When a new Log4j release of version `A.B.C` is detected, `
   logging.apache.org*/log4j/A.B.C*` will be automatically populated using
   `./mvnw site`
   3. When a change in `A.x` branch is detected, `logging.apache.org
   */log4j/A.x*` will be automatically populated using `./mvnw site
   -Drevision=A.B.C`, where `A.B.C` will be determined at runtime as the
   latest published release of major version `A`

#2, I initially didn't want to. Though had calls with Piotr, Ralph, Gary,
and Matt yesterday, and decided to keep that. #2 causes the Git repository
to blow up. Matt had some tips, I will propose a workaround soon.

On Mon, Oct 23, 2023 at 1:38 PM Christian Grobmeier 
wrote:

> This sounds pretty cool Volkan, if I didn't get anything I pretty much
> like it.
> One question - you wrote:
>
> "we all will enjoy automatically populated Log4j websites."
>
> Does this mean we will see our website is updated automatically by CI so
> we can see in example /log4j/dev?
> Or what else is "automatically updated"?
>
>
>
> On Sun, Oct 22, 2023, at 22:20, Volkan Yazıcı wrote:
> > Currently, we have the following folder structure in the
> > `logging-log4j-site` repository for the Log4j project:
> >
> >- `log4j-1.2.17` – the website generated by the last Log4j 1 release,
> >i.e, `1.2.17`
> >- `log4j-1.2` – symlinks to `log4j-1.2.17`
> >- `1.x` – symlinks to `log4j-1.2.17`
> >- ...
> >- `log4j-2.19.0` – the website generated by the `2.19.0` release
> >- `log4j-2.20.0` – the website generated by the `2.20.0` release
> >- `log4j-2.21.0` – the website generated by the `2.21.0` release
> >- `2.x` – symlinks to `log4j-2.21.0` (the latest Log4j 2 release)
> >
> > I propose keeping existing folders as is (hence, *no changes to the
> > existing URLs!*) and applying following practices:
> >
> >1. *Add a `latest` symlink* pointing to the latest stable version.
> Today
> >it will point to `2.x`, sometime in the future it will point to `3.x`.
> >   - This will make following URLs possible:
> >   https://logging.apache.org/log4j/latest
> >   - This convention is practiced by several other projects, e.g.,
> >   Spring Boot: https://docs.spring.io/spring-boot/docs/current
> >2. *Redirect root to `latest`*, i.e., `logging.apache.org/log4j`
>  will
> >redirect to `logging.apache.org/log4j/latest`
> 
> >3. *Don't create a new folder for every release, but override the
> `2.x`
> >folder.*
> >   - This is okay, since we keep backward compatibility in minor+patch
> >   releases and explicitly provide version for features that are
> added later
> >   on (e.g., "starting from 2.17.0 Log4j provides X...")
> >   - We can set up CI jobs to periodically populate `1.x`, `2.x`,
> `3.x`,
> >   `4.x`, etc. websites and avoid the need to generate the website
> once and
> >   for all.
> >   - We will stop polluting the folder structure.
> >
> > As a matter of fact, I already implemented this convention for some
> > projects. All the following URLs work:
> >
> >- `logging-parent`
> >   - logging.apache.org/logging-parent
> >   - logging.apache.org/logging-parent/latest
> >   - logging.apache.org/logging-parent/10.x
> >- `logging-log4j-kotlin`
> >   - logging.apache.org/log4j/kotlin
> >   - logging.apache.org/log4j/kotlin/latest
> >   - logging.apache.org/log4j/kotlin/1.x
> >- `logging-log4j-scala`
> >   - logging.apache.org/log4j/scala
> >   - logging.apache.org/log4j/scala/latest
> >   - logging.apache.org/log4j/scala/13.x
> >- `logging-log4j-tools`
> >   - logging.apache.org/log4j/tools
> >   - logging.apache.org/log4j/tools/latest
> >   - logging.apache.org/log4j/tools/0.x
> >- `logging-log4j-transform`
> >   - logging.apache.org/log4j/transform
> >   - logging.apache.org/log4j/transform/latest
> >   - logging.apache.org/log4j/transform/0.x
> >
> > Unless there are objections, I will update the CI in this direction and
> we
> > all will enjoy automatically populated Log4j websites.
>

Re: [log4j] Project URLs per major version

[Gary Gregory]

Blow up -> become very large, not corrupted.

Gary

On Tue, Oct 24, 2023, 6:45 AM Volkan Yazıcı  wrote:

> Let me elaborate on what I want to achieve with CI automation.
>
> *[I will focus on Log4j, but my statements apply to other Maven-based
> products as well; Log4j Tools, Log4j Kotlin, etc.]*
>
>1. When a new Log4j `release/A.B.C` branch is detected, `logging
>*-log4j-A_B_C.staged*.apache.org` will be automatically populated using
>`./mvnw site`
>2. When a new Log4j release of version `A.B.C` is detected, `
>logging.apache.org*/log4j/A.B.C*` will be automatically populated using
>`./mvnw site`
>3. When a change in `A.x` branch is detected, `logging.apache.org
>*/log4j/A.x*` will be automatically populated using `./mvnw site
>-Drevision=A.B.C`, where `A.B.C` will be determined at runtime as the
>latest published release of major version `A`
>
> #2, I initially didn't want to. Though had calls with Piotr, Ralph, Gary,
> and Matt yesterday, and decided to keep that. #2 causes the Git repository
> to blow up. Matt had some tips, I will propose a workaround soon.
>
> On Mon, Oct 23, 2023 at 1:38 PM Christian Grobmeier 
> wrote:
>
> > This sounds pretty cool Volkan, if I didn't get anything I pretty much
> > like it.
> > One question - you wrote:
> >
> > "we all will enjoy automatically populated Log4j websites."
> >
> > Does this mean we will see our website is updated automatically by CI so
> > we can see in example /log4j/dev?
> > Or what else is "automatically updated"?
> >
> >
> >
> > On Sun, Oct 22, 2023, at 22:20, Volkan Yazıcı wrote:
> > > Currently, we have the following folder structure in the
> > > `logging-log4j-site` repository for the Log4j project:
> > >
> > >- `log4j-1.2.17` – the website generated by the last Log4j 1
> release,
> > >i.e, `1.2.17`
> > >- `log4j-1.2` – symlinks to `log4j-1.2.17`
> > >- `1.x` – symlinks to `log4j-1.2.17`
> > >- ...
> > >- `log4j-2.19.0` – the website generated by the `2.19.0` release
> > >- `log4j-2.20.0` – the website generated by the `2.20.0` release
> > >- `log4j-2.21.0` – the website generated by the `2.21.0` release
> > >- `2.x` – symlinks to `log4j-2.21.0` (the latest Log4j 2 release)
> > >
> > > I propose keeping existing folders as is (hence, *no changes to the
> > > existing URLs!*) and applying following practices:
> > >
> > >1. *Add a `latest` symlink* pointing to the latest stable version.
> > Today
> > >it will point to `2.x`, sometime in the future it will point to
> `3.x`.
> > >   - This will make following URLs possible:
> > >   https://logging.apache.org/log4j/latest
> > >   - This convention is practiced by several other projects, e.g.,
> > >   Spring Boot: https://docs.spring.io/spring-boot/docs/current
> > >2. *Redirect root to `latest`*, i.e., `logging.apache.org/log4j`
> 
> >  will
> > >redirect to `logging.apache.org/log4j/latest`
> 
> > 
> > >3. *Don't create a new folder for every release, but override the
> > `2.x`
> > >folder.*
> > >   - This is okay, since we keep backward compatibility in
> minor+patch
> > >   releases and explicitly provide version for features that are
> > added later
> > >   on (e.g., "starting from 2.17.0 Log4j provides X...")
> > >   - We can set up CI jobs to periodically populate `1.x`, `2.x`,
> > `3.x`,
> > >   `4.x`, etc. websites and avoid the need to generate the website
> > once and
> > >   for all.
> > >   - We will stop polluting the folder structure.
> > >
> > > As a matter of fact, I already implemented this convention for some
> > > projects. All the following URLs work:
> > >
> > >- `logging-parent`
> > >   - logging.apache.org/logging-parent
> > >   - logging.apache.org/logging-parent/latest
> > >   - logging.apache.org/logging-parent/10.x
> > >- `logging-log4j-kotlin`
> > >   - logging.apache.org/log4j/kotlin
> > >   - logging.apache.org/log4j/kotlin/latest
> > >   - logging.apache.org/log4j/kotlin/1.x
> > >- `logging-log4j-scala`
> > >   - logging.apache.org/log4j/scala
> > >   - logging.apache.org/log4j/scala/latest
> > >   - logging.apache.org/log4j/scala/13.x
> > >- `logging-log4j-tools`
> > >   - logging.apache.org/log4j/tools
> > >   - logging.apache.org/log4j/tools/latest
> > >   - logging.apache.org/log4j/tools/0.x
> > >- `logging-log4j-transform`
> > >   - logging.apache.org/log4j/transform
> > >   - logging.apache.org/log4j/transform/latest
> > >   - logging.apache.org/log4j/transform/0.x
> > >
> > > Unless there are objections, I will update the CI in this direction and
> > we
> > > all will enjoy automatically populated Log4j websites.
> >
>