RFR: Section on cloning [v9]

[Magnus Ihse Bursie]

On Sun, 22 Aug 2021 23:34:02 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:
> 
>   Personal clone

Changes requested by ihse (Author).

src/index.md line 1003:

> 1001: If you intend to contribute patches to the JDK, you should first *fork* the JDK repository on GitHub and clone your own *personal fork* as shown below. To fork a project on GitHub, go to the [project page](https://github.com/openjdk/jdk) and click the 'Fork' button in the upper right corner, then follow the on screen instructions.
> 1002: 
> 1003: All pushes to [openjdk/jdk](https://github.com/openjdk/jdk) require an SSH key which must be installed on GitHub. If this is the first time you clone your personal fork of the [openjdk/jdk](https://github.com/openjdk/jdk) repository you may want to create an SSH key to use with it. See [Generating an SSH key] below. Once you have your personal fork and an SSH key to go with it, go ahead and clone.

This comment is either wrong or irrelevant. A normal developer cannot push to the openjdk/jdk repo. For your personal fork, you may chose to not use SSH, and instead use https.

src/index.md line 1017:

> 1015: Here we create a new branch called `JDK-8272373` based on the `master` branch and set the repository up to work in that new branch.
> 1016: 
> 1017: Starting from Git version 2.23 there's also `git switch` that can be used instead of `git checkout`.

Since 'git checkout' has the potential for catastrophic data loss, all modern git usage suggest using 'git switch' for switching branches. I recommend you suggest just 'git switch' and then perhaps parenthetically notices that prior to git 2.23 'git checkout' is needed instead.

src/index.md line 1027:

> 1025: ## Generating an SSH key
> 1026: 
> 1027: For security reasons you should always create new keys and use different keys with each repository you clone. The `ssh-keygen` command generates an SSH key. The `-t` option determines which type of key to create. `ed25519` is recommended. `-C` is used to add a comment in the key file, to help you remember which key it is. While it’s possible to use SSH without a passphrase, this is **strongly discouraged**. Empty or insecure passphrases may be reset using `ssh-keygen -p`; this doesn’t change the keys.

Personally, I believe using ssh is a lot of hassle (as these paragraphs shows; a third of the new section is devoted to ssh key handling) and think the https/PAT route is much simpler. Maybe you should at least mention it as an alternative, if you do not want to suggest it as the primary way to access Github.

src/index.md line 1090:

> 1088: 
> 1089: The second example is from a clean (newly installed) Mac running MacOS Big Sur. Please note that in this case there are some steps taken outside of the terminal. First XCode and the XCode command line tools must be installed. It could be that the most recent version of XCode that you get from App Store is too new to have been properly tested with the JDK build. See [the JDK build instructions](https://github.com/openjdk/jdk/blob/master/doc/building.md#apple-xcode) for supported versions and more details in case you need to install an older version of XCode.
> 1090: In this example [Mac Ports](https://www.macports.org) is used to install `autoconf`. `autoconf` can also be installed using [Homebrew](https://brew.sh) and surely through other sources as well.

Mac Ports is virtually dead. Homebrew usage dwarfs Mac Ports by magnitudes (see https://www.scivision.dev/homebrew-macports-fink/ for usage data). I recommend you switch the example to use Homebrew (and possibly mentions Mac Ports, but seriously, I don't think anyone ever tried to build OpenJDK on mac using Mac Ports so I'm not sure how well that woks).

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

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