Git
Good organization in branches assure the version control to have stable release from the project. Besides, it helps minimize sources of conflict when merging workload together.
In this project, we base our workflow on the established model called Gitflow. The following section summarizes and adopt the model for the project’s needs.
The main branch captures the official versions of the project. Each release should be stable and be merged from develop and no other branches.
This branch is protected and no commit should be pushed directly from main (apart from automated tasks).
The develop branch serves as an integration branch for issue branches. It acts as the heart of development and is not expected to be stable. Most PRs in the project target the develop branch.
An issue branch follows the same principle of a feature branch established by the Gitlfow model. We call them issue branches here since all our feature management is made within GitHub's issue and project system.
Every issue should be supported by its own branch. Once an issue linked to a branch is ready to be closed, a PR must be created to merge its branch into develop.
This means that development should not be made on personal branches that merges with develop multiple times. An issue branch is terminated once its PR is approved and merged.
When writing an issue, for any kind of task (gameplay, asset, groceries, etc.), you can create the branch directly from its generated issue's page. Make sure to deploy the new branch from develop or any other valid context.
An issue branch's name must respect the following structure:
tag/#n_lorem-ipsum-nuage
^--^^-^^---------------^
| | |
| | +---> Lowercase summary of the issue.
| |
| +---> Issue's number.
|
+---> Issue's main tag.
When planning to produce a new version on main, a release branch is created from develop. The goal is to stabilize a state of the project from develop before sending it as a release towards main. That way, we secure a version while development can continue as usual on develop without interfering with a release preparation.
Once a release is ready, the branch is merged into main and gets terminated.
A release branch name must respect the following structure:
#r/#n_lorem-ipsum-nuage
^-^^-^^---------------^
| | |
| | +---> Lowercase name of release.
| |
| +---> Issue number.
|
+---> Release number.
Sometimes, shit goes down on main. No time to panic, a hotfix branch is deployed to save the day. This type of branch is created directly from main's most recent version with the unique goal to make a new stable version ASAP.
Once a hotfix is ready, it merges on main like a release branch. Also, develop is expected to receive the hotfix in order to update the development files. We don't want to duplicate a hotfix when new releases are deployed on main.
A hotfix branch name must respect the following structure:
hotfix/#n_lorem-ipsum-nuage
^-----^^-^^---------------^
| | |
| | +---> Lowercase summary of hotfix.
| |
| +---> Issue Number.
|
+---> Hotfix tag.
There are two main types of commits available in this project:
- Commits that are linked to an issue within a branch
- Commits when merging into a branch after a pull request
While the first type is more or less important to keep consistent, it's still good practice (and friendly peer behavior) to follow certain rules while naming a commit and selecting the files targeted by it.
The second type in the other must be compliant to name convention in order to keep a clear version history.
While working on an issue, the effort must be done on an issue branch to isolate your unstable mess from the develop branch. However, it’s recommended to push commits to your dedicated branch, keeping history of the work progress. Besides, it’s very useful to revert to a previous state when iterating on new features or experimenting with code.
While every commits in an issue branch doesn’t matter in terms of naming (since they’ll be squashed during PR process), it’s still crucial to be consistent. Reasons are, if you need help on a certain topic, it’s easier for peers to understand an issue’s history.
Finally, it’s important to only include files that are linked to a commit’s doing. For instance, if I’m working on a controller and commit some progress, I should only involve the same controller and its dependencies. Additional files, like a material for another object, shouldn’t be pushed on the same commit.
A commit destined for an issue branch must respect the following structure:
scope: lorem-ipsum-nuage
^---^ ^---------------^
| |
| +---> Lowercase summary of the commit.
|
+---> Commit's scope.
When an issue is ready to be closed, and its content, ready to get on develop, a pull request needs to be created. That's right, it's time to take your elegant garbage on the main train.
Once you’re satisfied with your latest commit from your working branch, it's best to head to GitHub in order to create your pull request. Indeed, you'll then be able to name your pull request, describe your achievements, add reviewers, etc.
It's crucial to pick in which branch you want to merge your new content. Hint, most of the time, develop is the unlucky winner.
Once a pull request read approved by reviewers, it's now ready for the merge. It's very important at this step to select the option Squash and Merge. This will compile all existing commits in the merging branch into only one entry. Note that the merge commit will share the same name as its pull request.
Once a merge is completed, the working branch that got merged can be safely deleted. At this point, if a conflict happens, please refer to Merging Conflicts.
A pull request (and its commit) must respect the following structure:
scope: [#n] lorem ipsum nuage
^---^ ^--^ ^---------------^
| | |
| | +---> Lowercase summary in present tense.
| |
| +---> Issue number.
|
+---> Appropriate scope.
Just like you, every commit has a type. For strong readability, it’s important to identify your commit’s correct scope. Scrolling into your issue branch will then feel like a fresh nostalgic breeze. Otherwise, you might suffer from early undiagnosed Alzheimer looking at all your previous entries.
If a commit feels like it can hold more than one scope, it’s better to split it in two. No shame in having committed lonely files only to support a scope title. Versions history of the branch might have more commits, but every entry should be clear and exempt of noises.
| scope | description |
|---|---|
| feat | Files represent a new workable feature. |
| art | Files contain new assets to be used for upcoming features. |
| wip | Work in progress. Files aren’t ready to be published. |
| fix | It’s Tide to go. Bugs fixing. |
| refactor | When you feel smarter than your peers. |
| chore | Files are directed for system improvements, plugins, dishes, etc. |
| docs | Concerned files are for documentation purposes. |
| lab | When you go crazy on your branches. |
Commits are often a subject of debate. The above model should help make clear entries without having sophisticated syntax. Here are a list of different tips and tricks on how to handle commits and pull requests:
- Separate a complex commit into several smaller commits to satisfy scoping and improve lucidity over the branch's history.
- Always expect at least one reviewer to approve a pull request before proceeding a merge (unless it's Force Push Friday)
- When merging, always select Squash and Merge
- When naming a commit, try to summarize the commit with few words. If you feel like it requires more than one sentence, split the commit in two or more.
This repository has some rules for protecting the main and develop branches. Most of the time, your pull requests will target the develop. Now, it's not a trust issue situation. It's not you, it's your code. To make sure we understand what goes into the program and limits the number of all nighters, the ruleset on both main and develop requires at least one reviewer.
This is common practice and acts as a great sharing knowledge tool as well. Peer reviews is a powerful resource that protects the project's integrity as well as making your code smarter. What a deal.
Welcome to rebase hell.
You're on your own.