RFR: Section on cloning [v2]

[Stuart Marks]

On Wed, 23 Jun 2021 00:17:11 GMT, Jesper Wilhelmsson <jwilhelm at openjdk.org> wrote:

>> Added a section on cloning from GitHub, and an example of building on Mac. Also fixed two minor bugs that caused problems with syntax highlighting in Atom.
>
> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Moved SSH key section

Marked as reviewed by smarks (Author).

src/index.md line 1001:

> 999:     $ git remote add upstream git at github.com:openjdk/jdk.git
> 1000: 
> 1001: In the example above I cloned my personal fork of the JDK mainline repository. You should of course use your own GitHub username instead. Then, by adding a new *remote* named 'upstream', we associate this clone with [openjdk/jdk](https://github.com/openjdk/jdk) as well. Doing this will allow the tooling to automatically create a PR request on [openjdk/jdk](https://github.com/openjdk/jdk) whenever you push a change to your personal fork. The way that works is that once you have pushed a change to your private fork, and navigate to the [openjdk/jdk](https://github.com/openjdk/jdk) repository on GitHub, there will be a message saying that you just pushed a change and asking if you want to create a PR.

"PR request" => "PR"

src/index.md line 1006:

> 1004: 
> 1005:     $ git checkout master
> 1006:     $ git checkout -b my-fix

I'm not sure whether we should recomment "git checkout -b" or "git switch -c". I think switch is safer, but the doc says that it's experimental....

src/index.md line 1050:

> 1048: * Click "Add SSH key"
> 1049: 
> 1050: Now you are ready to clone your [openjdk/jdk](https://github.com/openjdk/jdk) fork using SSH.

I suspect this SSH stuff is all fine for Linux and Mac. What about Windows? I imagine that one would need to install OpenSSH or something before this will work. I haven't done this though.

src/index.md line 1082:

> 1080:     $ curl https://download.java.net/java/GA/jdk16.0.1/7147401fd7354114ac51ef3e1328291f/9/GPL/openjdk-16.0.1_osx-x64_bin.tar.gz --output openjdk-16.0.1_osx-x64_bin.tar.gz
> 1081:     $ tar xzf openjdk-16.0.1_osx-x64_bin.tar.gz
> 1082:     $ # Get XCode from Appstore

I think this should be a separate text paragraph, not a comment in what looks like a cookbook script to building the JDK. Getting XCode is kind of a problem. You can get it from the App Store; but sometimes the App Store version is too new for the OS version you have, so you have to get an older XCode. But of course if XCode is too old then it can't build the JDK. Obviously we can't write a whole section that covers all these issues. Plus, it changes from time to time as Apple releases new versions of things. I'd suggest having a separate paragraph that talks about getting XCode from the App Store, or the possible need to get older versions from Apple's developer site. I would avoid putting too many details in this document. Probably the best fallback is to tell people to ask on the mailing list if they have trouble with this step.

-------------

PR: https://git.openjdk.java.net/guide/pull/59