Learn about our Git standards and processes in [#git]

This guide provides a high-level step-by-step direction for navigating our Git collaboration workflow at LinkORB. While it aims to help new team members (particularly technical writers unfamiliar with Git) contribute to our repositories, other stakeholders outside the engineering team who contribute to documentation would benefit from reading this guide at least once.

Prerequisites

This guide assumes you have read the following documents before contributing documentation to a Git repository:

Example Git collaboration workflow

The entire Git git collaboration workflow from when you are assigned a task (through a Team HQ card) to the time a pull request (PR) is merged should look similar to the following:

Step 1: Make a copy of the repository

  1. After a team member assigns a card to you or after you assign a card to yourself, the card becomes visible in your Team HQ (My GTD Inbox) dashboard. Scroll to the bottom of the card’s Timeline and Acknowledge the assigned card.

  2. If you are contributing to the GitHub repository related to the task for the first time:

    1. Create a fork of the repository if you do not already have one.

      A fork is your own copy of a repository. Unlike the organization’s repository where you might have read-only access, you can easily make changes to your fork and then request to merge it with the organization’s copy (fork) through a pull request.

    2. Clone your fork of the repository to your local machine or open it in a Codespace.

      See Creating a Codespace for guidance.

      git clone /the/git/repo's/url

      Note that Git must be installed on your computer if you wish to clone your fork to your computer and work on it locally.

    3. Configure LinkORB’s commit message template for that repository if it is not automatically setup.

    If you have previously created a fork of the repository:

    1. Synchronize the main branch of your fork so it is up to date with the upstream repository.

    2. Pull the latest changes from the main branch of your fork (on GitHub) into the main branch of the cloned repository in your Codespace or local computer.

      1. Click the source control icon button in the side bar.
      2. Click the ellipsis (…) at the top of the source control tab.
      3. Select Pull.
      1. Click Current branch in the top bar.
      2. Select main from the list to switch to it.
      3. Click Fetch origin in the top bar.
      4. Click Pull origin.

      1. Switch to the main branch.

        git switch main

      2. Pull down the latest changes.

        git pull

      Git may ask you to authenticate over HTTPS or SSH when working in a local environment (on your computer).

Step 2: Apply your changes to a new branch

  1. Create a new branch on your local machine or in a Codespace and name the branch using branch naming conventions as a guide.

    Always create a separate branch off the main branch for each Team HQ card and terminate the branch’s name with the related Team HQ card’s number as directed in this guide. Never create a new branch from any branch other than the main branch if you wish to merge it into the upstream (organization’s) fork.

  2. Make the changes outlined in the Team HQ card related to the task.

Step 3: Review the changes you’ve introduced

  1. Recheck the card in Team HQ to ensure you have made all the required changes.

  2. Review changes to the repository to ensure that only the files you worked on have changed.

    1. Click the source control button in the sidebar.
    2. Review the list of files in the Changes section.
    3. Click any changed file to see changes that were made to it.

    1. Review affected files.

      git status

    2. Review changes to each file.

      git diff

      You may review changes to a single file or folder by passing a file or folder name/path to the git diff command.

    3. To discard changes you don’t want to keep, run:

      git restore THE-FILE-YOU-DON-NOT-WANT-TO-CHANGE

    For documentation updates, complete the following checks:

    1. Find and fix any broken links: See Scan for broken links in web applications and Scan for broken links on the LinkORB Engineering site for guidance.

    2. Check that Markdown is formatted correctly: See Lint Markdown documents.

    3. Check grammar/tone: See Proofreading with Vale.

    4. Preview your changes in a browser (locally/Codespace) or using the preview feature of a Markdown editor. Read the entire page, and pay attention to potential formatting issues.

      Instructions for how to view web applications in a browser are usually documented in the README.md file at the root of a repository.

      To preview your changes when working in a Codespace:

      1. Open the integrated terminal.

      2. Click the Ports tab.

      3. Click the globe button in the Local address field of the active port.

        If there is no active process in the ports tab, click the Terminal tab and start the web application as explained in the README.md file before doing steps 1 to 3 above.

Step 4: Stage the changes

  1. From the source control menu, place the mouse cursor over a file you wish to add to the commit and click the add (+) button. Do this for each file you want to commit to Git.
  2. Click Commit.

See Selecting changes to include in a commit

  1. Add files containing desired changes to the staging area.

    git add SPACE SEPARATED LIST OF CHANGED FILES OR FOLDERS

  2. Verify that only the files you wish to commit to version control have been staged.

    git status

Step 5: Save the changes

Commit your changes to the repository.

  1. After staging files in the source control panel, enter a commit message in the Message field using the commit message template as a guide. Please see our conventional commit standards for more information.
  2. Click Commit.

See the following guides:

  1. Commit the changes.
git commit
  1. Enter the commit message using the commit message template as a guide. Please see our conventional commit standards for more information.
  2. Save the commit message and exit the commit message editor.

Step 6: Merge the saved changes with your GitHub fork

Push changes to your fork of the repository on GitHub.

In the source control menu (from the sidebar), click Publish.

Click Push origin in the top bar to publish changes to GitHub.

Pass the -u or --set-upstream and specify the branch you want to your changes to (as shown below when) pushing changes to a GitHub branch.

git push --setupstream origin main

You only need to run the above command once per branch. Subsequent pushes should be done with:

git push

Git may request that you enter your SSH or GitHub password in order to publish changes.

Step 7: Ask team members for feedback/suggestions on the changes

  1. Create a pull request to merge your changes into the upstream (organization’s) repository.

  2. Request a PR review got get team members’ feedback or suggestions by:

    • Clicking the Reviewers button on the right pane of the PR’s Conversation tab and selecting team reviewers.

    • Sending a message to the Cyans topic related to the task.

      If the task doesn’t have a topic yet, create a topic and link it to the card.

  3. Repeat step number #5 through #10 above to address the feedback and suggestions you receive.

Squasing is a fairly technical operation that may confuse new Git users. Feel free to skip this section if you’re not up for it 😉.

  1. Once the reviewer(s) approve the PR, inform them that you will squash related commits to reduce the size of the PR.
  2. Follow the steps outlined in Squash related commits into one to squash the PR.
  3. Review your changes to ensure that the squashed commits have not introduced a bug.
  4. Inform the reviewer(s) that you’re done squashing 😉.

Step 9: Publish your work to the team or the public

The reviewers will approve and merge your PR.

Step 10: Verify the changes on the production site

If your PR introduced changes to a web application, please verify the changes on the production site after the PR is merged. Verifying changes on the production site can identify possible bugs and other issues (e.g., formatting) that were not obvious in development and staging environments.

Further reading

About Git