---
tags: mstu5003
---

# Github Team Workflow

## Step One -- Initiate
One person from your team should create a github repository. The process is exactly the same as how you normally create a repository.
> this person will be the main controlling person. Let's call her/him ==Montana== from now on for easier reference
>

> make sure your repository is set to ==public==. If it's a private repository, your teammates can not view it.

:::info
As an example, we will use the following Github for demo purpose:
https://github.com/ymm2110/10-minutes-timer
:::

**Result after step 1:**

## Step Two -- Fork
Other members should login their own accounts, find ==Montana== 's repository, and use the `fork` botton on the upper right corner to fork the repository.
[What is fork?](https://help.github.com/en/articles/fork-a-repo)

**Result after step 2:**

After forking someone else's github successfully, you should see that in your own github account, a new github is created referencing to the orignal github.

For example, after user zhenzhenqi successfully fork user ymm2110 on a repo called 10-minutes-timer, user zhenzhenqi will see the following result:

## Step Three -- Edit
Clone or download the code to your local environment/

- if you wnat to use GitHub Desktop to clone:
1. click the "open in Desktop" button from the webpage then follow instructions
2. when the Desktop App open, use the "choose" button to change where you want to store the files if necessary. Click `clone` to complete the clone process.

- if you're using terminal to clone:
To clone, use command `cd` to navigate to the folder location you want to use, then use command `git clone` followed by the github address
For example:
`git -clone https://github.com/zhenzhenqi/10-minutes-timer.git`

Now, you have all the code ==Montana== (and other teammates') wrote in your local environment. **You can now start coding!** :smile:

When you complete a good amount of work, ==commit and push== the changes to **your** own repository.

## Step Four -- Pull Request

### Downstream to Upstream
Now, when you go you **your** own repository page on github, you should be able to see Github showing message like
> This branch is 1 commit ahead of ==Montana==:master.

Let's sync your progress back to ==Montana=='s repository

- if you're using GitHub Desktop

1. Click the `new pull request` button to create a new pull request.
[What is a pull request?](https://help.github.com/en/articles/about-pull-requests)

2. After clicking the button, you will see github showing you all of the changes you've made that are ahead of the master branch, aka Montana's branch.

3. If there's no conflict, you'll see a green message says ==√Able to merge==. Click the `new pull request` and follow the steps to create the request.

4. Now, when ==Montana== logs into his or her account, Github will display a pull request that need response. ==Montana== needs to approve the request.

- if you are using terminal,
1. cd into the cloned folder and type `git status` You will see the changes you made:

2. type the following commands to push changes

    git add --all
    git commit -m "some message"
    git push origin master

## Step Five -- Merge
### Approve the merge

Now, you created a ==request== to add your code to ==Montana=='s. But ==Montana== haven't approve this request yet.

> why ==Montana== need to approve?
> imaging you're a famous coder and create amazing resources for other programmers. Now, a ramdom person decides to contribute the project. He forked your repo, cloned, and created a pull request. If there isn't the approve process, his code will automatically be a part of yours. Maybe his codes make cool improvement, but what happenes if his code doesn't work, or conflict with your ideas? Without the approval process, your repo will soon become an open canvas that everyone can draw on it. Messy alert!

Now, let's figure out how can ==Montana== do the approval.
1. ==Montana== needs to go to the repository from GitHub Webpage. Next to the 'Pull Request' tab, there should be a little number there(`1` in our example).
2. click on title of the pull request (`changed h1 color` in our example). Github will display details of this request, and run an automatic diagnose of if there's any problems, such as code conflicts. If there's no conflict, Github will say `This branch has no conflicts with the base branch. Merging can be performed automatically.`
3. click `merge pull request`, edit the commit message or description if necessary, then click `omfirm mergre` to comfirm.
[what's a merge?](https://help.github.com/en/articles/merging-a-pull-request)
4. after comfirmation, Github will show ==Montana== that your merge is completed.
5. Now, the code online is updated and synced. But what about the version on your local environment? Go to Github Desktop, click 'fetch' button to read updates that you made online.
6. Github Desktop will show you how many changes are made (aka, how many commit is your local environment behind the online version). Click `pull origin` to download these changes to your local environment.
7. Congrats! Now, ==Montana== has the most recent updated codes on both his/her local environment and online on Github. If ==Montana== opens the project in Atom now, he/she will be able to edit the most up-to-date codes.

### solve conflicts
In the previous step, we assume that there's no conflicts. What happens if we do?

:::info
conflicts happens when two or more people work on the same code, or when you're working on an older version, but your teammates are working on a newer version, or vice versa. The best way to avoid this is
1. team members should work on differnet section of the project, so you do not conflict each other. For example, if you're team is creating a to-do list, one person can work on `to-do-item-list.tag` and another person can work on `user-login.tag`
2. Team communication is the key. ==Montana== should let others know new pull request is approved, and you should always `fetch` from ==Montana=='s code before you resume working. We'll cover fetch in the next section.
:::

How can we know if there's a conflict?
If a teammember and ==Montana== changed the same line of code, both pushed to their repository, and the teammember created a pull request. When ==Montana== tries to approve the merge, an error message will show.

Now, in the unfortunate case, if we do have conflict, we solve the probelm by
1. click the 'Resolve Conflicts' button to go to the editing page. This page will show ==Montana== exactly where are the conflicts.
2. Edit the code to keep the lines that you want to keep. Remember to delete the `<<<`, `===`, and `>>>` generated by Github as well.
3. Once done, click the 'mark as resolved' button to complete. Now, Github will give you an green checkmark to show that the problem is solved.
4. Click `comfirm merge` to comfirm. Github will pop an alert box, click `i understand`
alert window
5. Now, Github will show that the conflicts is gone and you can comfirm the merge as shown in the last step.

remember, ==Montana== still need to use Github Desktop to `fetch` and `pull` to make sure the local file is the same as the files online.

## Step Six -- Fetch and Pull
### Upstream to Downstream
Now, your repository and ==Montana=='s repository are synchronized. But how about other members in the team? Or what happens when your teammates make updates but your repository is behind? Now, once you need to sync **from** Montana's repository.

1. In GitHub Desktop, click the `current branch` tab and choose `choose a branch to merge into master`
2. Choose `upstream/master`. If ==Montana=='s repository is ahead of you, you will see a message that says `this will merge 1 commit fom upstream/master to master`. In this case, `upstream/master` means ==Montana=='s repository, and `master` means your repository.
3. Now, your local repo is synchronized with Montana's. If you check the `history` tap of Github Desktop, you can see that your merging history is here as well. Remember to `Push Origin` so that your online repo is synchronized as well.

:::info
To make sure everyone's repository are always up to date, **always** fetch from ==Montana=='s before you start to make new changes.

Montana should check new pull request regularly and make sure to approve them in a timely manner.

Team members should **NOT** work on the same tag or the same section at the same time. Otherwise your codes will conflict with each other.
:::

## Suggested Team Practice
:::success
The team should first discuss who is in charge of which part, and code individually.
Every night, all team member should commit their code and create pull request. ==Montana== should reslove all conflicts if there's any, approve all requests. All team member should fetch and pull origin after the approval.
:::