Git is the most powerful version control system coded in the history of humankind. The super-rich feature set of Git makes the code management straightforward.
So today, let's discuss how we can follow a simple structure to manage our codebase.
When we kick-off a new project, we create a repository on Github. Followed by setting up or creating a
README.md file. Now, it can be a public or a private project.
Collaborators and accessibility -
After that, we invite our collaborators to collaborate. Always setup access rights to the collaborators. For example, not everyone can merge pull requests. Only the code maintainers or core team members can manage the merging part.
Every collaborator gets their own cloned repository so they can work independently. When you fork a repository, the primary repository becomes the
upstream, and the cloned repository becomes the
origin. We push our code to
origin/branch-name and then it's merged into the
upstream/develop. I like to keep my primary repository clean; therefore I suggest a fork based approach for development.
Most commonly, forks are used to either propose changes to the projects or to use someone else's plan as a starting point for your idea.
So, when a collaborator wants to work on something new, they create a new branch depending on the type of the work they will be doing. So that, they can work on their features or bugs independently without troubling the other collaborators.
When you create a new repository on Github, you get a
master branch, by default. Usually, all the developers or maintainers create a new branch from master, names
develop should be the primary branch for merging your features, bugs and enhancements.
master- is a branch for production deployments.
develop- is a branch where we merge the code from different collaborators.
staging- is a branch in which we merge and test our code before going to production-level. Once we test all the functionality and the deployment cycle, we push/merge the
- branch with unfinished work - When any collaborator leaves the organisation with incomplete code, or if he/she wants to transfer his/her ownership to someone else, it's a good thing to create a new branch on parent repository with his name. So the other collaborator can pull his/her code from there. Branch name can be something like this,
It's a good practice to have (only) these branches on the primary repository. So it stays clean.
On your fork, you can create a branch based on the type of work you are doing. We can follow a simple technique to identify branches in a better way,
- For a feature,
- For a bug,
- If you have an open issue for this then,
- Any enhancement,
Very simple, isn't it? These are the industry standards or common practice that developers around the globe follow.
Pull requests -
Once the work is done we create a pull request from our branch to the
upstream/develop. Now, it's a good thing to have different things set up on your pull request.
- Reviewers - Reviewers are those people who are going to review your pull request. You can request more than one review to the pull request.
- Assignee - Assignee is someone who is currently working on the pull request. There can be more than one assignee.
- Description - explain what is the pull request about. You can add issue reference number to the description.
- Labels - Labels are the best way to add identification to the pull request. Github has already given important labels. Such as - bug, enhancement, feature, wontfix, help wanted. So that other collaborators can identify the pull request without even opening.
Milestones - By adding
milestones, you can track and filter your pull requests. You can find a detailed description over here.
Before merging the pull request, at least have two code review rounds with your peers. Usually, I like to apply different labels such as
waiting for peer review,
waiting for merge review,
ready for deployment to track the status of the pull request.
Other than that, I like to add different labels to know the type of the pull request. Like,
You can create multiple labels to make your pull requests more identifiable according to your process.
The Github already predefines some of the labels.
This is a very good place to keep track of your bugs and enhancements. You can integrate bug trackers to auto-create issues. Issues are shared between the collaborators where they can have a discussion about the solution.
There’s an assignees option, where you can tag different collaborators.
Whenever you merge any pull request from
master, it's a release. Essentially it's a good thing if you can track your releases. Every time we merge code to the
master, we increment the counter by one. Now, it's easy to track your versions. You can read more about Semantic Versioning here.
The simple explanation for generating a version number is,
- MAJOR - significant releases and features.
- MINOR - When you improve existing functionality, improve code quality.
- PATCH - for minor changes, bug fixes.
This is how you can draft releases with Github. It's simple and useful!
Real world example is Bootstrap -
Before merging the pull request, you can have different tools to make your code robust. Like,
- Run test cases on a cloud.
- Run linter to fix code quality.
Well, that's it! I have documentation for all the stuff that I mentioned. If you want it, write your email in the comment section below. I would be happy to share it with you.