Automation for OpenJ9 API doc

[AdamBrousseau]

Automate the generation of API doc for OpenJ9. Simon Rushton added the ARCHIVE_JAVADOC: true param to the nightly builds to generate API doc for Java 8 and 11, now we need a process to get that into the hosted user doc. Here are suggested steps, kicked off when a developer commits an update that includes API doc comments in the code:

1. Run a compile after every PR is merged so that only a single PR is "tested" for doc changes. Specify the ARCHIVE_JAVADOC: true param to generate the API doc.
2. Create a branch on the functional ID's fork of openj9-docs repo.
3. Take the docs zip from the compile, extract and move as necessary to overlay (populate the docs/api/jdk8 and docs/api/jdk11 folders), check for changes, commit, push a branch to the bot account's fork.
4. Open a PR to commit the update to the openj9-docs repo.
5. Add a "Jenkins doc stage" comment to the PR, to stage the update in the OpenJ9 draft docs.
6. Possibly send a notification to the developer that the draft API doc is ready to be checked (with a link), or the build instructions tell developers to look the following day (if we compile nightly), or the instructions tell developers to look for a relevant PR in the openj9-docs repo.

ID team can then merge the PR manually once a feature is definitely in the release, like they do already for user doc.

Build instructions will need updating to explain.

• Saves manual effort for developers and ID in getting API doc published.
• Avoids API doc updates being missed or forgotten.
• Published API doc
• Eclipse builds
• API folder

Possible TODO list:

• Merge builds (per jdk version) (on the fastest platform) with ARCHIVE_JAVADOC true
• Follow-up build to pull javadoc, overlay, commit, push
• Tie together merge build and api doc build
• Automated PR from new branch
• Kick off doc stage from PR
• Ping @ dev who made change from PR

[AdamBrousseau]

Merge builds setup to run daily for now on zlinux jdk8 & 11

First PR opened manually for the initial update (8/11)
#639
https://ci.eclipse.org/openj9/job/Pipeline-Build-Javadoc/

[pshipton]

Really we should be generating the javadoc from the release branches. i.e. we should generate the javadoc from v0.22.0-release before publishing the docs for this release, and then from v0.23.0-release for the next one. Otherwise we could have head stream changes that don't match the release. If we want to interim javadoc updates along the way, that's fine, but the final updates before doc publish should match the released content.

[doveye]

Seems sensible to me. We can get Javadoc from the head stream during development, so developers can check their updates, but the final doc publish can use the release branch. So I guess https://ci.eclipse.org/openj9/job/PullRequest-Doc-test_on_staging_site/ needs to use the head stream and https://ci.eclipse.org/openj9/view/Website-Doc/job/Build-Doc-Push_to_Eclipse/ the release branch?

[AdamBrousseau]

The master branch of docs is built and pushed to the GH Pages branch after each PR merge. The Release branch is pushed to Eclipse (production site). So assuming the release branch is split accordingly with the right changes I think we only need to be concerned about keeping master up to date for the scope of this issue. During release cycle it may be a manual process to cherry-pick changes for a release branch (double delivered). Does that sound correct?

[SueChaplain]

FWIW I agree that we need to be sure the release branch has the appropriate changes. We tend to create the release branch just before we publish, so at that point we need a way of verifying that it is accurate. If it contains API changes that are destined for a future release, these would have to be removed. So not really double delivering, more like uncommitting. I'm sure you can do this in Git but noone in the ID team currently has any cherry picking skills and the idea of a manual step at the end isn't ideal.

Could we ensure that master does not contain content for the next release in the same way we currently do for doc updates (PRs remain open at openj-docs until the release closes)? i.e. hold back those PRs at OpenJ9 with a release target?

[AdamBrousseau]

I guess there's a few options

1. Leave PRs for future releases open until they're ready to ship/merge.
2. Merge everything into master and split a hand-rolled release branch that has future commits removed.
3. Merge everything into master and keep a release branch hand-maintained that gets changes cherry-picked which will be shipped for next release. (sort of reverse of 2)

Going to take manual effort from what I can see. First option may be easiest to show what's outstanding. Second option runs the risk of missing a change to be removed. Third option runs the risk of forgetting about a change and it never gets into a release.

[SueChaplain]

Yeah, I like (1) best.

(2) is risky

(3) will be a lot more. work because user doc changes typically come late so we'd be doing a lot of double delivering.

[pshipton]

We should be creating PRs from the OpenJ9/extensions master/openj9 branches until we split a release branch. Then the doc updates should come from the release branches until the release is completed. At which point we can switch back to creating PRs from master.

[SueChaplain]

We should be creating PRs from the OpenJ9/extensions master/openj9 branches until we split a release branch. Then the doc updates should come from the release branches until the release is completed. At which point we can switch back to creating PRs from master.

So in theory we should not see any API doc updates come to openj9-docs/master for the next release until the job switches back to building from openj9/master. This would work fine although I don't immediately see how @AdamBrousseau might build the intelligence into the pipeline job. It would have to flip between master/release branch depending. on where we were in the dev cycle?

[AdamBrousseau]

Yea I'm not sure how this is going to work. The javadoc is built from a branch of OpenJ9. Each automated PR would contain the changes from the previous build/PR. Unless I'm misunderstanding I don't see how this is possible.

[pshipton]

As I've mentioned before, we don't need to update the javadoc after every OpenJ9 PR merge. Create a job that runs one a week (on a schedule which we can modify as desired) and builds the javadoc from specified branches. I'll keep it up to date with the releases.

[SueChaplain]

I think the idea of running it per change was that the developer could go check the docs to make sure the update was as expected. I don't have a problem with it being once a week as long as the changes get reviewed.

[AdamBrousseau]

To confirm my understanding, if we build the doc from an OpenJ9 release branch, it will only contain doc changes set to go out in that release?

[pshipton]

Correct.

[pshipton]

Note that all the OpenJ9 doc changes have been reviewed as part of the PR review, although not in javadoc form.

[AdamBrousseau]

To summarize, it sounds like we can have our regular cadence build pushing all changes to master and a second build at release time which pushes to a release branch. That release branch is what will be pushed to Eclipse. Agree?

[pshipton]

Not sure if docs has a release branch in advance of a release? I'm not sure at what point the branch is created. Everything is merged to master, changes which don't apply to the release are held back until the release is completed.

[SueChaplain]

We only create a release branch shortly before GA as there are usually last minute things to update. So if it is easier, we'd want PRs that apply to future releases held back. Once we've branched, those can be merged in to master.

Then the automation is just to regularly build the API doc to master. The existing build/publish to Eclipse (from branch) would cater for API doc aswell as the rest once we branch.??

[AdamBrousseau]

To confirm, PRs held back at OpenJ9, and only delivered once Docs has split (not when openj9 has split).

[pshipton]

Nothing will be held back at OpenJ9. OpenJ9 creates a release branch well in advance of the release, and continues to merge changes to master. This will not change.

[AdamBrousseau]

Ok I think I'm sorted now.
We will regularly build master, which will contain latest OpenJ9 with Javadoc changes. OpenJ9 will split for release early. We will continue to build master. Once Docs splits for the release, we will launch a "release" build(s) that will build the doc from the OpenJ9 release branch and push to the doc release branch. This will (likely) in turn "rollback" some changes that weren't destined for the release. This will look funny for the history on the release branch but I think that is the cost of this workflow.

[SueChaplain]

In reality, Javadoc updates are few and far between, so in most cases, I think this will be fine.