Skip to content

GitHub Workflow

After completing the setup steps, you are ready to work on your code and data. This guide walks you through using git and github to manage your project.

Overview

  1. Create an issue in your repository in GitHub to plan changes with your team
  2. Create a new branch from the main branch
  3. Make edits to the data, code, documentation, etc
  4. Commit changes and push to remote
  5. Create Pull Request (PR) and add a Reviewer
  6. Implement feedback
  7. Merge PR into the main branch
  8. (Recommended) Remove local feature branch to keep your workspace tidy

1. Create an Issue

Creating an issue is a simple way to coordinate with others and document the decision process. The issues become a history log of a particular feature of the project allowing you and new collaborators to orient yourselves quickly.

When creating an issue:

  • Use Markdown to format the text1
  • Describe the problem or element to be addressed
  • Describe your proposed plan to address that problem
  • Discuss with collaborators2

2. Create a Branch

When creating a new branch, it's good practice to use a prefix to organize branch names. Your team should agree on a convention. Examples include:

  • Type of change: feature vs fix
  • Component affected: scripts vs data vs docs
  • Collaborator identifier (initials or username): fridakahlo vs georgiaokeeffe

For example, if your team chooses feature vs fix your branches might look like:

  • feature/add-water-temp-qc-script
  • fix/empty-csv-row-added
  1. Open a Terminal (in RStudio or the Git-Bash terminal)
  2. Navigate to the project directory, if needed
  3. If you've made any local uncommitted changes, run git stash
  4. Run git switch main
  5. Run git pull
  6. Run git switch -c [prefix]/[branch-name]
  7. If you stashed any changes, run git stash pop
  1. Open Positron
  2. Open the Command Palette (Ctrl + Shift + P)
  3. Enter "Git: Create Branch From..."
  4. Search for "main" and select
  5. Enter a name for your new branch in the form [prefix]/[branch-name] (see above)
  1. Click on the Git tab in the upper right pane in RStudio
  2. Click the dropdown next to 'New Branch' and ensure it says main
  3. Click on the Pull button
  4. Close the status pop-up
  5. Click New Branch
  6. Name the branch following [prefix]/[branch-name]

3. Make Changes

Make your edits to the project files.

It's good practice to only make the changes outlined in the original GitHub issue. You may notice other changes that could be made, but making those changes in addition to the planned changes will create a messy commit history and make it harder for a reviewer to understand your work.

4. Save Changes

  1. Run git status to see what files have been modified
  2. Run git add [file_1] [dir_2] to "stage" these files
  3. Run git commit -m "[your commit message]" (see below)
  4. Run git push

If you need to "unstage" a file while keeping the changes you've made run:

git restore --staged [filename]

  1. Save any changes
  2. Expand the Version Control section from the left-hand vertical menu
  3. Under Changes, hover over a file and click the '+' to stage it
  4. Or stage all modified files at once by hovering over the Changes header and clicking the '+'
  5. Enter a commit message
  6. Click Commit
  7. Click Publish Branch or Sync Changes to push your changes to the remote repository

See the VSCode documentation for more info

  1. Click the Git tab in the upper right pane in RStudio
  2. Click Commit
  3. Click Stage
  4. For each file listed, review your edits
  5. (Optional) Unselect staged files to exclude them from this commit
  6. On the right, enter your commit message (see below)
  7. Click Commit
  8. Click Push
File Status (untracked, unstaged, staged)

Within a git repository, files can be untracked (not monitored by git), unstaged or staged.

  • Untracked files are not recorded or managed by git. You must add them with git add [file] if you need to track them.
  • Unstaged files are tracked files that have been modified since the last time they were committed.
  • Staged files are modified files that have been added to the group of files that will be associated with the next commit you make.
Commit Message Tips
  • Summarize the changes
    • e.g. "Add new qc steps for biodiversity samples (#123)"
  • Link commits to GitHub issues
    • e.g. by adding "(#xxx)", pushing this commit will link the original github issue #xxx
    • e.g. by adding "closes #xxx", pushing this commit will auto close that github issue.

5. Request Feedback (PR)

  1. Go to the repository in GitHub
  2. Click the Pull request tab
  3. Click New pull request
  4. Set the "base" to main
  5. Set the "compare" to your [prefix]/[branch-name]
  6. Scan list of commits and changes
  7. Click Create pull request
  8. Enter a title that summarizes what this PR adds
  9. Add any notes in the description (e.g. how you tested the changes or remaining questions you have)
  10. Click Create pull request (optionally create the PR as a draft)
  11. Along right side, add a Reviewer (an individual or a Team, like 'nearshore')

Email data@hakai.org to discuss using teams in GitHub.

6. Implement Feedback

Your reviewer should test the changes you made and offer feedback. After you've received their review, you can go back to your original [prefix]/[branch-name] and add those changes, then stage the files you edited, commit them, and push them. They will automatically be appended to the open PR for that branch.

7. Merge Changes

  1. When ready, click Merge pull request
  2. (Optional) Modify the PR commit message. Close the original issue by appending "closes #xxx"
  3. Click Confirm merge3
  4. If your PR triggers any automations, you can view them under the Actions tab

Email data@hakai.org to learn more about automation options.

Once a branch has been merged into the main branch, we recommend deleting it from your local repository to keep your workspace tidy. Copies of these branches, unless explicitly deleted, will remain in GitHub for future reference.

  1. Run git branch to list your local branches
  2. Run git switch main
  3. Run git branch -D [branch-name] to delete
  1. Open the Command Palette (Ctrl + Shift + P)
  2. Enter "Git: Checkout to..."
  3. Search for "main" and select
  4. Open the Command Palette again
  5. Enter "Git: Delete Branch"
  6. Search for and select the branch you want to delete

Deleting local branches is not possible through RStudio GUI. Use the integrated terminal.

Next Steps

Learn how to publish your data as a package.

  1. See GitHub's custom Markdown for options. ↩

  2. Moving relevant discussions to github issues - or at least summarizing internal threads on an issue - can help keep a public record of why changes were made. ↩

  3. See merge options for different ways of integrating your changes and shaping how the git history of the main branch is written. ↩