Onboarding

# Onboarding

A guide on how to contribute effectively

---

# Scope

1. Project Management
   - Github as a PM Tool
   - Creating and Managing Issues
2. Version Management
   - Trunk-based Development
   - How to Use Git
   - Conflicts

---

# Project Management

## What is project management?

A way to plan, manage and complete our project (and get an A).

## How to do project management?

For our use case, we will be mainly using:

- Github as a [single source of truth](https://en.wikipedia.org/wiki/Single_source_of_truth)
- Discord for communications and meetings

---

# Github as a PM Tool

[Github Project](https://github.com/features/issues) offers a [Kanban board](https://www.atlassian.com/agile/kanban/boards) to track tasks.

We can see:

- What tasks there are
- Who's handling each task (and also assign people)
- What's the state of each task

## Github Issues

- Issues are a way to manage task items
  - They can be linked to code and commits, which we will get into later
- You should **ALWAYS** create tasks via issues

---

# Issue Demo

---

- Go to the project repository's issue page and create a new issue

![Step 1](assets/issue-demo/1.png)

- Name the issue appropriately
  - Add a description if the task requires deeper explanation

![Step 2](assets/issue-demo/2.png)

---

- On the right sidebar, set the:
  - Assignee(s) - Person working on this issue
  - Type - Type of issue (feature, bug, RND, etc.)
  - Project - The project this issue falls under
  - You can ignore the other attributes for now

---

- You can now create the issue!

![Step 4](assets/issue-demo/4.png)

- When doing the task, ensure that the status of it stays updated

---

- Provide updates when you have done/found something

- When the task is completed, you may reply with the result and close the issue to mark it as completed

![Step 7](assets/issue-demo/7.png)

---

Here's how the issue looks like in the project view:

![Step 8](assets/issue-demo/8.png)

---

# It's your turn!

- Go to the [onboarding repository](https://github.com/10x-Slackers/onboarding) and create a new issue
  - Title: [Name]'s onboarding
  - Remember to set assignee, type (RND), and project accordingly
- Once the issue has been created, set the status to "In progress"

---

# Version Management

## What is version management?

A way to track and manage changes to our codebase.

## How to do version management?

- We will be using [Git](https://git-scm.com/) as our version management tool
  - **PLEASE watch [this video](https://www.youtube.com/watch?v=SWYqp7iY_Tc) and [read this](https://rogerdudler.github.io/git-guide/) if you are not familiar with Git**

---

# Trunk-based Development

- We will be using [trunk-based development](https://trunkbaseddevelopment.com/) as our branching strategy
  - In short, we all use a single branch (main) to work on
  - We create short-lived branches for features/bug-fixes and merge them back to main quickly
- By effectively using issues, we can ensure that everyone is working on different tasks and avoid conflicts
  - Branches should be linked to issues and named according to the issue ID (1, 2, 3, etc.)

---

# Conventional Commits

- In order to keep our commit history clean and meaningful, we will be following [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary)
- The commit message should be in the format of `<type>(<scope>): <description>`
  - **Type**: feat, fix, docs, style, refactor, chore
  - **Scope**: optional, but should be the area of the codebase being changed (e.g. auth, ui, api)
  - **Description**: a short description of the change
  - Example: `feat(auth): add login functionality`
- Not sure what to write? You may try using AI tools, but ensure that it follows the format above

---

# Version Management Demo

---

- Ensure that you have git installed
  - You can check by running `git version` in your terminal
  - If not, please install it from [here](https://github.com/git-guides/install-git)
- Create an issue, then click on "Create a branch" at the sidebar

![Step 1](assets/git-demo/1.png)

---

- In the dialog pop-up, modify the branch name to match the issue ID and click "Create branch"

![Step 2](assets/git-demo/2.png)

---

- Copy the commands in the new pop-up and run them in your terminal
  - If you have not yet cloned the repository, do so first by running `git clone <repo-url>`
  - If you have no idea what the commandas are, please watch the video linked earlier

---

- Now, you can make changes to the codebase
- When you are done, stage the changes by running `git add .` in your terminal
- Then, commit the changes by running `git commit -m "Your commit message"` in your terminal
  - Ensure that your commit message is descriptive and meaningful
- Finally, push the changes by running `git push origin <branch-name>` in your terminal

![Step 4](assets/git-demo/4.png)

---

- You may make more changes and commits, and push them as needed
- When you are ready to merge, go to the repository's pull request page and you will see a prompt to create a pull request
  - Click on "Compare & pull request"

![Step 5](assets/git-demo/5.png)

---

- Ensure that the base branch is "main" and the compare branch is your branch
- Change the pull request title to follow conventional commits

![Step 6](assets/git-demo/6.png)

- Click on "Create pull request"

---

- You may make more changes and commits again, and push them as needed
- When you have completed your task, ensure that the pull request has been approved by at least one other person
  - You can ping someone on Discord to review your code
- Once approved, you may merge the pull request by clicking on "Squash and merge"
  - If not approved, you may make changes and push them again

---

- After merging, pull the latest changes to your local main branch by running:
  - `git checkout main`
  - `git pull origin main`
- You can also delete your branch locally by running:
  - `git branch -d <branch-name>`

---

# It's your turn!

- Using the issue you created earlier, create a branch
  - Add your name to guestbook.txt and commit the change
- Create a pull request and get it approved by at least one other person
  - Remember to follow conventional commits
- Once approved, merge the pull request
  - The issue will be automatically closed once the pull request is merged

---

# Conflicts

- Conflicts occur when two or more people make changes to the codebase at the same time
- If a conflict occurs, Git will notify you when you try to push your changes

---

# Conflict Demo

- I'm too lazy to make a demo for this
  - PLEASE watch [this video](https://www.youtube.com/watch?v=DloR0BOGNU0) instead