Onboarding for Tech Team

Onboarding

Quick Links:

How does the Tech Team work?


Git/Github

Making Your First Contribution!

This will be instructions on how to make your first contribution, with the example of adding John Doe to the list of contributors.

  1. Cloning the repository.
    • Open a new terminal and type the git clone command followed by the GitHub repository you want to clone. In this case, it would be git clone https://github.com/stevensblueprint/blueprint_website.git. This should create a new folder on your computer with the name of the repository.
    • Cloning the repository creates a local copy of all the code that you can edit on your computer. This only needs to be run once and from here, you can keep editing this local copy and updating it from the GitHub repository when needed.git_clone_command.png
  2. Creating a new branch.
    •  Open the folder of the local repository and run the git checkout command followed by the name of the branch. When naming a branch, it's good to pick a short, descriptive name. In our case, we are adding a contributor, so we'll type git checkout -b contributors/johnDoe.
    • Notice the -b? That's used to create a new branch as opposed to checking out a branch that already exists.
    • Creating a new branch makes a new version of the code that is isolated from the main code. This means changes can be made without affecting the main code (in case something goes terribly, disastrously wrong).creating_new_branch1.png
  3. Making the change!
    • Open the file you want to edit and make the necessary changes. In this case, we will be adding John Doe to the list of contributors.making_first_change.png
    • Make sure to save the file!

  4. Adding a file to a commit.
    • Once the change is made, use the git add command followed by the local file path to the changed file, in order to include or 'stage' the change them for the next commit. Commits can be thought of as checkpoints; more on that later.
    • In this case, we made changes to the CONTRIBUTORS.MD file in the .github folder, so our file path is .github/CONTRIBUTORS.MD and we type in git add .github/CONTRIBUTORS.MD.
    • You can use git add multiple times to add as many files as you need.
    • Another option is to use git add . to add all files with changes.adding_changes_to_commit1.png
    • Note that the file path is case sensitive.

  5. Checking changes to be committed.
    • You can use the git status command to check what files have been added or "staged" for a commit. In this case, it's only the one contributors file that we added.git_status_command.png
    • You can see here that our file is under changes to be committed and is in green text. Changes not staged for commit will be in red.

  6. Committing changes.
    • With our changes made and staged, we can create a commit which is basically a checkpoint for our code. We can revert to this point if we make mistakes or need to look at the version of the code at this point in time.
    • It is also good practice to include a commit message by using the -m flag to describe what changes were made. For us, we will just say that we are adding a new contributor, like so: git commit -m "Added a new contributor!".
      • Commit Messages: When writing a commit, it is usually good practice to follow a convention. At Blueprint, we use the Conventional Commits specification: www.conventionalcommits.org
        • Most basic form: <type>: <decscription>, two common types are feat (feature) or fix (bug-fix)
    • We can commit as often as we want, or when we feel it is necessary before making big changes.git_commit_command.png
  7. Pushing the commit.
    • In order for our changes to appear on the remote repository (the one on Github), we need to push our changes using the git push command. If we run it as is, however, we will encounter an error:git_push_command_1.png
    • This is because when we create the branch contributors/johnDoe, we only created it locally and it does not exist on the Github repository. Therefore, we must run the command shown: git push --set-upstream origin contributors/johnDoe.git_push_command_2.png
    • Once the branch is set up remotely, or if the branch already existed remotely and was not created locally, we can simply use git push.
  8. Creating a pull request.
    • Once we have completed our task and pushed the changes, we can work on merging the changes back into the main code. To do this, we can create something called a pull request (PR for short) where we essentially propose the changes we made.
    • Going onto Github, you will likely see a pop-up asking if you want to create a pull request for your branch. If so, press "Compare & pull request".making_pull_request.png
    • If you don't see it, you can also create a new pull request by navigating to the "Pull requests" tab and selecting "New pull request".navigate_to_new_pr.png
  9. Approvals and Merging.
    • Next, you can put in details for your pull request such as a title and detailing what changes were made on your branch.new_pull_request.png
    • You will also see a list of approvals, some of which are run automatically. It is also necessary for at least one person to review your pull request before you can merge it with the main branch. Once your pull request is approved, hit "Squash and merge". You're done!merging_request.png
  10. What Now?
    • In order to keep your local copy updated with the remote repository (on GitHub), you can run the git pull command. This pulls all the changes made by other people.
      • Pulling changes can sometimes result in merge conflicts which is when the changes on the remote repository don't work well with your local version. See the Merge Conflict section below for more details.

         
    • For each task, your process should be something like this:
        • Step 2, create a new branch
        • Repeat Steps 3-7 as you work on your task and make changes
        • Steps 8-9 when you complete your task
          • Make revisions as needed.
  11. Merge Conflicts
    • What is a merge conflict?
      • When different versions of the code are combined, the changes don't always align well. For example, if you have a version where you changed a line of code, but the same line of code was removed in a different version, this could create a conflict.
    • How to fix?

Project Board and Tasks

Now that you know how to make changes, there's the questions of what to change.

Tasks
Project Board

If you're ever unsure of which task to pick up or having difficulty completing a task, drop by a Tech Team meeting and ask!

Git/Github Quick Reference

New to Git and Github? Checkout these resources:

Overview of Git and Github: https://wiki.sitblueprint.com/books/onboarding/page/contributing-to-blueprint-gitgithub

Full comprehensive guide/walkthrough of Git and Github: GitHub Foundations - Training | Microsoft Learn

If you prefer a comprehensive book: https://git-scm.com/book/en/v2

Or comprehensive video: Git Tutorial for Beginners: Learn Git in 1 Hour

Git Clone

git clone [<repository>]

Git Pull

git pull

Git Checkout

git checkout [-b <branch>]

Git Add

git add [<path>]

Git Commit

git commit [-m <message>]

git push

git merge [<branch-name>]


Revision #10
Created 26 September 2024 00:26:56 by Miguel Merlin
Updated 23 April 2025 18:32:55 by Chinli Ong