Working in a team requires an organized workflow to manage the codebase
efficiently, making it easier to review code and resolve conflicts. Let’s
explore the key points in the GitHub workflow, a topic I’m passionate about
because I love keeping things organized.

Issues

There’s no single right way to divide tasks into issues; it usually starts with
team agreement. The GitHub workflow typically begins by creating an issue to assign tasks.

Imagine we have three tasks for our application: fixing the existing auth flow, improving the login page styling, and creating an admin dashboard. The issues might look like this:

[FIX]: Fix auth flow
[STYLE]: Improve login page styling
[FEATURE]: Implement admin dashboard

You can also break down issues into subtasks, such as:

[FEATURE]: Implement admin dashboard

[SUB-FEAT]: Implement dashboard UI
[SUB-FEAT]: Implement dashboard APIs

Generally, the issue naming convention follows this format:

[<type>]: <short-description>

Branches

After creating an issue, the next step is to start coding by creating a branch
separate from the main branch. This separation ensures that any errors during development won’t affect the production environment.

GitHub offers a feature that allows you to link an issue to a branch. This means that when the branch work is completed and the pull request is merged, the issue is automatically closed. To create a branch, navigate to the issue page, find the “Development” section on the right, and click “Create a branch.”

When naming a branch, it’s good practice to include the issue number. For
example:

For [FIX]: Fix auth flow, the branch name could be fix/<issue-number>/fix_auth_flow.
For [STYLE]: Improve login page styling, it might be style/<issue-number>/improve_login_page_styling.
For [FEATURE]: Implement admin dashboard, use feature/<issue-number>/implement_dashboard.
The general format for branch naming is:

<type>/<issue-number>/<short-description>

Commits

Here are some tips for committing your changes:

Commit frequently rather than waiting until all work is done.
Write clear, descriptive commit messages that explain what you did.
Use the present tense, such as “add,” “fix,” or “update.”
Use the imperative mood, like “add” instead of “added.”
Keep the message under 50 characters if possible.
Now, let’s consider some example commit messages for our tasks:

feat: implement dashboard header
feat: implement dashboard main content
style: add dashboard styling
fix: fix dashboard data fetching
enhance: add dashboard animations
refactor: improve dashboard API implementation
docs: add API documentation for dashboard
If you’re working in a mono repo (where frontend and backend code are in the same repository), you might use messages like:

feat(front): implement dashboard header
feat(back): implement dashboard APIs
style(front): add dashboard styling
fix(back): fix dashboard data fetching
enhance(front): add dashboard animations
refactor(back): improve dashboard API readability
docs(front): add API documentation for dashboard
The commit message format is:

[<type>]: <short-description>

Pull Requests

After committing your changes, push them to the remote branch and create a Pull Request (PR) to merge your changes with the main branch.

To create a PR, navigate to the branch page and click “Create a Pull Request.”
You’ll need to provide a title and description for the PR, and you can link it.
to an issue or assign it to a reviewer. You can also add labels, such as bug, feature, or enhancement
Name your PR in a way that reflects the branch name but without the issue number. For example:

For style/<issue-number>/improve_login_page_styling, the PR might be style/improve-login-page-styling.
For feature/<issue-number>/implement_dashboard, it might be feature/implement-dashboard.
The format for PR naming is:

/ (use kebab-case for the short description)

OR

//
NOTE
It’s perfectly fine to use the branch name as the PR title. No problem at all.

Code Review
Code review is a critical step before merging your code into the main branch. It ensures that the code is clean, follows best practices, and doesn’t introduce bugs or performance issues. After creating a PR, assign it to someone experienced in the codebase, ideally a senior developer.

Having two reviewers for each PR is recommended, as it helps catch more issues and promotes knowledge sharing among team members.

Merging
The final step in the GitHub workflow is merging the PR into the main branch. After the PR is approved and merged, the associated issue will be automatically closed. Don’t forget to delete the branch after merging to keep the repository clean.

Once the code is in the main branch, it’s ready for production, and the changes will be visible to users. The team can then celebrate another successful collaboration!

Recap
Let’s quickly recap the main points in the GitHub workflow:

Create an Issue
Name it like [<type>]: <short-description> ([FIX]: Fix auth flow).
Create a Branch
Name it like <type>/<issue-number>/<short-description> (fix/92/fix_auth_flow).
Commit Your Changes
Use concise, descriptive messages (feat: implement dashboard header).
Create a Pull Request
Use a clear title that reflects the branch name (feature/implement-dashboard).
Code Review
Assign one or two reviewers to check the code before merging.
Merge and Clean Up
Merge the PR, close the issue, and delete the branch.
Types
can include feat, style, fix, enhance, refactor, docs

Scopes
can be front, back, api, db, docs, test, chore

Tools
You can use a Git hook called pre-commit to enforce the commit message format.

This workflow might seem like a lot initially, but with practice, it will become second nature. I hope this article was helpful and that you learned something new today. Thank you for reading, and have a great day! :)

By the way, I’m considering writing an article about GitHub Actions next. What do you think?