I had a quick look and it looks like clean well-thought-out code. I couldn’t figure what it was doing at a high level (e.g. what the generated URLs would look like), so I think some high-level comments would help.
+1 Thanks for your excellent work, Francis. Julian > On Mar 30, 2022, at 11:54 AM, Stamatis Zampetakis <[email protected]> wrote: > > Hi Francis, > > I went over the workflows and rules and everything looks good to me. Great > work! > > I'm +1 on merging this to master and I am OK with your suggestions about > Avatica. > > Thanks a lot for moving this forward. It will certainly save us a lot > of time in the future. > > When this goes in we need to update also our documentation. It will be a > good opportunity to test that everything is working properly. > > Best, > Stamatis > > On Wed, Mar 30, 2022, 7:50 AM Francis Chuang <[email protected]> > wrote: > >> Forgot to mention in my last message, but I am now implementing the >> automation for calcite-avatica and calcite-avatica-go >> >> For those 2 repos, we never used a site branch as we usually push the >> site after a release. If there are any small updates to the site that >> occur after the release, we just built from master and pushed it as >> there is usually no unreleased updates to the docs due to avatica not >> having much updates. This is the same situation for avatica-go. >> >> Therefore, for calcite-avatica and calcite-avatica-go, I plan to: >> - Always build from master if there's an update to site. >> - For a release, build from master and build the javadocs and publish. >> >> I think this should we sufficient for our use-case for now and should >> improve the release process and site publishing process significantly. >> If we find edge cases in the future, we can deal with those at a later >> time. >> >> Please let me know what you guys think. >> >> Francis >> >> On 30/03/2022 4:21 am, Julian Hyde wrote: >>> 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 <[email protected]> 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 <[email protected]> 于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 <[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 >>>>>> >>> >>
