A GitHub Workflow Primer for xQAP Group

Prerequisites

Create a GitHub account
Apply for the Educational Benefits (Optional)
GitHub can be accessed through the web interface, command line, GitHub CLI, or GitHub Desktop. This guide, however, focuses on the GitHub Desktop version, which illustrates our workflow.
To access a private repository, you may need to request permission from the administrator.
If you contribute to public repositories and do not want your personal email address to appear in public commit metadata, make sure to keep your email address private. After making this change on the account online, update the setting on GitHub Desktop as well, so it does not create commits with your personal email address that may later be blocked from being pushed to GitHub.
This document provides an introduction to our standard workflow and typical scenarios. For more detailed information, please refer to the GitHub Docs.

Before contributing to a repository, the recommended first step is to open an issue there to discuss and clarify your intended contribution.

Create an issue (if none exists) to discuss what you plan to work on.
Apply a priority label (e.g., high, medium, low) to indicate its importance/urgency.
Assign the issue to yourself to announce that you are actively working on it, and help avoiding having 2 people working on the same issue at the same time.

Download and install GitHub Desktop
Clone a repository. If you are not a contributor, request access first; otherwise, you need fork it first, then you can clone it.

Create a new branch. Even if you have permission, you should avoid working directly on the main branch. This practice ensures that all changes are reviewed before being merged, rather than being pushed directly to the repository.

Open the cloned project in your preferred text editor (such as Visual Studio Code or Sublime Text) and implement your changes.

Project development server: Use a dedicated development server command, such as docs:dev (for vitepress sites), commonly found in project documentation.
VS Code Extension: If using VS Code, the Live Server extension provides an integrated and convenient way to preview HTML files with live reload.
npm package: Use tools like live-server and local-web-server for a simple, standalone development server.
Online tools: use website like the HTML Online Viewer, though note that some may not render dependencies like images.

Update, Don't Accumulate: When making changes, update and replace outdated sections, rather than leaving old content intact and appending new information.
Avoid Redundancy: Avoid repeated information; for example, state the required Python version only once in a dedicated section.

Use Links When Possible: Prefer linking to images rather than embedding them directly. This recommendation also applies to videos.
Image Quality and Size: Use JPG images with a quality setting of 7/12, and make them only as big as needed. In most cases, 1080p should be the maximum.

Once your changes are complete, review and commit them in GitHub Desktop.
Rule of thumb: changes in 1 file = 1 commit with a short descriptive message.
Make use of the description textfield. Add quick bullet points, including notes to reference like `- this refers to #11` or `- this fixes #11`
Using the default commit message (like `Update README.md`) and including description bullet points is much better than a longer commit message and an empty description. Make sure the commit message includes the name of the modified file, and the description clearly summarizes the changes.

Commit Changes

When editing multiple files usually Github Desktop will not provide a default commit message. This could happen for example when renaming a file, when uploading multiple image files, or when doing a very simple and repeated change across multiple files. In those rare situations you need to come up with a simple title.
If the repo you're working on has multiple files with the same name, eg `index.html`, the default commit message might not be immediately clear of which file is being edited. In those scenarios it is good to add a portion of the path to help distinguish, eg `project1/index.html` `project2/index.html` etc.
Optionally, to credit another author in a commit as co-author, click the add co-authors icon and type the username(s) you want to include.

Add co-author commit

This section is really important. Please read it again and try to really incorporate it. Good commit messages/descriptions will make glancing at the commit history of the repo a much faster process to identify what happened and where. This is absolutely crucial for both development and bug tracking.

Create Pull Request

Click Create Pull Request. GitHub Desktop will open your default browser to take you to GitHub. In the PR, clearly describe the changes using the title and description fields.
Note: You can only push the branch to GitHub if you have write access to the repository.

Choose Branch

Delete Branch

Updating PRs: If changes are requested, update the existing PR with new commits. Do not close the PR and create a new one for the same change set.
Merge Strategy: For PRs containing multiple commits (especially for repeating changes), prefer the Squash and Merge option to maintain a clean commit history.

Squash and Merge

Contributing to Forks: When contributing to a forked repository, ensure you are creating the PR against the correct fork. You can select the target fork when creating the PR. Do not attempt to merge your commits directly into the upstream repository.

Choose Base Fork and Branch

Request a review from at least one other contributor (Do not directly assign the PR to a reviewer). The PR can only be merged after receiving approval.

Request Review

In your PR description, use # to mention or reference related issues (for example, Fixes #123, Refer #123). These keywords will create links and can automatically close issues when the PR is merged. Note: Write Fixes #123, not Fixes issue #123.

😎 Happy coding!