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
- Project Overview
- Setting up
- Project Boards
- Issues and Milestones
- GitHub Templates
- Pull Request
- 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.
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:
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.
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
f. Now we are all done setting up!
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.
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.
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.
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.
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.
b. After that, click Create a Milestone to create one.
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.
d. With this, you can now view your created milestones under Issues tab > Milestones.
e. By clicking the milestone, you can easily see all the issues that are linked to it.
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.
In creating issues, a friend of mine taught me how I can categorize them:
- Task Issue - a small task that can be part of an Epic Issue. This can be labeled as a "good first issue".
- Epic Issue - a large task that is divided into small issues.
- 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
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.
- 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.
- Milestones. After linking the issue to the v1 milestone of the app. You can now see the issue under it.
Since the task issue is done, we can now move on to the Epic Issue.
Epic Issue
Now, let's create an epic issue regarding the library page of the application.
- 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
enhancementlabel. Since this is a feature request. - Projects. Adding it will automatically put the issue card into the To Do column of the project board:
- 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:
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.
After creating all the tasks, we can now update the epic issue and link the 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.
- 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
buglabel. 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
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
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
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
The created files will be like this:
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)
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)
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.
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
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
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:
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.
Or you may go to the feature-github-templates branch and click pull request like what is shown below:
Then let's now create a Pull Request, we'll be comparing it to the master branch.
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 Nameor can be a custom name regarding the fix.
- Task Issue:
- 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 #IssueNowill 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.
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:
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
- Epic Issue:
- 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.
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
The commit will now be like this:
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 đŠâđť
Oldest comments (13)
Is it good to follow such an elaborate workflow?
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.
i tried out the workflow for a big project of mine, i think it'l really streamline my work! thanks!
That's great. Glad it worked out! đ
Thanks for sharing this. I learned a lot!
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.
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.
Thanks
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
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.
Thanx for your answer :) i'll try it and adjust to my needs ;)
Quite similar to GitFlow, i recently found a vscode extension that handles all the git commands to create feature branches (Task Branches), release branches (Epic Branches), if you are interested here is the link to it.
marketplace.visualstudio.com/items...
This is a really nice article, with to the point info and apt example. Thank you for making this, I've implemented this for my upcoming project hope this let's me keep this organized.