[Dev][Release] post-10-docs.sh doesn't work correctly for patch releases

[amoeba]

Describe the bug, including details regarding any error messages, version, and platform.

During both the 16.1 and 18.1 releases, we found the dev/release/post-10-docs.sh didn't work correctly and had to be fixed manually. See:

• 16.1: [Website] Add missing 16.0 docs from jfrog archive arrow-site#555
• 18.1: [Website] Update documentations for 18.1.0 arrow-site#565 (comment)

This should probably get fixed for the next release.

Component(s)

Developer Tools, Release

[amoeba]

Looking at the current version of the script, it looks like the idea was to only publish a single documentation set for each major version series (i.e., replace the 18.0 docs with the 18.1 docs when 18.1 is released). If this is the case, other changes would be needed, such as to how we update the version switcher.

@jorisvandenbossche do you remember what the idea was behind your change in 8963755? To fix the problem in this issue, I'm considering removing all the major/minor parts of the script.

[jorisvandenbossche]

do you remember what the idea was behind your change in 8963755? To fix the problem in this issue, I'm considering removing all the major/minor parts of the script.

That change was certainly not made to properly deal with "minor" releases (as in major.minor.patch, and at the time we only ever did major or patch releases), so the major / minor is maybe a confusing naming, but with the current set-up I think the script still needs to distinguish major+minor vs patch releases.

Right now, IIRC, the workflow goes like this:

• The latest released ("stable") version of the docs lives at the root of https://arrow.apache.org/docs, and then previous versions e.g. at /docs/18.0/
• When we make a new non-patch (major/minor) release -> at this point the current stable docs are copied to its versioned subdirectory, and then the docs of the new release are written over the old stable docs at the root of the /docs folder.
• When we make a patch release, only the stable docs at the root need to be overwritten with the new docs, as we don't keep separate docs of patch releases of the same major/minor release (e.g. of 15.0.0, 15.0.1 and 15.0.2)

Now, I do think it would probably be an improvement/simplification to already make the versioned subdirectory at the time of making the release (e.g now for 18.1.0, already make the docs/18.1/ directory), and do when doing the release just copy the new docs to two places (versioned subdir and root), then we don't have to this "move current stable docs to subdir".

---

This is all with the presumption that we indeed don't want to keep the docs of every single version. I personally still think that is better, because 1) there is typically hardly a difference between those, 2) it reduces the size of the docs, and 3) I also wouldn't want to include those in the version dropdown anyway because it would just be unnecessary noise to the user of the docs.

(personally, with the way we currently make minor releases like 18.1.0 as just a bit extended patch release, I would even argue the same for those, and just keep one version of the docs for the entire 18.x release cycle)