GitHub is a service to host repositories and provides a lot of features/utilities around this task. There are many others but GitHub is the oldest and probably most used. GitHub provides extensive documentation and (video) guides, so in order to honor the DRY principle, only little text is found here but instead a list of deep links to chapters and other learning resources is provided here:
- Training guides on GitHub and Git
- Video Guides on various topics
- Create, cloning and archiving of repositories
- Committing changes to your project
- Collaborating with pull requests / proposing changes to your work with PRs
- Proposing changes to your work with pull requests
- Using the power of GitHub on the CLI
- GitHub Training Lab
- Visualizing Git
While there are many git workflows out there, having your repository on GitHub make the GitHub Flow your first choice. As explained on the git workflows page, it's simple even for bigger teams. The documentation on the Github flow primarily explains it from technical point of view. The follow section workflow embeds these steps in an example change.
My philosophy is that every change should be documented from the beginning to the end when it's implemented. A change could be a bug and its fix or a new feature that is required and gets implemented. The order of action then is:
sequenceDiagram autonumber participant L as LocalRepo participant G as GitHub (GH) L->>G: Create an issue (bug, feature, ...) activate L L->>L: Create a feature branch (FB) loop work_on_issue L->>L: Change code and create a commit L-->>G: (optionally) Push FB to GH end Note right of L: When work is finally done L->>L: Cleanup your FB L->>G: Push FB to GH deactivate L activate G G->>G: Create a pull request (PR) G->>G: (ideally): Let somebody review your PR G->>G: Merge PR deactivate G activate L G->>L: Pull latest changes on main L->>L: Delete local FB L->>G: Delete remote FB deactivate L
Comments on above diagram
1) Describe the bug/feature in several dimensions to make it possible to understand the need to change something. Key questions are:
- What is broken?
- How does the error present itself?
- What are error messages that occur?
- What feature is missing?
- Which are the requirements that make the changes necessary?
2) Name the branch accordingly i.e.
5) Cleanup the branch if needed by rewording, squashing, rearranging commits using
git rebase --interactive in order to have a history that makes
12) Get yourself a or move to the next ticket
Except for the following deep links into the official documentation, no other information is available here as of yet.
GitHub on the CLI
There is a wonderful, official tool written in Go that let's you do all the GitHub related work on your CLI without the need to go to the browser. No need to switch app, enter URLs, click through to the destination page you need, just to open a new PR. All can be done in your Bash. See it in action.
The above illustrated workflow done using the tool
gh might look as follos:
gh issue create --title "Thing X fails to compile" --assignee "@me" --label "bug" \ --body "some longer text to sufficiently describe the bug" gh checkout main gh checkout -b bug_compile_error_in_X # work on file git add fileX git ci -m "Fix compilation error" git push origin bug_compile_error_in_X gh pr create -t "The bug is fixed" -b "Everything works again" gh pr merge git checkout main git pull origin main git branch -d bug_compile_error_in_X
gh comes with an excellent documentation and
local help, see
Community Health Files