Opened 7 months ago

Closed 7 months ago

Last modified 7 months ago

#33585 closed Bug (fixed)

lacking hint to SSH setup (Working with Git and GitHub)

Reported by: Samuel Hartmann Owned by: Carlton Gibson
Component: Documentation Version: dev
Severity: Normal Keywords: documentation, git, github contributing, contribution
Cc: Triage Stage: Ready for checkin
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

Starting to work on #33544 I found the following:

The explanation Setting up local repository in "Working with Git and GitHub" quitely assumes that people have already set up their local Git and GitHub for use of SSH.

They say:

You should also set up django/django as an “upstream” remote (that is, tell git that the reference Django repository was the source of your fork of it):

git remote add upstream git@github.com:django/django.git
git fetch upstream

I didn't set up SSH before.
Hence I got the following error when running git fetch upstream:

The authenticity of host 'github.com (140.82.121.4)' can't be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
This key is not known by any other names
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes

Warning: Permanently added 'github.com' (ED25519) to the list of known hosts.
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

The reason and solution for that error are described in this stackoverflow reply.
Basically you need to set up an SSH key on your local machine and add it to your GitHub profile.
This enables you to connect to GitHub.

I suggest two possible solutions:

  1. insert a new section after the Installing Git section
  2. change the SSH notations (like git@github.com:django/django.git) to HTTPS notations (like https://github.com/django/django.git) instead

If the second approach makes sense, I'd prefer this one because it's easier to understand and needs less effort from a setup perspective.
Hence simplifies the start for first time contributers.

Change History (7)

comment:1 Changed 7 months ago by Mohamed Nabil Rady

Resolution: invalid
Status: assignedclosed

This seems like a Github issue and not a Django issue, I think the user can figure out the problem from the git error message.

comment:2 in reply to:  1 Changed 7 months ago by Samuel Hartmann

Replying to Mohamed Nabil Rady:

This seems like a Github issue and not a Django issue, I think the user can figure out the problem from the git error message.

From my point of view, the issue here isn't the error message itself (Of course we can't change/fix the error).
Instead the issue is that the documentation is incomplete.
The documentation is incomplete because it intends to give the correct prerequisites in the Installing Git section.
But these are actually not all requirements which are necessary to follow the subsequent steps.

Since this documenation especially targets first time contributers, I suggest to make it as easy as possible.
It took me at least one hour to get the SSH setup running.
This may definitely be enough to sicourage most of the first timers.

So my intention with this ticket is to simplify the contribution for first time contributers as much as possible, to enlarge the community which maintains Django in the long run.

comment:3 Changed 7 months ago by Carlton Gibson

Has patch: set
Resolution: invalid
Status: closednew
Triage Stage: UnreviewedAccepted

... simplify the contribution for first time contributers as much as possible

Yes, we did similar in 3c6a4fdb6d828a03e368632d88f8261cc30104da. GitHub's SSH config docs are great, but the using the HTTPS checkout can defer needing to deal with such configuration.

PR updating the remaining examples.

comment:4 Changed 7 months ago by Carlton Gibson

Owner: changed from Samuel Hartmann to Carlton Gibson
Status: newassigned

comment:5 Changed 7 months ago by Mariusz Felisiak

Triage Stage: AcceptedReady for checkin

comment:6 Changed 7 months ago by GitHub <noreply@…>

Resolution: fixed
Status: assignedclosed

In 9fed515a:

Fixed #33585 -- Made example git repo URLs use HTTPS protocol.

The SSH-based checkout requires additional configuration, which is
beneficial to defer for new contributors.

Follow up to 3c6a4fdb6d828a03e368632d88f8261cc30104da. This commit
updates the remaining examples.

comment:7 Changed 7 months ago by Mariusz Felisiak <felisiak.mariusz@…>

In c0a34bef:

[4.0.x] Fixed #33585 -- Made example git repo URLs use HTTPS protocol.

The SSH-based checkout requires additional configuration, which is
beneficial to defer for new contributors.

Follow up to 3c6a4fdb6d828a03e368632d88f8261cc30104da. This commit
updates the remaining examples.
Backport of 9fed515a251d488172feb1652bb5179344364fb3 from main

Note: See TracTickets for help on using tickets.
Back to Top