DEV Community

Cover image for A Look into How I Manage My Personal Projects (My Git/GitHub Workflow)
Joeylene Rivera
Joeylene Rivera

Posted on • Updated on

A Look into How I Manage My Personal Projects (My Git/GitHub Workflow)

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

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 or other git hosting providers.

Table of Contents

  1. Project Overview
  2. Setting up
  3. Project Boards
  4. Issues and Milestones
  5. GitHub Templates
  6. Pull Request
  7. Merging Branches

1. Project Overview

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.

2. Setting Up

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-Baseweb initial setup.

Visual Studio Code with a Google Chrome browser on top that says "Hello World"

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

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

A new GitHub repository that doesn't have files yet

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

git remote add origin https://github.com/jorenrui/hondana-app.git
git push -u origin master
Enter fullscreen mode Exit fullscreen mode

f. Now we are all done setting up!

A GitHub repostiory that has an initial commit

3. Project Boards

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

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

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

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

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

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

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.

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

A GitHub repo's milestone tab content

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

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

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

Issues

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

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 sample task issue

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

  • 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

  • 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

Since the task issue is done, we can now move on to the Epic Issue.

A GitHub task issue

Epic Issue

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

A sample epic issue

  • 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

  • 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

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"

Issues tab that contains a lot of issues

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

An epic issue highlighting the linked tasks

After that, you're all done.

Bug Report

Since the Hondana App has no bugs yet, let me show a sample bug in my create-project repo.

A sample bug report

  • 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

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.

Branching Out

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:

# Create a branch named `feature-github-templates` from the current branch
git checkout -b feature-github-templates
Enter fullscreen mode Exit fullscreen mode

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

Templates

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.

# Create a directory/folder named `.github`
mkdir .github
Enter fullscreen mode Exit fullscreen mode

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

# Create a directory/folder named 'ISSUE_TEMPLATE' under `.github`
mkdir .github/ISSUE_TEMPLATE
Enter fullscreen mode Exit fullscreen mode

Then create the files for the issue templates and the pull request template.

# 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
Enter fullscreen mode Exit fullscreen mode

The created files will be like this:

The root directory of the app shown in tree view

Task Issue Template

The small_issue.md will contain the following:

---
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)
Enter fullscreen mode Exit fullscreen mode

Epic Issue Template

The epic_issue.md will contain the following:

--------
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)
Enter fullscreen mode Exit fullscreen mode

Bug Report Template

The bug_report.md will contain the following:

--------
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.
Enter fullscreen mode Exit fullscreen mode

Pull Request Template

Lastly, the PULL_REQUEST_TEMPLATE.md will contain the following:

# 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
Enter fullscreen mode Exit fullscreen mode

Commiting

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

git add .
git commit -m 'Add GitHub Templates'
git push --set-upstream origin feature-github-templates
Enter fullscreen mode Exit fullscreen mode

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

6. Pull Request

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

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

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

A sample of opening a pull request

A sample pull request

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 for more information.

7. Merging Branches

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

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

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

Then delete the branch from my local repository:

# Switch to master branch
git checkout master

# Delete `feature-github-templates` branch
git branch -d feature-github-templates
Enter fullscreen mode Exit fullscreen mode

The commit will now be like this:

Commit Log

This is useful when you're creating a changelog 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 👩‍💻

Discussion (11)

Collapse
edisonknew profile image
EdisonKnew

Hi, really nice works! It helps me a lot, i was always struggling to have a nice streamflow.

I'm not sure i fully understand how you manage epic with your branch

If we have one Epic
Book Page
And 3 tasks
Create Book
Read Book
Delete Book

What branchs do you create ?

1 for the epic and one for each task?

Thanx a lot for your work

Collapse
jorenrui profile image
Joeylene Rivera Author

Actually my workflow has kinda change since this post. That I create an epic branch which are versions like v1. Then task branches that are features to be done for v1 release. Also I now name them "jr.create-book" adding my initials to the branch.

Anyways, regarding the epic branches. I think you should only do it for features that are too big then chop then it up into little pieces. Since it is easier to review small PRs than bigger ones that does a lot.

Regarding what you've said above. You can create an epic branch called "feat-book-page". Then three task branches called "task-book-page-create-book", etc. that points to the epic branch. So when you create a PR also a preview deployment, you can test the book page (epic branch) before merging it to production for all to see.

Collapse
edisonknew profile image
EdisonKnew

Thanx for your answer :) i'll try it and adjust to my needs ;)

Collapse
obwana profile image
Obwana

I tried to implement this workflow with android studio, but I'm stuck in "5. Git Templates" as I can't edit the .md files after I created all the directories, is there any knowledge I'm missing. Please help I'm new to this.

Collapse
jorenrui profile image
Joeylene Rivera Author

Ahh late reply. Haven't been here on dev.to that much lately.

Anyways, you can use a normal editor like Notepad to edit the .md files. You can manually create a folder named ".github" then inside create those ".md" files then edit them using a text editor.

Collapse
obwana profile image
Obwana

Thanks

Collapse
brandnk profile image
Brandon King

Thanks for sharing this. I learned a lot!

Collapse
rush profile image
Aarush Bhat

Is it good to follow such an elaborate workflow?

Collapse
jorenrui profile image
Joeylene Rivera Author

Depends on your needs and preference. Not every workflow is suited to every project/everyone.

Cause some find that this is a drag on smaller projects. But helpful for big ones where you collaborate with someone else.

Collapse
rush profile image
Aarush Bhat

i tried out the workflow for a big project of mine, i think it'l really streamline my work! thanks!

Thread Thread
jorenrui profile image
Joeylene Rivera Author

That's great. Glad it worked out! 😊