8251549: Update docs on building for Git

[jerboaa]

Hi,

Now that OpenJDK 11u is fully on Git we should update the docs to no longer refer to Mercurial and use Git instead. The JDK 16 patch doesn't apply clean due to some differences in the file (e.g. referring to JDK 8 vs. JDK 11 in head). doc/building.html is the result of running make update-build-docs when the building.md file has the relevant changes.

Thoughts?

---

Progress

• Change must not contain extraneous whitespace
• Commit message must refer to an issue
• Change must be properly reviewed

Issue

• JDK-8251549: Update docs on building for Git

Reviewers

• Aleksey Shipilev (@shipilev - Reviewer)
• Christoph Langer (@RealCLanger - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jdk11u-dev pull/205/head:pull/205
$ git checkout pull/205

Update a local copy of the PR:
$ git checkout pull/205
$ git pull https://git.openjdk.java.net/jdk11u-dev pull/205/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 205

View PR using the GUI difftool:
$ git pr show -t 205

Using diff file

Download this PR as a diff file:
https://git.openjdk.java.net/jdk11u-dev/pull/205.diff

[bridgekeeper]

👋 Welcome back sgehwolf! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[openjdk]

This backport pull request has now been updated with issue from the original commit.

[mlbridge]

Webrevs

• 01: Full - Incremental (bbbd50ef)
• 00: Full (cce60747)

[shipilev]

The *.md change looks good, but *.html has a lot of irrelevant changes. This is usually caused by a different version of pandoc used to generate the HTML file. Please run make update-build-docs on master and see what changes it brings. The usual way is to find the pandoc version that produces the minimal changes to HTML. If we don't do this, then HTML would change every time a future contributor changes MD again.

[jerboaa]

The *.md change looks good, but *.html has a lot of irrelevant changes. This is usually caused by a different version of pandoc used to generate the HTML file.

I see. Makes sense. Do you know which pandoc version we need? I have 2.9.2.1

Please run make update-build-docs on master and see what changes it brings. The usual way is to find the pandoc version that produces the minimal changes to HTML. If we don't do this, then HTML would change every time a future contributor changes MD again.

OK. I'll try to figure it out. Thanks for the sanity check!

[shipilev]

The *.md change looks good, but *.html has a lot of irrelevant changes. This is usually caused by a different version of pandoc used to generate the HTML file.

I see. Makes sense. Do you know which pandoc version we need? I have 2.9.2.1

Look at ./make/conf/jib-profiles.js in the 11u tree and in current master. Chances are there is no exact Pandoc version that produces the same HTML file exactly, but we probably want to have it as close to current version as possible. So that we generate the HTML file once here, and then stick with the particular Pandoc version going forward.

[jerboaa]

The *.md change looks good, but *.html has a lot of irrelevant changes. This is usually caused by a different version of pandoc used to generate the HTML file.

I see. Makes sense. Do you know which pandoc version we need? I have 2.9.2.1

Look at ./make/conf/jib-profiles.js in the 11u tree and in current master. Chances are there is no exact Pandoc version that produces the same HTML file exactly, but we probably want to have it as close to current version as possible. So that we generate the HTML file once here, and then stick with the particular Pandoc version going forward.

Thanks!

Found the needed version, I think. Seems to be 1.17.2
https://github.com/openjdk/jdk11u-dev/blob/master/make/devkit/createPandocBundle.sh#L34

[jerboaa]

@shade Updated doc/building.html with with pandoc 1.17.2 now. Looks clean-ish to me. Thoughts?

[shipilev]

Thanks! There are a few unrelated hunks still (formatting in cross-compilation tables), but I don't think we need to fret about those. Looks good.

[openjdk]

@jerboaa This change now passes all automated pre-integration checks.

After integration, the commit message for the final commit will be:

8251549: Update docs on building for Git

Reviewed-by: shade, clanger

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 45 new commits pushed to the master branch:

• f4772b5: 8272602: [macos] not all KEY_PRESSED events sent when control modifier is used
• 90d5293: 8272131: PhaseMacroExpand::generate_slow_arraycopy crash when clone null CallProjections.fallthrough_ioproj
• 8f402b2: 8272628: Problemlist gc/stress/gcbasher/TestGCBasherWithCMS.java for x86_32
• 0621d9d: 8226602: Test convenience reactive primitives from java.net.http with RS TCK
• 6722cee: 8226319: Add forgotten test/jdk/java/net/httpclient/BodySubscribersTest.java
• 5ce46d9: 8248403: AArch64: Remove uses of kernel integer types
• 3db0637: 8272197: Update 11u GHA workflow with Shenandoah configurations
• 55545f4: 8225082: Remove IdenTrust certificate that is expiring in September 2021
• 12312a3: 8230841: Remove oopDesc::equals()
• 8a470e1: 8209768: Refactor java/util/prefs/CheckUserPrefsStorage.sh to plain java test
• ... and 35 more: https://git.openjdk.java.net/jdk11u-dev/compare/1538790fdcad884a40f9a91ddba8587affd034d6...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

[jerboaa]

Thanks for the review!

[RealCLanger]

LGTM, thanks for backporting.

[jerboaa]

/integrate

[openjdk]

Going to push as commit ba097ca.
Since your change was applied there have been 48 commits pushed to the master branch:

• 3a88ae7: Merge
• 3a32efc: Merge
• fdbaa23: Merge
• f4772b5: 8272602: [macos] not all KEY_PRESSED events sent when control modifier is used
• 90d5293: 8272131: PhaseMacroExpand::generate_slow_arraycopy crash when clone null CallProjections.fallthrough_ioproj
• 8f402b2: 8272628: Problemlist gc/stress/gcbasher/TestGCBasherWithCMS.java for x86_32
• 0621d9d: 8226602: Test convenience reactive primitives from java.net.http with RS TCK
• 6722cee: 8226319: Add forgotten test/jdk/java/net/httpclient/BodySubscribersTest.java
• 5ce46d9: 8248403: AArch64: Remove uses of kernel integer types
• 3db0637: 8272197: Update 11u GHA workflow with Shenandoah configurations
• ... and 38 more: https://git.openjdk.java.net/jdk11u-dev/compare/1538790fdcad884a40f9a91ddba8587affd034d6...master

Your commit was automatically rebased without conflicts.

[openjdk]

@jerboaa Pushed as commit ba097ca.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.