# GitHub Organizations and Git Workflow

## Setting up Your GitHub Org
Please follow the below instructions to set-up your GitHub organization and repo (note: only one person per team needs to do this).

# Creating a GitHub Organization
1. Go to [github](https://github.com/)
1. Click the “+” button in the upper righthand corner
1. Select “New organization” from the dropdown
1. Select the free tier
1. Input a name for your organization (e.g., graceshopper-team-awesome)
1. Input your personal email, select “My personal account”, and click “Next”
1. Add all your teammates to this organization by searching for their Github usernames. Please also add your fellow and your instructor (my username is `nlane`). Note you can add people after this step, so feel free to continue on if you’re missing some usernames.
1. Click “Complete set-up”
1. No need to fill out this next page (“Welcome to Github”). You can scroll to the bottom and click “Submit”.

# Creating and Initializing a Repo

## Option 1: GitHub UI
1. Go to [github](https://github.com/)
1. Click the ➕ "New" button or go to https://github.com/new
1. Fill out:
- Repository name (e.g., git-demo)
- Optional: Add a description
- Choose Public or Private
- ✅ Check "Add a README file" (optional but helpful)
1. Click "Create repository"
1. Copy the SSH or HTTPS Clone URL
- Click the green "Code" button
- Choose either:
- `SSH: [e-mail]:your-username/git-demo.git`
- `HTTPS: https://github.com/your-username/git-demo.git`
1. Open your terminal and run:
- `git clone [e-mail]:your-username/git-demo.git`
- `ls` to verify the folder name
- `cd git-demo`

## Option 2: `git init` (Start Locally)
1. Open your terminal/vscode/command prompt
1. Navigate to your desired directory:
- `cd path/to/your/project`
1. Initialize a Git repository:
- `git init`
1. Add files:
- `git add .`
1. Commit:
- `git commit -m "Initial Commit"`
1. Create a remote repository on GitHub (see Option 1)
1. Link local to remote:
- `git remote add origin [e-mail]:your-username/repo-name.git`
- `git push -u origin main`

# Adding Collaborators on GitHub

## Step-by-Step Instructions
1. Go to your repository on GitHub
1. Click the **Settings** tab
1. On the left menu:
- For individual accounts: click `Collaborators & teams`
- For organizations: click `Manage access`
1. Click **"Invite a collaborator"**
1. Type the GitHub username or email of the person you want to add
1. Click their name when it appears, then click **"Add"**
1. The person must accept the invitation via email or from their GitHub dashboard

## Collaborator Permissions

| Role | Access Rights |
|-------------|----------------------------------------|
| **Read** | View code and issues only |
| **Triage** | Manage issues and pull requests |
| **Write** | Push commits, open/merge PRs |
| **Maintain**| Manage repo settings & users |
| **Admin** | Full control over the repository |

## Collaborators Checklist

- [x] Navigated to **Settings**
- [ ] Went to **Manage Access** or **Collaborators & Teams**
- [ ] Invited teammates by GitHub username
- [ ] Confirmed all collaborators accepted invite

# Creating a Project Board

## Step-by-Step Instructions
1. Go to your repository on GitHub
1. Click the **"Projects"** tab (NOT the one marked “Beta”)
1. Click **"New project"**
1. In the dropdown, choose the **second option** (Kanban-style board, not Beta)
1. Give your board a **name** (can match your repo/org)
e.g., `graceshopper-board`
1. Add a short **description**, such as:
_Agile board for managing GitHub issues_
1. Under **Project template**, select:
✅ “Automated kanban with reviews”
1. Under **Visibility**, choose:
✅ “Public”
1. Under **Linked repositories**, search for your repo and select it
- You’ll see a badge with your repo name appear
1. Click **Create project**

## Project Board Checklist

- [ ] Opened the “Projects” tab (not Beta)
- [ ] Selected the Kanban template
- [ ] Named and described the board
- [ ] Set visibility to Public
- [ ] Linked the correct repository
- [ ] Clicked **Create project**

# Protecting the Main Branch (Classic Rules)

## Step-by-Step Instructions
1. From your repo’s GitHub page, click **Settings**
1. In the left sidebar, click **Branches**
1. Under **Branch protection rules**, click **“Switch to classic rules”** at the top
1. Then click **“Add rule”**
1. Enter `main` in the **Branch name pattern**
1. Check the following options:
- ✅ Require pull request reviews before merging
- ✅ Require status checks to pass before merging (optional but recommended)
- ✅ Include administrators
1. Click **Create** to save the rule

## Checklist
- [ ] Navigated to repo → Settings → Branches
- [ ] Clicked “Switch to classic rules”
- [ ] Created rule with name pattern: `main`
- [ ] Checked:
- [ ] Require pull request reviews before merging
- [ ] Require status checks to pass
- [ ] Include administrators
- [ ] Clicked **Create** to confirm

# Git Workflow (Add → Commit → Push)

1. Check status:
`git status`
(If files are red, they’re unstaged)

2. Stage changes:
`git add .`

3. Check again (they should be green):
`git status`

4. Commit:
`git commit -m "Your message here"`

5. Push:
`git push`

# Feature Branch Workflow

1. **High level overview**:
Pull latest main → Make a branch → Commit changes → Push to GitHub → Make a PR → Get it approved → Merge into main → Start again. - ***If this is your first branch and you're already on main, please proceed to step 4***.

2. Make a GitHub issue for the feature
3. Checkout main:
`git checkout main`

4. Pull the latest main:
`git pull`

5. Create a new branch:
`git checkout -b YOUR-NEW-BRANCH-NAME`

6. Make commits:
- Use semantic commit messages:
`type(scope): message`
Example: `feat(client): switch to React-Redux`
- Keep commits focused on that branch’s purpose

7. Push to GitHub:
`git push -u origin YOUR-NEW-BRANCH-NAME`

8. Open a Pull Request:
- Select your branch → Click "Open pull request"
- Use `Closes #issue-number` to link issue(s)
- Request a review
- Make any changes requested
- Once approved and checks pass → merge to main

9. Sync main locally:
- `git checkout main`
- `git pull`

10. Repeat for your next task/feature

# Keeping Your Branch Up to Date
When teammates merge Pull Requests into main, you should update your branch so it doesn’t fall behind. You can do this in two ways:

## Option 1: Quick & Easy -- `git pull`
### This fetches and merges changes in one step.
1. git checkout main
2. git pull ***(updates your local main from GitHub)***
3. git checkout `YOUR-FEATURE-BRANCH-NAME`
4. git merge main ***(bring main's updates into your branch)***

## Option 2: Quick & Easy -- `git fetch`
1. git fetch origin ***(downloads the latest commits)***
2. git checkout main
3. git merge origin/main
4. git checkout `YOUR-FEATURE-BRANCH-NAME`
5. git merge main

✅ Tip: Do this before opening a Pull Request and after any teammate merges to main. This keeps conflicts small and easy to resolve.

# Merge Conflicts

## Resolve Locally

1. Checkout `main`:
`git checkout main`

2. Pull the latest:
`git pull`

3. Checkout your feature branch:
`git checkout YOUR-FEATURE-BRANCH`

4. Merge `main` into your branch:
`git merge main`

5. Run:
`git status`
*(Look for conflict markers in files)*

6. Manually resolve the conflicts
*(Search for `<<<<<<<`, `=======`, `>>>>>>>` markers)*

7. After resolving, stage all files:
`git add -A`

8. Commit:
`git commit`

9. Push:
`git push`

10. Go to the Pull Request to ensure conflicts are resolved