I have implemented automatic site builds for Calcite in a test repo.
See:
-
https://github.com/F21/calcite-test/blob/master/.github/workflows/publish-non-release-website-updates.yml
-
https://github.com/F21/calcite-test/blob/master/.github/workflows/publish-website-on-release.yml
For the automation that does the cherry-picking to site, I used the
following rules:
https://github.com/F21/calcite-test/blob/master/.github/workflows/publish-non-release-website-updates.yml#L7
Community members, please review the rules to see if they are sufficient
for our use-case.
The rules are implemented as follows:
- All changes to files under the site folder triggers a cherry pick to
site and a site build
- If the change is to a file under site/_docs, do not trigger a cherry
pick and do not build
- If the change is to site/_docs/powered_by.md, trigger a cherry pick
and a site build.
The order of the rules is due to
https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#example-including-and-excluding-paths
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
