If you think you have found a bug, search first for it in the
issues; it can be that the bug is already tracked an someone else is working on it.
issue for the feature or bug you have to work on20-fantastic-featuremain branch (this will assure a clean history and will avoid merge conflicts to the reviewers); if your branch is behind main, then rebase it on mainclosing keywords to refer issues you are working on (see Linking and closing issues from pull requests)“This flow starts with
issuesand is a way to make the relation between the code and the issue tracker more transparent.”
Any significant change to the code should start with an issue that describes the goal. Having a reason for every code change, helps to inform the rest of the team and to keep the scope of a feature branch small.
Each change to the codebase starts with an issue in the issue tracking system.
If you are faced with a bug, a regression, ecc, search for a related issue first; then, if not present, open one.
Raising an issue is part of the development process because they can be used in sprint planning. The issue title should describe the desired state of the system.
For example, the issue title “As an administrator, users can be removed without receiving an error” is better than “Administrators can’t remove users.”
Issues can be documented with “steps to reproduce” and media files like screenshots or gifs.
When you are ready to code, create a branch for the issue from the main branch. This branch is the place for any work related to this change.
Naming the branch with a reference to the related issue can be a good practice
(ex.: 20-this-is-a new-feature , where “20” is the issue reference number).
“N.B. : the
defaultbranch in a repository is the base branch for new pull requests and code commits.”
When you are done or want to discuss the code, open a pull request (see Pull request flow).
A pull request is an online place to discuss the change and review the code.
If you open the pull request but do not assign it to anyone, it is a draft pull request. These are used to discuss the proposed implementation but are not ready for inclusion in the main branch yet. Start the title of the pull request with [Draft], Draft: or (Draft) can help to prevent it from being merged before it’s ready.
When you think the code is ready, assign the pull request to a reviewer. The reviewers can merge the changes when they think the code is ready for inclusion in the main branch. Pull requests always create a merge commit, even when the branch could be merged without one. This merge strategy is called no fast-forward in Git. After the merge, delete the feature branch, because it is no longer needed.
Suppose that a branch is merged but a problem occurs and the issue is reopened. In this case, it is no problem to reuse the same branch name, because the first branch was deleted when it was merged. At any time, there is at most one branch for every issue. It is possible that one feature branch solves more than one issue.
You can link an issue to a pull request manually or using a supported keyword in the pull request description.
When you merge a linked pull request into the default branch of a repository, its linked issue is automatically closed.
You can link a pull request to an issue by using a supported keywords in the pull request’s description or in a commit message (please note that the pull request must be on the default branch).
If you use a keyword to reference a pull request comment in another pull request, the pull requests will be linked. Merging the referencing pull request will also close the referenced pull request.
The syntax for closing keywords depends on whether the issue is in the same repository as the pull request.
| Issue in the same repository | KEYWORD #ISSUE-NUMBER | Closes #10 |
|---|---|---|
| Issue in a different repository | KEYWORD OWNER/REPOSITORY#ISSUE-NUMBER | Fixes octo-org/octo-repo#100 |
| Multiple issues | Use full syntax for each issue | Resolves #10, resolves #123, resolves octo-org/octo-repo#100 |
Only manually linked pull requests can be manually unlinked. To unlink an issue that you linked using a keyword, you must edit the pull request description to remove the keyword.
You can also use closing keywords in a commit message. The issue will be closed when you merge this commit into the default branch, but the pull request that contains the commit will not be listed as a linked pull request.
With Git, you can use an interactive rebase (rebase -i) to squash multiple commits into one or reorder them. This feature helps you replace a couple of small commits (like fix typos, ecc. ) with a single commit, or if you want to make the order more logical.
However, you should avoid rebasing commits you have pushed to a remote server if you have other active contributors in the same branch. Because rebasing creates new commits for all your changes, it can cause confusion because the same change would have multiple identifiers. It would cause merge errors for anyone working on the same branch because their history would not match with yours. It can be really troublesome for the author or other contributors. Also, if someone has already reviewed your code, rebasing makes it hard to tell what changed after the last review.
You should never rebase commits authored by other people unless you’ve agreed otherwise. Not only does this rewrite history, but it also loses authorship information. Rebasing prevents the other authors from being attributed and sharing part of the git blame.
When creating a feature branch, always branch from an up-to-date main. If you know before you start that your work depends on another branch, you can also branch from there. If you need to merge in another branch after starting, explain the reason in the merge commit. If you have not pushed your commits to a shared location yet, you can also incorporate changes by rebasing on main or another feature branch.
Both GitHub and GitLab offer the possibility to open a branch directly from the issue page: this can be a time saver since the branch will be based on main branch and it will have the issue number at the beginning of the name; the only precaution is to arrange the name so that it is declarative but not too long.
Do not merge from upstream again if your code can work and merge cleanly without doing so. Merging only when needed prevents creating merge commits in your feature branch that later end up littering the main history.
Another way to make your development work easier is to commit often. Every time you have a working set of tests and code, you should make a commit. Splitting up work into individual commits provides context for developers looking at your code later. Smaller commits make it clear how a feature was developed. They help you roll back to a specific good point in time, or to revert one code change without reverting several unrelated changes.
Committing often also helps you share your work, which is important so that everyone is aware of what you are working on. You should push your feature branch frequently, even when it is not yet ready for review.
By sharing your work in a feature branch or a pull request, you prevent your team members from duplicating work. Sharing your work before it’s complete also allows for discussion and feedback about the changes. This feedback can help improve the code before it gets to review.
Pull requests are created in a Git management application. They ask an assigned person to merge two branches.
If you work on a feature branch for more than a few hours, share the intermediate result with the rest of your team. To do this, create a pull request without assigning it to anyone. Instead, mention people in the description or a comment, for example, /cc @guizzo @devnuli. This indicates that the pull request is not ready to be merged yet, but feedback is welcome. Your team members can comment on the pull request in general or on specific lines with line comments. The pull request serves as a code review tool, and no separate code review tools should be needed. If the review reveals shortcomings, anyone can commit and push a fix. Usually, the person to do this is the creator of the pull request. The diff in the pull request automatically updates when new commits are pushed to the branch.
When you are ready for your feature branch to be merged, assign the pull request to the person who knows most about the codebase you are changing. Also, mention any other people from whom you would like feedback.
After the assigned person feels comfortable with the result, they can merge the branch. If the assigned person does not feel comfortable, they can request more changes (or close the pull request without merging).
For naming conventions on pull requests see conventional commit
Is common to protect the long-lived branches, such as the main branch, so most developers can’t modify them. So, if you want to merge into a protected branch, assign your pull request to someone with the Maintainer role.
After you merge a feature branch, you should remove it from the source control software. In GitHub, you can do this manually when merging or automatically (see settings). Removing finished branches ensures that the list of branches shows only work in progress. It also ensures that if someone reopens the issue, they can use the same branch name without causing problems.