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 > >>>> > > >
