RFR: Section on cloning [v9]

[Jesper Wilhelmsson]

On Wed, 25 Aug 2021 08:31:02 GMT, Magnus Ihse Bursie <ihse at openjdk.org> wrote:

>> Jesper Wilhelmsson has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Personal clone
>
> 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.

Removed the checkout example.

> 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.

I have added a comment about https. I prefer to keep ssh for the most part since that's how I work and I can't verify my examples if they should assume that there are no ssh key installed.

> 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).

I use Mac Ports. It works fine (as the example shows) to build the JDK with it. Since I don't have Homebrew installed I can't write examples using it.

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

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