A Look into How I Manage My Personal Projects (My Git/GitHub Workflow)
Tags: productivity, github
Published: 2020-05-15 10:59:12

> I'll discuss how I create and manage my projects using Git/GitHub. Also, I'll be tackling how I use GitHub's project boards, issues, and pull requests.
>
> Note: This is NOT a comprehensive tutorial about Git/GitHub so I won't dive deep into those topics.
>
> Photo by [Yancy Min](https://unsplash.com/@yancymin) 

Like anyone who first started using Git, when I start working on a project, I just create a GitHub repository then commit directly to the `master` branch. I don't _branch out_ from `master` whenever I'm working on a feature or a bug fix.

Tho as I started growing, meeting new devs, and gain experience in working as a developer, I started to rethink my way of creating projects. Since most of my commits are "Fix typo", "Refactor code", and commits like "Welp" lol, my git logs ended up kinda messy. So with that, I decided to re-work my workflow 😉

PS: Although this is my GitHub workflow, you can also do it on [GitLab](https://about.gitlab.com/) or other git hosting providers.

## Table of Contents
1. [Project Overview](#project-overview)
2. [Setting up](#setting-up)
3. [Project Boards](#project-boards)
4. [Issues and Milestones](#issues-milestones)
   - [Milestones](#milestones)
   - [Issues](#issues)
     - [Task Issue](#task-issue)
     - [Epic Issue](#epic-issue)
     - [Bug Report](#bug-report)
5. [GitHub Templates](#github-templates)
   - [Branching out](#branching-out)
   - [Templates](#templates)
     - [Task Issue Template](#task-issue-template)
     - [Epic Issue Template](#epic-issue-template)
     - [Bug Report Template](#bug-report-template)
     - [Pull Request Template](#pull-request-template)
     - [Commiting](#commiting)
6. [Pull Request](#pull-request)
7. [Merging Branches](#merging-branches)

## 1. Project Overview <a name="project-overview"></a>

For this post, I'm gonna create the frontend of a book database app wherein I can store books that I've read and books I'm planning to read.

Why create a specific app?

I just prefer explaining my workflow using an existing app, rather than an app called "my-awesome-project" as I did in the past. Tho I'm not gonna finish it hahaha or will I? I'll just use it for explanations. I'll also be using [VS Code](https://code.visualstudio.com/).

## 2. Setting Up <a name="setting-up"></a>

a. To get started, let's create a folder for the repository and set up the initial files.

In this case, I named the folder `hondana-app` and worked on a [NextJS-Styletron](https://www.styletron.org/getting-started/#with-nextjs)-[Baseweb](https://baseweb.design/getting-started/setup/) initial setup.

![Visual Studio Code with a Google Chrome browser on top that says "Hello World"](https://dev-to-uploads.s3.amazonaws.com/i/w69ox3pyx3nsi0r56rkd.png)

b. Then initialize the project as a git repository using either the "Initialize Repository" button found in VS Code or by running `git init` in a terminal.

c. Afterward, let's do an **Initial Commit** like so:

![VS Code with the version control sidebar opened](https://dev-to-uploads.s3.amazonaws.com/i/sdkc0y7atvq628ab4ekz.png)

d. After that, it's time to use GitHub 😁 Btw I just google translate "bookshelf" to Japanese, in case you're curious about the name, `hondana app`.

![Creating a GitHub repository](https://dev-to-uploads.s3.amazonaws.com/i/pk0r71zruchfdifmfngt.png)

![A new GitHub repository that doesn't have files yet](https://dev-to-uploads.s3.amazonaws.com/i/z3r42030ohshxviqnnpa.png)

e. Then let's push the initial commit. But first gotta add the remote origin:

```bash
git remote add origin https://github.com/jorenrui/hondana-app.git
git push -u origin master
```

f. Now we are all done setting up!

![A GitHub repostiory that has an initial commit](https://dev-to-uploads.s3.amazonaws.com/i/opvfvropag2492pl2r4j.png)

## 3. Project Boards <a name="project-boards"></a>

In GitHub, you can create **project boards** to manage your repository. With this, you can put all your notes and tasks (_issues_ and _pull requests_) in a single place.

![Empty Project Tab of a GitHub Repository](https://dev-to-uploads.s3.amazonaws.com/i/8odshzrexdvb7ip2pk6c.png)

To create a project board, go to your repository. After that, go to the **Projects Tab** then click **Create a project** like how it is shown above.

For now, I'm going to name it as **Hondana App**. This project board is gonna be a roadmap for the app. Tho you can create multiple project boards for a single repository. For example, you may create a project board for your app's documentation, frontend, backend, etc.

![Creating a new GitHub project board](https://dev-to-uploads.s3.amazonaws.com/i/i8asnr9qkc3hd7j11lae.png)

GitHub also has a project template in which you can use. A _Kanban Board_ has a Todo, In Progress, and Done column. As for me, I prefer using an _automated kanban with reviews_. With this, when issues and pull requests are automatically moved from To Do, In progress, Reviews and Done. Tho if you're the only one on a project then I suggest the _automated kanban_ since there will be no code reviews.

![Seleting a GitHub's Project Template](https://dev-to-uploads.s3.amazonaws.com/i/x50p99l4ltywvszsce46.png)

This board has five columns: Todo, in progress, review in progress, reviewer approved, and done. When you create a pull request, it will be added into the _In progress_ column. When a code review is being done, it will move to _Review in progress_, if the reviewer has accepted your Pull Request, it will then be moved to _Reviewer approved_. Lastly, when you merge the pull request into the "master" branch it will be then be moved to _Done_.

![An automated GitHub Project Board](https://dev-to-uploads.s3.amazonaws.com/i/x6y6bpbcf676zxxebp5n.png)

Since this board is an automated one, we don't necessarily need to touch it. We just need to links our issues and pull requests to this board. I'll show you how to do it in the next part.

## 4. Issues and Milestones <a name="issues-milestones"></a>

Since the project board is all set up, let's now move on to creating some issues. Issues can either be tasks that you need to do or bugs that your application has.

### Milestones <a name="milestones"></a>

Tho before creating issues, first we need to create **Milestones**. These can be the goals you have for your app. It can also be the versions of your app. As for me, I use milestones in versioning my app.

For example, for the initial version of the hondana app, I plan to finish the following features:
- User Authentication
- View a list of books that I plan to read, currently reading, and have read
- Add books wherein I can put status like to read, reading, and done
- Delete the books in the app

For the second version of the app, I plan to finish the following features:
- Add notes to books I have read
- Add reviews and give a 5-star rating to the books that I have read
- Add search functionalities

With this, all the issues and pull requests related to that version can be organized into a single milestone.

a. To start, go to the **Issues Tab** of the repository, then click **Milestones**.

![A GitHub repo's Issue Tab that has no content yet.](https://dev-to-uploads.s3.amazonaws.com/i/195n4ldotknjbtzga7h7.png)

b. After that, click **Create a Milestone** to create one.

![A GitHub repo's milestone tab content](https://dev-to-uploads.s3.amazonaws.com/i/vens2lshni0ezhc4gs6t.png)

c. Then input the title of your milestone. Here, I put **v1** as the milestone's title. You can also add a deadline in you want.

![Creating a new milestone in GitHub](https://dev-to-uploads.s3.amazonaws.com/i/xi6pjaosm7fnhye9sgko.png)

d. With this, you can now view your created milestones under Issues tab > Milestones.

![A GitHub repo's milestone tab that has a v1 milestone](https://dev-to-uploads.s3.amazonaws.com/i/j8ffoy9lo648n4a7v9wd.png)

e. By clicking the milestone, you can easily see all the issues that are linked to it.

![v1 milestone that doesn't have any issues yet](https://dev-to-uploads.s3.amazonaws.com/i/xfgjuazlxd23c4tzvxls.png)

### Issues <a name="issues"></a>

In creating you can either create it by going to the _Issues Tab_ of your repository, like the image shown below, or by going into a specific milestone.

![A GitHub's repo Issue Tab wherein the "New Issue" button is shown](https://dev-to-uploads.s3.amazonaws.com/i/582u25nywjzf56up24qi.png)

In creating issues, a friend of mine taught me how I can categorize them:
1. **Task Issue** - a small task that can be part of an Epic Issue. This can be labeled as a "good first issue".
2. **Epic Issue** - a large task that is divided into small issues.
3. **Bug Report** - it contains information that is needed to fix a bug that the user has encountered.

To understand them a bit more, let's create our first issue.

#### Task Issue <a name="task-issue"></a>

![A sample task issue](https://dev-to-uploads.s3.amazonaws.com/i/10lbvs6kn2m7i9a6352y.png)

In this part, I'll show you how to create GitHub templates, but first, let's create those issues.

- **Issue Title**. As you can see, I named the issue title as _Task: Add Github Templates_ since this is a task issue.
- **Description**. There's a format I follow in creating issues wherein I write the following:
  - Task Title
  - Description
  - Linked Epic Issue (optional)
  - In this case, there's no linked epic issue yet. I'll show you the format in a bit.
- **Assignees**. I assigned it to myself since I'm the only one working on this project.
- **Labels**. GitHub has default labels in which you can use. Tho you may customize it and add some new ones if you want. Anyways, Tasks/Epics are commonly labeled as "enhancement" or "documentation". Tho in this case, I decided to add "enhancement" as its label since I think of templates as features.

![GitHub's list of labels](https://dev-to-uploads.s3.amazonaws.com/i/e3uhz1acq50ftrsfuhym.png)

- **Projects**. By adding the project board that we've made earlier, we may now see the issues' progress. As you can see, linking the issue will automatically put it to the _Todo_ column of the board. Since this is an automated project board, you don't need to move this card by yourself.

![A Project Board that contains a single task issue](https://dev-to-uploads.s3.amazonaws.com/i/lba666k2q40dw5hogpa2.png)

- **Milestones**. After linking the issue to the _v1_ milestone of the app. You can now see the issue under it.

 ![A v1 milestone that contains single issue](https://dev-to-uploads.s3.amazonaws.com/i/ym63bxctya0dysu6apdh.png)

Since the task issue is done, we can now move on to the _Epic Issue_.

![A GitHub task issue](https://dev-to-uploads.s3.amazonaws.com/i/5h8q8l144hjoziqd8l2r.png)

#### Epic Issue <a name="epic-issue"></a>

Now, let's create an epic issue regarding the library page of the application.

![A sample epic issue](https://dev-to-uploads.s3.amazonaws.com/i/cpubhj64o4x7k2k4q4z1.png)

- **Issue Title**. As you can see, I named the issue title as "Feature: Library Page" since this is an epic issue.
- **Description**. There's a format I follow in creating epic issues wherein I write the following:
  - Epic Title
  - Description
  - List of Tasks
  - In this case, the task issues aren't linked yet since those issues haven't been created yet.
- **Assignees**. I assigned it to myself since I'm the only one working on this project.
- **Labels**. I added the `enhancement` label. Since this is a feature request.
- **Projects**. Adding it will automatically put the issue card into the **To Do** column of the project board:

![A project board that contains two issues](https://dev-to-uploads.s3.amazonaws.com/i/mm1qd0zdq2ug0xwitiee.png)

- **Milestones**. Linking it to the **v1** milestone will make it appear under it. Also since the epic issue is composed of tasks, you'll see the progress of the issue based on the checklist like shown below:

![A v1 milestone that contains two issues](https://dev-to-uploads.s3.amazonaws.com/i/l09t8lcmielxlq0pe2ch.png)

Since the epic issue is created, let's now create those tasks.

In these tasks, we can now link its epic parent which is `Feature: Library Page #2`.

![A task issue with the title of "Task: Done Reading Tab Panel #6"](https://dev-to-uploads.s3.amazonaws.com/i/724ho1mwfiqnzex1utku.png)

![Issues tab that contains a lot of issues](https://dev-to-uploads.s3.amazonaws.com/i/plgniavs1znegniildiq.png)

After creating all the tasks, we can now **update** the epic issue and link the tasks.

![An epic issue highlighting the linked tasks](https://dev-to-uploads.s3.amazonaws.com/i/55gxejqfv2fayvpxugdg.png)

After that, you're all done.

#### Bug Report <a name="bug-report"></a>

Since the _Hondana App_ has no bugs yet, let me show a sample [bug in my create-project repo](https://github.com/jorenrui/create-project/issues/12).

![A sample bug report](https://dev-to-uploads.s3.amazonaws.com/i/hcm3w9fwxk0nljxeyav0.png)

- **Issue Title**. As you can see, I named the issue title as "Bug: Fix broken links in npm" since this is a bug report.
- **Description**. There's a format I follow in creating bugs wherein I write the following:
  - Title
  - Description
  - Steps to reproduce the bug (optional)
  - Expected result (optional)
  - Actual result (optional)
- **Assignees**. I assigned it to myself since I'm the only one working on this project.
- **Labels**. I added the `bug` label. Since this is a bug report.
- **Projects**. Adding it will automatically put the issue card into the **To Do** column of the project board.

## 5. GitHub Templates <a name="github-templates"></a>

Now it's time to show you how to create GitHub templates! So in this part we'll be working on this issue: [Task: Add GitHub Templates #1](https://github.com/jorenrui/hondana-app/issues/1).

### Branching Out <a name="branching-out"></a>

Whenever I'm working on a feature request or bug fix. I first create a branch from the `master` branch (sometimes it can be the `develop` branch).

For naming the branch I follow this format:
- Bug Fix: `hotfix-issue-name`
- Feature Request: `feature-issue-name`

So in this example, I'll create `feature-github-templates` from the `master` branch:

```bash
# Create a branch named `feature-github-templates` from the current branch
git checkout -b feature-github-templates
```

Then you'll automatically be switch to your newly created branch. After that let's create the template files.

### Templates <a name="templates"></a>

To create some GitHub templates, create a folder named `.github` in the root directory of your app name. That's where your templates will reside.

```bash
# Create a directory/folder named `.github`
mkdir .github
```

Then create a folder named `ISSUE_TEMPLATE`. This is where the templates for the task, epic, and bug issue will reside.

```bash
# Create a directory/folder named 'ISSUE_TEMPLATE' under `.github`
mkdir .github/ISSUE_TEMPLATE
```

Then create the files for the issue templates and the pull request template.
```bash
# Create the markdown files
touch .github/ISSUE_TEMPLATE/bug_report.md
touch .github/ISSUE_TEMPLATE/epic_issue.md
touch .github/ISSUE_TEMPLATE/small_issue.md
touch .github/PULL_REQUEST_TEMPLATE.md
```

The created files will be like this:

![The root directory of the app shown in tree view](https://dev-to-uploads.s3.amazonaws.com/i/1430698vyptcrn8o9xfm.png)

#### Task Issue Template <a name="task-issue-template"></a>

The `small_issue.md` will contain the following:

```markdown
---
name: Task
about: A small task that is, most likely, part of an Epic. It will usually be labeled as `good first issue`.
---

<!-- Issue title should mirror the Task Title. -->

# Task Title

Task: Awesome Task Title

## Task Description

This Task will...

## Epic Parent

<!-- The link below should link to its Epic Parent. -->

[Feature: Awesome Feature Title](https://github.com/username/repository-name/issues/1)
```

#### Epic Issue Template <a name="epic-issue-template"></a>

The `epic_issue.md` will contain the following:

```markdown
---
name: Epic
about: A task large enough that it needs to be divided into smaller tasks. It will usually be labeled as `enhancement`.
---

<!-- Issue title should mirror the Epic Title. -->

# Epic Title

Feature: Awesome Feature Title

## Epic Description

This Feature will...

## List of Tasks (Complete in order)

1. [ ] [Task 1: Awesome Task Title](https://github.com/username/repository-name/issues/1)
2. [ ] [Task 2: Awesome Task Title](https://github.com/username/repository-name/issues/2)
```

#### Bug Report Template <a name="bug-report-template"></a>

The `bug_report.md` will contain the following:

```markdown
---
name: Bug report
about: Create a report to help us improve
---

<!-- Please search existing issues to avoid creating duplicates. -->

# Bug Report

Bug: Not so Awesome Bug Title

## Description

Info about the bug goes here.

### Steps to Reproduce

1. Step 1
2. Step 2

### Expected Result

The expected result was...

You may write the expected result or add a screenshot.

### Actual Results

The actual result was...

Would be awesome to link screenshots here and/or error messages received.
```

#### Pull Request Template <a name="pull-request-template"></a>

Lastly, the `PULL_REQUEST_TEMPLATE.md` will contain the following:

```markdown
# Story Title

[This is the Issue Title](https://github.com/username/repository-name/issues/1)

## Changes made

- made this
- did that

## How does the solution address the problem

This PR will...

## Linked issues

Resolves #1
```

#### Commiting <a name="commiting"></a>

After making the files, we make now commit the changes made and push our newly made branch along with our commits to `origin`.

```bash
git add .
git commit -m 'Add GitHub Templates'
git push --set-upstream origin feature-github-templates
```

When `feature-github-templates` has been merged with `master`. You'll now see the templates whenever you create an issue or create a pull request:

![GitHub Issue Templates](https://dev-to-uploads.s3.amazonaws.com/i/zxvyj5xhv05kyscv9tvx.png)

### 6. Pull Request <a name="pull-request"></a>

Now that we're all done with creating GitHub Templates, we may now create a _Pull Request_.

When you check out your repository, your recently pushed branches are shown. You may click the **Compare & pull request** button to create a PR.

![Comparing a recently pushed branch](https://dev-to-uploads.s3.amazonaws.com/i/57ezrspm9vsnmmqhnnyy.png)

Or you may go to the `feature-github-templates` branch and click **pull request** like what is shown below:

![Seleting a branch and creating a pull request](https://dev-to-uploads.s3.amazonaws.com/i/jlmipqtsmjxp3no1afjw.png)

Then let's now create a Pull Request, we'll be comparing it to the `master` branch.

![A sample of opening a pull request](https://dev-to-uploads.s3.amazonaws.com/i/kfy4x5za6sve2g13bhsy.png)

![A sample pull request](https://dev-to-uploads.s3.amazonaws.com/i/yp1500va6e9asj8enm5t.png)

If you have **reviewers**, then you're code will be subject to _approval_. 

The format of the Pull Request is:
- **PR Title**. The title of the PR is based on the issue that it is going to resolve.
  - Task Issue: `Task: Issue Name`
  - Epic Issue: `Feature: Issue Name`
  - Bug Report: `Hotfix: Issue Name` or can be a custom name regarding the fix.
- **Story Title**. This is the issue name.
- **Changes Made**. This is your commit summary. You may add jargon here and additional technical details regarding the change.
  For example:
  - Add Redux as a state container
  - Add Theme Provider
- **How does the solution address the problem**. It will contain an explanation for normal people.
  For example:
  This PR will add the ability to login and logout of the application.
- **Linked Issues**. Adding `resolves #IssueNo` will automatically close the linked issue when the pull request has been merged. See GitHub's [Linking a pull request to an issue](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue) for more information.

### 7. Merging Branches <a name="merging-branches"></a>

When I merge branch I prefer **Squash and merge**. This action _squashes_ the branch into one commit before merging. I'll explain in a bit as to why I prefer this.

![Merging a pull request](https://dev-to-uploads.s3.amazonaws.com/i/pajmjmpaax57ivsncb4s.png)

> EDIT: I don't use squash and merge anymore since it greatly affects the history. Now, I prefer a normal git merge with commit.
 
After picking **Squash and merge**, you'll be able to add the commit message. Like shown on the image below:

![GitHub's squash and merge form](https://dev-to-uploads.s3.amazonaws.com/i/z7kdzbj0p6c06dncg51j.png)

For the commit message:
- **Title**. The title is based on the PR title and the name of the issue that it resolves.
    - Epic Issue: `[Finishes #IssueNo] Feature: PR Title #PRNo`
    - Task Issue: `[Finishes #IssueNo] Task: PR Title #PRNo`
    - Bug Report: `[Hotfix #IssueNo] PR Title #PRNo`
- **Description**. The description is copied from the PR's description.

After merging it, it will now create the merge commit and the PR in the project board will automatically be moved to Done. Then you may now delete the branch.

![GitHub's after merging a PR info](https://dev-to-uploads.s3.amazonaws.com/i/x4u4o9pegr14qs1o80is.png)

Then delete the branch from my local repository:

```bash
# Switch to master branch
git checkout master

# Delete `feature-github-templates` branch
git branch -d feature-github-templates
```

The commit will now be like this:

![Commit Log](https://dev-to-uploads.s3.amazonaws.com/i/2wutw8milnhdvgdih54x.png)

This is useful when you're creating a [changelog](https://keepachangelog.com/en/1.0.0/) and when you're working on a legacy project that has tons of features. You will easily see the changes and the info regarding each commit. This is why I prefer squash and merge. Also, I tend to create commits like "Refactor code" and "Fix typo", so seeing a clean log of commits is refreshing.

## Wrapping Up

In managing your repositories, you can create project boards to organize your issues and pull request. Then add milestones in versioning your app. You may also organize your issues into three categories: task, epic, and bug report. Lastly, merge your pull request.

That's just one way of managing your project. You can make it your own by customizing it like adding some tests or GitHub actions. It's all up to you. Experiment and see what works best for you 😉.

Thanks for reading and happy coding 👩‍💻