Hello everyone, I totally agree on automating the website publication and having a single branch, the less we do manually, the lower the chances to mess something up.
I am also in favour of versioned docs in the website, it's confusing to land on updated pages from an older context like a message from the ML. Best regards, Alessandro On Tue, 29 Mar 2022 at 06:44, Francis Chuang <[email protected]> wrote: > Hey Julian, > > All very good points. I can definitely see the utility of the javadocs. > The analogue in Go would be godoc, with the difference being that the > godoc server automatically crawls the code across all versions to > generate the documentation. > > As an example, see the godoc for protobuf [1]. There is a version > selector on the top left to look at the documentation for different > versions of the module / library in question. > > You mentioned that you do not want to have a version string in the URL. > Is there any particular reason for this? For example, if I were to end > up on the mailing list archives through a google search and there's a > message linking to the javadoc, it might be more helpful if the javadoc > was linked to a particular version of the release so that the context > around the discussion at the time makes more sense. > > We can have all javadocs for all releases of Calcite published and have > a selector to jump between versions, similar to godoc, for example, like > this javadoc for google cloud with a version selector on the bottom > right [2]. This would allow users to switch between different versions > and look at the version of the javadoc that's currently being used in > their project. > > Regarding the documentation on the website itself, would it make sense > if we have a versioned copy for each release? Currently, we only publish > the documentation for the latest release, so, if we were to look at > older messages from the mailing list and follow a link to the > documentation, the documentation could be incorrect or not relevant to > the message itself. > > Maybe we can have a folder for each release? For example: > - > calcite.apache.org/docs/1.30.0/adapter.html#jdbc-connect-string-parameters > - > calcite.apache.org/docs/1.29.0/adapter.html#jdbc-connect-string-parameters > > This would give each release their own documentation with a unique path. > For the current unreleased version, we can still put it in version of > the next release: > calcite.apache.org/docs/1.31.0/adapter.html#jbc-connect-string-parameters > and > maybe have a message that says this is an unreleased version like > elasticsearch [3]. Links to this release's javadoc would work before and > after the release and would never break. > > The upside to this approach is that all documentation (even the > unreleased version) is published immediately, but they are versioned, so > there is no confusion. It also means that users of Calcite master would > be able to look at the docs online. This also simplifies the deployment > of site as we no longer need the site branch: the website can just be > built from master. > > Francis > > [1] https://pkg.go.dev/google.golang.org/protobuf > [2] https://googleapis.dev/java/google-cloud-asset/latest/index.html > [3] https://www.elastic.co/guide/en/elastic-stack/master/index.html >
