Github Work Flow

Initial Setup

Ensure your SSH keys include a valid SSH key for your local git repository https://docs.github.com/en/enterprise/2.16/user/github/authenticating-to-github/reviewing-your-ssh-keys

Firstly, create a 'Fork' of the central repository, using the Github UI (Fork top-right) This is now a personal repository, linked to the central repository. All of my work goes to my fork first.

For info on forking: https://docs.github.com/en/enterprise-server@2.20/github/getting-started-with-github/fork-a-repo

Setup model is always

Clone the forked repo on github

$ git clone <myfork on github>/<example_repo>
$ cd example_repo
$ git remote add upstream <mainProjectOrg>/<example_repo>

now origin is my copy and upstream is the main project

Operation rules

• never push to upstream
• always push to origin
• only push to origin/main with content from upstream

    OrgRepoGithub   ⟵ PR ⟵  personalForkGithub

              ↘                    ↗  ↙

                   myLocalGitRepo

remove the risk of accidental push to upstream

$ git remote set-url --push upstream DISABLE

(http://sushihangover.github.io/git-set-up-a-fetch-only-remote/)

Standard working pattern

my 'always do' workflow

$ git fetch upstream
$ git checkout -b <branchName> upstream/main
$ ... <stuff> ...
$ git push origin <branchName>

• When the working branch on my fork is ready to go
  • Pull Request the branch to in github when ready for review
    • The Github UI deliver this functionality

This ensures that every new branch, for every new activity, starts from the most up to date upstream/main at that time.

Adding commits to a branch once a PR is open is fine, and a good way to respond to feedback.

A new branch for each new activity is a good model for working with the repository.

to update my github master branch on my github fork from upstream (as required)

$ git fetch upstream
$ git checkout upstream/main
$ git push origin upstream/main:main

This is useful to do periodically. Having my fork's main branch up to date with upstream lets me do useful things, including checking CI test pipelines on my fork.

This is the only time to work locally with the main branch. Don't use main for local work.

Merging changes into the main repo

When merging changes from a pull request into the upstream main branch (ie, after a review), use the GitHub UI Squash and Merge option, to keep the history clean and clear.