The workflow outlined below is a basic one that would be used when we want to do product development without maintaining older versions.
For example, there may be projects where a version 1.0.0 of the product is generated, and then a version 2.0.0 of the product is developed. In such cases, you may want to support version 1.0.0 while continuing to develop version 2.0.0 by adding commits for fixes to both versions but only new features to the latest version.
This workflow is primarily not intended for such cases but rather for situations where the latest published version is the only one maintained, as in the case of a service or a library.
For more information, you can refer to GitHub Flow.
Below, we will outline the Git workflow. First, we need to create our branch, implement the necessary code to finish the task, and then perform an integration into the master branch using a rebase.
This process can be visualized as shown in the following diagram while we are working on our features:
%%{init: {'gitGraph': { 'mainBranchName': 'master'}} }%%
gitGraph
commit id: "feat(project) set up"
branch feat/user-login
commit id: "feat(front): add login template"
commit id: "feat(backend): add login processer"
checkout master
branch feat/user-signin
commit id: "feat(front): add sigin template"
commit id: "feat(backend): add loginsigin processer"
checkout master
merge feat/user-login
merge feat/user-signin tag: "v0.0.1"
However, once the task is completed, the history will become linear, as depicted in the following diagram:
%%{init: {'gitGraph': { 'mainBranchName': 'master'}} }%%
gitGraph
commit id: "feat(project) set up"
commit id: "feat(front): add login template"
commit id: "feat(backend): add login processer"
commit id: "feat(front): add sigin template"
commit id: "feat(backend): add loginsigin processer" tag: "v0.0.1"
To indicate the release of a version or a deployment, we will use tags in Git.
Before merging into the master branch, we need to bring all changes and rebase master using the following commands:
# Update the local repository with changes from the remote repository (master branch)
git fetch origin master
# Switch to the master branch
git checkout feat/user-signin
# Rebase the master branch with the latest changes from origin/master
git rebase origin/masterIn this section, we will discuss the branch structure of the repository.
- The master branch is the main and default branch in Git.
- It serves as the foundation for all other branches.
- It should be protected to prevent direct writing except through pull requests (PRs).
- It represents the main development line of your project.
- Everything found here is expected to be a stable and functional version of the code.
There are three types of branches:
- feat: Used to develop new features, perform refactoring, add CI/CD tests, etc.
- fix: Used to fix errors.
- poc: Used for proof of concepts, testing redesigns, etc.
Regarding these branches:
- It is recommended to create specific branches that branch off from the master branch.
- Each feature branch should have a descriptive name indicating its purpose, without the need to include the author's name or assigned task, unless it's necessary for a specific CI/CD setup.
Guidelines for naming your branches:
- Prefix: Use a prefix indicating the branch type, for example, "feat/" for new features, "poc/" for proof of concept, and "fix/" for fixes.
- Descriptive Name: The branch name should be descriptive yet concise, reflecting the task or feature you are developing.
- Lowercase and Hyphens (-): It's a good practice to use lowercase letters and hyphens to separate words in the branch name.
Examples of feature branch names:
feat/user-authentication
poc/data-analytics
fix/bug-in-validation
Using conventional commits is an approach to writing commit messages following a specific format or convention. The conventional commit format helps standardize commit messages, making it easier to automate tasks like generating changelogs or tracking issues. This format typically includes three parts: a type, an optional scope, and a message.
Here's how a conventional commit message is structured:
<type>(<scope>): <message>. <backend>
- <type>: Describes the purpose of the commit, such as feat for new features, fix for bug fixes, chore for routine tasks, and more.
- <scope> (optional): Indicates the module, component, or section of the project affected by the commit.
- <message>: Provides a concise and descriptive summary of the change.
- <backend> (optional): When the git backend is linked to issue platform like jira you can use this to close a issue among other
By adopting the conventional commit format, your commit history becomes more organized and easier to parse. Additionally, various tools and workflows can be integrated with conventional commits to automate release notes generation and issue tracking, enhancing your development process.
To get started with conventional commits, consider using tools like "commitlint" and "commitizen" in your Git workflow. These tools help enforce the commit message format and guide you through creating conventional commit messages.
You can gather more information about the structure of conventional commits at https://www.conventionalcommits.org/en/v1.0.0/.
To automate and streamline the use of conventional commits, you can use the Commitizen tool https://pypi.org/project/commitizen/ or the following website: https://commitlint.io/.
| Commit Type | Title | Description |
|---|---|---|
feat |
Features | A new feature. Correlates with MINOR in SemVer |
fix |
Bug Fixes | A bug fix. Correlates with PATCH in SemVer |
docs |
Documentation | Documentation only changes |
style |
Styles | Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc) |
refactor |
Code Refactoring | A code change that neither fixes a bug nor adds a feature |
perf |
Performance Improvements | A code change that improves performance |
test |
Tests | Adding missing tests or correcting existing tests |
build |
Builds | Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm) |
ci |
Continuous Integrations | Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs) |
feat(component): add a new feature. closes: #
^--^ ^-------^ ^---------------^ ^------^
| | | |
| | | +--> (Optional) Issue reference: if the commit closes or fixes an issue
| | |
| | +---------------------> Commit summary
| |
| +---------------------------------> (Optional) Commit scope in the project
|
+--------------------------------------> Commit type: feat, fix, build, ci, docs, style, refactor, perf, test
Here are some examples of conventional commit messages:
feat(user-auth): add login functionality.
fix(validation): resolve input error handling. Closes: #100
chore(docs): update project documentation.
Tags will serve as a way to indicate which commit in the master branch has been deployed or released. They will be generated manually using the Commitizen tool, which will generate the corresponding version based on the commit messages.
Before starting to make any commits, you'll need to install and enable the necessary Git hooks. For Python repositories, you can use "pre-commit" for this purpose. To initialize them, you can execute the following command:
pre-commit install
This command sets up and activates the pre-commit hooks in your repository, ensuring that code quality checks or other tasks are performed automatically before each commit.
- https://gist.github.com/alpteo/e93d754e5e09907c6362c4230fb66f87
- https://gitmoji.dev/
- http://karma-runner.github.io/1.0/dev/git-commit-msg.html
- https://nitayneeman.com/posts/understanding-semantic-commit-messages-using-git-and-angular/
- https://www.conventionalcommits.org/en/v1.0.0/
- https://commitizen-tools.github.io/commitizen/
- https://docs.github.com/en/get-started/quickstart/github-flow