I have never needed or wanted a versioned Javadoc URL for Calcite. Our APIs tend to grow over time.
The only requirement I see is that we don’t pollute the javadoc/doc of the latest released version with things that are not yet released. Which would lead to two versions: latest release and head. I can see that the implementation might be simpler if we have multiple versions, but let’s be clear that that is not the requirement. Julian > On Mar 29, 2022, at 6:49 AM, Fan Liya <liya.fa...@gmail.com> wrote: > > 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 >>>
