[PATCH 0/2] WIP: doc: add new git tutorial

["Julia Evans via GitGitGadget" <gitgitgadget@gmail.com>]

This is the first draft of a tutorial which introduces Git in two parts:

Part 1: Create an empty repo & make 2 commits (git init, git add, git
commit, git status, git diff) Part 2: Push the repo to a remote host like
GitHub or GitLab (git remote add, git push)

So far we've gotten 112 comments from 22 beta testers who have tried to
learn Git for the first using this tutorial. Most of them were able to
finish it successfully. I'd like to avoid getting into the details of every
single thing in the tutorial at this stage (we're still planning to do a
second round of feedback with the beta testers, and the beginning especially
will likely change)

There are 2 questions I'd like feedback on since they both could affect the
structure of the tutorial. I don't think either of these is a dealbreaker,
since folks generally were able to finish the tutorial despite all these
issues and said that they enjoyed it and learned a lot. But it would be
great if there were an easy way to make the process less messy.


question 1: create the repo on the command line, or in the forge?
=================================================================

One issue that came up a lot in our testing is that the tutorials explains
how to run git init in a repo to create it locally and then later choose a
forge to host that repo (GitLab, GitHub, etc) and push to the remote on that
forge.

Several users ran into the issue that GitLab by default creates a README.md,
which means that when you run your first git push, the push fails since
there's already a commit.

A few options I see:

a. Suggest that they instead create the repo on the forge and then clone it.
I think this is easier and usually I support suggesting things that are
easier, but in this case I think it's our role (as the official Git
documentation) to make it clear that you do not need a forge to use Git. IMO
this approach really confuses that issues and makes it seem like the forge
is more important than it is. b. Suggest git push --force. This is an easy
fix but I don't like suggesting that people use --force so early since it's
so dangerous. c. Just try to get users to try to figure the right way in the
GitLab/GitHub/etc UI to actually create an empty repository that it's
possible to just push to. This is really hard because the UIs constantly
change.


current solution 1
==================

Right now we're working on Option C since it seems least bad


question 2: How to handle authentication
========================================

 * How should the tutorial tell users to authenticate? I know there are
   commands like gh auth login for GitHub and IIRC GitLab and it seems like
   there are some advantages to using those, but also AFAIK they're all
   pretty specific to the individual Git forge and I don't see how it's
   possible to discuss them in a generic tutorial.
 * Whether to explain the process of creating an SSH key etc. Arguably this
   is the job of the SSH documentation, but since https://www.openssh.org/
   doesn't have such a guide, it feels bad to tell users "you should go read
   a guide on how to use SSH to do this but by the way that guide does not
   exist so good luck I guess".
 * A lot of testers found it hard to find the SSH URL on GitLab/GitHub


current solution 2
==================

Right now we're solving these by:

 1. Using SSH
 2. Explaining how to set up SSH in the easiest way possible (with
    disclaimers to check your security team's policy if applicable since the
    "easiest way" may not be the best)
 3. Giving some instructions for how to translate an HTTPS URL to an SSH URL

Julia Evans (2):
  doc: remove gittutorial
  doc: add new Git tutorial for beginners

 Documentation/gittutorial.adoc | 854 +++++++++++++++------------------
 1 file changed, 397 insertions(+), 457 deletions(-)


base-commit: 5a7d1e8045ce66c908f62598e26cbb8df7b39a90
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2248%2Fjvns%2Fgit-tutorial-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2248/jvns/git-tutorial-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2248
-- 
gitgitgadget