search

linagora / james-project

Mirror of Apache James Project
Apache License 2.0
70 stars 63 forks source link

[Antora] Sort out versioning #5217

Closed Arsnael closed 6 days ago

Arsnael commented 1 week ago

In Antora documentation, every doc change is made under 3.8.1-snapshot.

First of all, 3.8.1 is an official release not a snapshot. And most of new documented implemented feature should end up in a 3.9.0-snapshot and not in 3.8.1, except if backported.

Also it seems there is a 3.6.0-snapshot doc that... somehow seems to match the 3.8.1 which is inaccurate.

Sort out the doc versioning with Antora, and try to be a bit more strict and accurate in our official doc.

Arsnael commented 1 week ago

Potentially tricky...

As some parts will be common to multiple versions and some introduced by new ones.

If some pages are too complex, can just make separate pages. If just small parts different, can maybe work with version attribute and some if condition macros... Or maybe having partial versionings?

The way we organize our folders as well might matter.

Versioning is not explained very well in the doc IMO, might need to play around with it a bit

chibenwa commented 1 week ago

Isn't this file not enough? https://github.com/apache/james-site/blob/live/doc-sites/antora-playbook.yml

IE declairing we want also 3.7.x + 3.8.x + master?

https://github.com/apache/james-site/blob/29c8e3e11c55d007c62df5378946bf801326b60d/doc-sites/antora-playbook.yml#L11

chibenwa commented 1 week ago

For managing the release number it would then be, for each branch, writing the correct info within

https://github.com/apache/james-project/blob/master/docs/antora.yml

For master branch:

version: '3.9.0'
prerelease: SNAPSHOT

For 3.8.x:

version: '3.8.2'

etc...

Arsnael commented 1 week ago

I mean if you don't organize it... Look at your 3.6.0 tag, it looks like the current 3.8.1 doc to me

=> https://github.com/apache/james-site/blob/staging/doc-sites/antora-playbook.yml

I mean you still need to differentiate it somehow somewhere in your antora pages right? How antora is supposed to know that this or that feature in that page is from what "version"? The versioning in place isn't working imo, aint that simple

Arsnael commented 1 week ago

It's cool and all saying we want 3.7.x and 3.8.x and 3.9.0-snapshot doc but we wrote all doc without really thinking versioning until now.

The current state of the doc is defo 3.9.0-snapshot. To find back what parts are or not for prior version is gonna (not) be fun

chibenwa commented 1 week ago

How antora is supposed to know that this or that feature in that page is from what "version"?

Because it would exist or not on the git!

It's cool and all saying we want 3.7.x and 3.8.x and 3.9.0-snapshot doc but we wrote all doc without really thinking versioning until now.

Because the way ANtora works allow you to do this without thinking...

Look at your 3.6.0 tag

We may switch to branches

Do you want me to prove it works?

chibenwa commented 1 week ago

image

chibenwa commented 1 week ago

I even added a little redirection so that there is still an entry within James server distributed.

We do not loose previous versions. We easily find new location.

If this is OK to you, I can PR all those changes.

image

Arsnael commented 1 week ago

OK no I just understood, you associate the tag to the corresponding branch, and in the branch the code source will have the state of the doc for that version.

Lack of sleep, was completely off sorry.

Don;t hesitate to PR this yes no problem

chibenwa commented 1 week ago

Lack of sleep, was completely off sorry.

:+1: no issue! Been there.

chibenwa commented 1 week ago

We would need to also polish the current site like ...

chibenwa commented 1 week ago

https://github.com/apache/james-project/pull/2328

https://github.com/apache/james-project/pull/2329

https://github.com/apache/james-project/pull/2330

https://github.com/apache/james-project/pull/2331

https://github.com/apache/james-site/pull/51

chibenwa commented 1 week ago

We would need to also polish the current site like ...

CF https://github.com/linagora/james-project/issues/5218