Onboarding

# Onboarding

A guide on how to contribute effectively

---

# Scope

1. Project Management
   - Github as a PM Tool
   - Issue Demo
2. Developer Environment
   - Set-up Guide
3. Version Management
   - Trunk-based Development
   - Conventional Commits
   - Git Demo
   - 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:

---

# It's your turn!

1. 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
2. Once the issue has been created, set the status to "In progress"

---

# Development Environment

- To prevent "it works on my machine" issues, we will be using a standardized development environment
  - Imagine if everyone had different versions of Python, Node.js, formatters, etc.
- The environment consists of such:
  - [Visual Studio Code](https://code.visualstudio.com/) as the code editor
  - [Docker](https://www.docker.com/) as the containerization tool, which is needed for:
  - [Dev Containers](https://containers.dev/) to standardize the code environment
- The next few slides will teach you how to set this up (compulsory)

---

# Set-up Guide

---

- Install [Visual Studio Code](https://code.visualstudio.com/)
  - You should have already done so if you're in CS...
- Install [Docker](https://www.docker.com/get-started)
  - To test if Docker is installed correctly, run `docker run --rm hello-world`
- Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) in VS Code
- Clone the onboarding repository
  - `git clone https://github.com/10x-Slackers/onboarding.git`

---

- Open the cloned repository folder in VS Code
- There should be a pop-up at the bottom left, click on "Reopen in Container"
  - This will take a while the first time as it needs to build the container

---

- When it's done, it should say "Dev Container: Onboarding" at the bottom left
- Open a new terminal and run `python --version`
  - It should say Python 3.11.2
  - It should look the same as the screenshot

---

# 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
  - We use a branch for each feature/bug-fix, and merge them to main when it's done
  - Branches **NEED** to be linked to issues and named accordingly (1, 2, 3, etc.) for our use case

---

# 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 **pull request title** 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`

---

# 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"

---

- 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 commands do, 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"`
  - Your commit message does not need to follow conventional commits, it is the PR title that matters
- Finally, push the changes by running `git push origin <branch-name>`

---

- You may make more commits and push them as needed
- When you're done with your task, go to the repository's pull request page
- 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
- Ensure your pull request title follows conventional commits

- Click on "Create pull request"

---

- Before merging, the pull request will need to be approved by >=1 other teammate
  - You can ping someone on Discord to review your PR
- You may make more commits if needed by repeating the steps above
  - You will need to get the PR approved again if you do so
- Once approved, you may merge the pull request by clicking on "Squash and merge"

---

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

---

# It's your turn!

1. Using the issue you created earlier, create a branch
2. Add your name to `guestbook.txt` and commit the change
   - You can test out the dev container if you want!
3. Create a pull request and get it approved
   - Ensure that the PR title follows conventional commits
4. Once approved, merge the pull request
   - The issue will be automatically closed once the pull request is merged

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

---

# 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
- PLEASE watch [this video](https://www.youtube.com/watch?v=DloR0BOGNU0) to understand how to resolve conflicts

---

# Conclusion

## You're all set!

- I hope that you're able to contribute effectively now
- If you have any questions, feel free to reach out on Discord
- If we don't get an A I am blacklisting YOU