Git Workflow

⚠️ IF YOU ARE NEW TO GIT AND GITHUB:

we highly recommend that you read about Git Branches and read this entire page CAREFULLY and COMPLETELY

Creating/assigning an issue

We use GitHub issues to keep track of what needs to be worked on. Feel free to take a look at the current issues list here.

Assigning an issue

If you see an issue that you would like to work on that's great! To help keep track of what everyone is working on please assign it to yourself so we can see who is working on which issues:

If you are not part of our org and therefore cannot self assign to the issue feel free to leave a comment asking us to assign it to you.

Creating an issue

If you have a suggestion for a feature we should implement or you notice a bug feel free to create an issue for it! You can do so via the "New Issue" green button on the top right of the issues page. From there you can select an appropriate template and describe your issue/suggestion in as much detail as possible, this will help whoever is working on it to understand the intention.

Please also add the appropriate labels to your issue to help categorize it.

Working on an issue

If you haven't already done so, navigate to your local repo and use the following command to pull the most recent version of the repo:

$ git pull

Create a New Branch

1. We are using the main branch as our deployment branch. You'll want to create a new branch for the issue you are contributing to.
2. Use the following to create a new branch:

$ git checkout -b NameOfYourNewBranch

3. Publish your new local branch to remote

$ git push origin NameOfYourNewBranch

Work With Your Branch

1. Add, create or modify files as you see fit according to the issue you are working on. Git will track any changes you make (provided they are in the project folder)
2. You want to add the files you want to keep track of to the staging area of git. You do so with:

To add a specific file
$ git add fileName

Or to add all changes
$ git add .

3. It is good practice to make a new commit every time there is significant change to the file(s) you are tracking:

$ git commit -m "brief description of what you did"

4. If this seems confusing, Codecademy has a Git Course or check the Git Handbook

5. Once you are finished with all your changes and you have used commit to add them to the staging area, push them to remote:

$ git push origin NameOfYourNewBranch

6. After your changes are pushed to GitHub, you can go to the repo page and create a pull request (PR for short) so that others can review your work and approve the changes.

PRs

1. Once your commits are pushed to origin (the repo hosted on GitHub), you will see a new message on the site, something like "[branch name] has recent pushes" and a green button with "Compare & Pull Request". Click it.
2. On the right side you should see a menu with an option to add reviewers. Invite others to review your work! Lyallstewart, aedwardg, Victoria-DR and mikejoh12 are the main contributors so feel free to request a review from one, or multiple, of us.
3. Don't forget to add a meaningful comment to your PR. It should be brief and explain why your changes should be merged into the DEV branch.
4. You can also use keywords to automatically link your PR to an open issue. Read all about it here.
5. Congrats on your contribution! Reviewers might either approve the PR and merge it, or post comments with feedback.

Remember to check out the main branch to ensure you have the most recent version of the code. You can get the latest version by using the following command:

$ git pull origin

Clean Up

1. Typically, we want to use one branch per issue. That means that once your PR is merged into the dev branch, you should delete the branch (and create a new one if there is another issue you want to work on).
2. Once your PR has been merged you will be able to delete the branch by clicking on the "delete branch" button at the bottom of the PR.