Feb 5, 2020 • Graham Higgins • projectdoc
The Atlassian tutorial is extensive and recommended https://www.atlassian.com/git/tutorials/install-git
Otherwise …
Documentation on:
Getting started with GitHub, Learn about GitHub’s products, sign up for an account.
Setting up and managing your Github account
Navigate to the Prime Gap List repository page on Github: https://github.com/primegap-list-project/prime-gap-list.git
and click on the button labelled “Fork”.
If a choice of destinations is offered, choose an appropriate destination. If no choice is offered the fork will be created in your Github account.
Github’s web UI will show progress. NOTE the location has changed (upper left) from primegap-list-project/prime-gap-list
to gjhiggins/prime-gap-list
The repository has been successfully forked into gjhiggins/prime-gap-list
Use the Github web GUI to copy the web URL to use for cloning (copying via downloading) the repository locally with:
cd <working area>
git clone <URL>
allgaps.sql
in your local copy of the repositoryAssuming you have already used the prime gap list project web site’s web GUI conversion facility to convert your record prime gap entries into SQL (see the illustrated guide to checking new record gaps or gaps with better merits) and have a downloaded file of SQL named (for example) prime-gap-list-conversion-2020-02-05T01_02_03.123Z.sql
NOTE in the examples below, you will need to replace references to https://github.com/gjhiggins
with references to your own account.
$ git clone https://github.com/gjhiggins/prime-gap-list.git
$ cd prime-gap-list
$ sqlite3 tmp.db <<<$'.read allgaps.sql\n.read prime-gap-list-conversion-2020-02-05T01_02_03.123Z.sql\n.output allgaps.sql\n.dump\n.quit\n'
$ rm tmp.db
$ git commit -m "Update for 2020-02-05 by <submitter>"
$ git push
$ git clone https://github.com/gjhiggins/prime-gap-list.git
$ cd prime-gap-list
$ sqlite3 tmp.db
SQLite version 3.22.0 2018-01-22 18:45:57
Enter ".help" for usage hints.
sqlite> .read allgaps.sql
sqlite> .read prime-gap-list-conversion-2020-02-05T01_02_03.123Z.sql
sqlite> .output allgaps.sql
sqlite> .dump
sqlite> .quit
$ rm tmp.db
$ git commit -m "Update for 2020-02-05 by <submitter>"
$ git push
> git clone https://github.com/gjhiggins/prime-gap-list.git
> cd prime-gap-list
> sqlite3 tmp.db ".read allgaps.sql" ".read prime-gap-list-conversion-2020-02-05T01_02_03.123Z.sql" ".output allgaps.sql" ".dump" ".quit"
> del tmp.db
> git commit -m "Update for 2020-02-05 by <submitter>"
> git push
> git clone https://github.com/gjhiggins/prime-gap-list.git
> cd prime-gap-list
> sqlite3 tmp.db
SQLite version 3.22.0 2018-01-22 18:45:57
Enter ".help" for usage hints.
sqlite> .read allgaps.sql
sqlite> .read prime-gap-list-conversion-2020-02-05T01_02_03.123Z.sql
sqlite> .output allgaps.sql
sqlite> .dump
sqlite> .quit
> del tmp.db
> git commit -m "Update for 2020-02-05 by <submitter>"
> git push
git push
After successfully forking the prime gap repository on github, the fork was reported as being “even with primegap-list-project:master”
git push
After pushing your commit (containing the changed allgaps.sql
) up to your Github fork, it now reports as “1 commit ahead of primegap-list-project:master” - time to click the “New pull request” button and generate a new Pull Request - a request to the repository maintainers to “pull” the changes from the forked repository into the main repository.
NOTE the commit message I used for this working exercise was “Update 2020-02-03 gapcoin merit improvements”, as shown next to the allgaps.sql
line
Before actually going through the exercise of actually creating a Pull Request, GitHub’s automata check the committed changes and the web GUI reports whether git can simply merge the changes straightaway or whether the changes are in conflict with the existing code, in which case a repository maintainer is required to resolve the conflicts before the changes can be merged.
In this worked example, the changes to allgaps.sql
are able to be automatically merged and so it was okay for me to click the “Create pull request” button.
Github’s automata handle the actual merging, all that’s required (by principles of good practice) is an explanatory titled comment to aid the repository maintainers in their task. I have chosen to include the output of Dr Nicely’s cglp
checker as (weak) confirmation that the primes are indeed such and in preparation for pasting the text, I have entered the appropriate Markdown code for denoting verbatim content - three backticks to denote the start and three to denote the end:
```
```
Github provides good documentation of the writing and formatting syntax used for comments.
Of particular note (for its utility in cross-referencing commits, issues and pull requests) is the Github documentation on ”Autolinked references and URLs”, especially the section “Issues and pull requests”
I then pasted the checked output copied from cglp …
=============================================================================
G= 6098 P1=165780299536768454870526593505937140570016757..(97D).. OK BPSW*1
G= 6272 P1=148710129286189176623362105968560409845985636..(97D).. OK BPSW*1
G= 6354 P1=368221405388079181400789997951967077413201972..(87D).. OK BPSW*1
G= 6364 P1=147872708725008438896840265493528800063370907..(97D).. OK BPSW*1
G= 6378 P1=114448978367781720231771001349387152044607787..(97D).. OK BPSW*1
G= 6428 P1=122297977636934185744748044406791875203549301..(97D).. OK BPSW*1
G= 6432 P1=167670307352479624859373437749938392275931638..(97D).. OK BPSW*1
G= 6618 P1=529020352802661375241399423756367771225299185..(99D).. OK BPSW*1
G= 6628 P1=206823118393258320900948642245542552398543310..(97D).. OK BPSW*1
G= 8056 P1=42025082789596485040260513128144215771069157..(117D).. OK BPSW*1
=============================================================================
Errors=0. OK=10. T=0.109 seconds.
Input=gaps.dat. CL==>./cglp4 gaps.dat<==.
=============================================================================
between the pairs of triple backticks:
By selecting the “Preview” tab, I check that my Markdown content is properly rendered …
At this point, with my comment completed and checked, all I need to do is click on the “Create pull request” button …
On clicking the “Create pull request” button, I am immediately taken to the page showing the newly-created and “open” pull request. As a repository maintainer, I have a privileged view that includes a “Merge pull request” button which is only presented to repository maintainers (a user with an “admin” role, in Github parlance), otherwise the page looks the same.
Note the small inclusion in the middle of the page …
Of interest to repository administrators, the cryptic hexadecimal code d769e23
is a hyperlink text which leads to a Github page showing an easy-to-encompass rendering of the actual changes.
Each git commit is identified by a unique SHA hash code. In this instance, the commit hash is d769e23e485468e91c33377c7bc0c33f66a0e925
as shown above - opposite my mugshot and the text “gjhiggins committed 22 hours ago”.
The shortened form d769e23
is used for convenience and to lessen the user-hostility of the full form.
The notification of an existing open pull request appears as a numeral included the “Pull requests” tab and in the web UI’s listing of open pull requests.
The listed links simply lead to the page showing the pull request. For this worked example, it is the same as that shown in “The opened pull request” above.
As mentioned above, repository administrators are exclusively shown a “Merge pull request” button which, when clicked, triggers the Github automata to perform the merge and change the status of the pull request from “open” to “closed”, changing the page content to reflect that fact.
Details of closed pull requests are accessible via the Github web UI, via the “Pull Requests” tab, i.e. All closed pull requests for prime-gap-list and for this worked example.
Note also the “Fork settings” button, exclusively shown to the user who created the pull request and which triggers an offer to delete the fork from which the pull request originated.
For a closed pull request, the “Fork settings” button is exclusively shown to the user who created the pull request.
It triggers an offer to delete the fork from which the pull request originated.
It’s good practice to delete your fork of the main prime-gap-list repository and re-create it as required because it is NOT automatically updated with subsequent changes to the main repository made by other group members.
For exactly the same reason, it’s also good practice to delete your locally cloned fork after your pull request has been accepted and closed.