I think it is a good idea to provide versioned JavaDocs. However, even if we only provide the JavaDoc of the latest release, there is no need to maintain two branches (IMHO), because the processes of updating the website and JavaDoc are relatively separate processes (according to [1]). With a single branch, it is feasible to update the website regularly, and update JavaDocs only at release times.
Best, Liya Fan [1] https://github.com/apache/calcite/blob/a6a1e2cef332893fd90286098869c56529e052c3/site/README.md Alessandro Solimando <alessandro.solima...@gmail.com> 于2022年3月29日周二 17:59写道： > > 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 <francischu...@apache.org> > 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 > >
