...
By using the --amend and --force options means that any of the commits that you produce should be clean, non-breaking changes at all times that get merged in, instead of having a set of patches in a PR that may have one or two 'fixup' changes.
GitHub
...
Issue and Pull Requests
(added with approval of the TSC 9/21/21)
A GitHub issue should normally be filed for any bug discovered in EdgeX services, code or documentation flaw (with the exception of those situations noted below) and prior to any PR to fix the bug is submitted. When submitting a PR to fix the bug, the issue should be referenced as a "fix:" (the Conventional Commit fix type) for the bug in the commit comments (see Commit Message guidelines).
When submitting a GitHub issue for a bug, the submitter is requested to provide the "steps to reproduce or see" the bug. When the steps are not provided, the issue should provide some explanation as to why steps to reproduce or how to see the bug are not provided.
No bug issue is required for:
- CI/CD (or other DevOp) needs that typically must be accomplished quickly and across many repositories and are not germane to the EdgeX application/service development
- Immediate / emergency bug fix PRs. In this case, the PR must document both the bug and the fix.
Issue creation for new features is suggested, but not required. Issue creation for features or enhancements is at the discretion of the contributor and typically done in consultation with the affected work group chairperson(s). Issues can be a good way to
- track progress, reference associated features, and seek comments and agreement on scope of work for a feature
- discuss potential features or improvements that have not yet been approved by the community for implementation
- document needs (features or enhancements) that will not be implemented in the near term but are desired in the distant future (providing a record of the need for longer term preservation)
GitHub Flow
The EdgeX project has adopted the GitHub Flow workflow, a lightweight, branch-based workflow that supports teams and projects where deployments are made regularly.
GitHub Flow is in a nutshell:
- Anything in the master branch is tested, functioning code that is usable.
- To work on something new, create a descriptively named branch off master (i.e. new-oauth2-scopes).
- Commit to that branch locally and regularly push your work to the same named branch on the server. Rebase regularly from upstream or face the pain of merge conflicts.
- When you need feedback or help, or you think the branch is ready for merging, open a Pull Request.
- A Pull Request is a request that someone else (e.g. an appropriate reviewer such as a project Maintainer or Committer) review the work that you’ve done and merge your changes in. When you create a pull request, you need to select 2 branches on GitHub,
...
The EdgeX project has adopted the GitHub Flow workflow, a lightweight, branch-based workflow that supports teams and projects where deployments are made regularly.
GitHub Flow is in a nutshell:
- Anything in the master branch is tested, functioning code that is usable.
- To work on something new, create a descriptively named branch off master (i.e. new-oauth2-scopes).
- Commit to that branch locally and regularly push your work to the same named branch on the server. Rebase regularly from upstream or face the pain of merge conflicts.
- When you need feedback or help, or you think the branch is ready for merging, open a Pull Request.
- A Pull Request is a request that someone else (e.g. an appropriate reviewer such as a project Maintainer or Committer) review the work that you’ve done and merge your changes in. When you create a pull request, you need to select 2 branches on GitHub, the branch that you’ve made your changes on, and the branch where you would want to merge your changes into. Because Pull Requests occur in GitHub, you would need to push your branch to GitHub before you create the request. If they review the changes on your branch and everything looks good, they can just merge the branch (and often delete the branch to clean up). However, if they have questions or comments, they can leave a comment on the pull request, i.e. with changes that you might need to make before they merge in. Then if they needed you to make another change, you can make the change to your code, then commit and push to your existing branch. Because a Pull Request is just a request to merge to branches in GitHub, since you’ve updated your branch, you’ve updated the Pull Request as well. They can then review your latest update and merge in.
- The main rule of GitHub Flow is that master should always be in deployable (usable operational state). GitHub Flow allows and encourages continuous delivery.
- Changes are submitted from developer feature branches as pull-requests against master, then merged using merge commits (which is the default for GitHub merges via their UI).
- When a new version is released, a tag is created, and development continues as before, via pull-requests submitted against master.
- If/when the need for supporting a maintenance release of a specific microservice arises, a branch is created from the required release tag, which is then used for release-specific bug fixes, potentially cherry-picked from master and/or other release branches (if they exist).
...
- If a commit A depends on commit B, the dependency should be stated in the message of commit A.
- Similarly, if commit A solves a bug introduced by commit B, it should also be stated in the message of commit A.
- If a commit is going to be squashed to another commit use the --squash and --fixup flags respectively, in order to make the intention clear.
...
$ git commit --squash f387cab2
Merging
- Always prefer a rebase to a merge (see above)
- Do not rewrite published history. The repository's history is valuable in its own right and it is very important to be able to tell what actually happened. Altering published history is a common source of problems for anyone working on the project.
- However, there are cases where rewriting history is legitimate. These are when:
- You are the only one working on the branch and it is not being reviewed.
That said never rewrite the history of the "master" branch or any other special branches (i.e. used by production or CI servers).
- Keep the history clean and simple. Just before you merge your branch:
- Make sure it conforms to the style guide and perform any needed actions if it doesn't (squash/reorder commits, reword messages etc.)
- If your branch includes more than one commit, do not merge with a fast-forward
# good - ensures that a merge commit is created
$ git merge --no-ff my-branch
# bad
- commit A.
- If a commit is going to be squashed to another commit use the --squash and --fixup flags respectively, in order to make the intention clear.
$ git commit --squash f387cab2 |
|---|
Merging
- Always prefer a rebase to a merge (see above)
- Do not rewrite published history. The repository's history is valuable in its own right and it is very important to be able to tell what actually happened. Altering published history is a common source of problems for anyone working on the project.
- However, there are cases where rewriting history is legitimate. These are when:
- You are the only one working on the branch and it is not being reviewed.
That said never rewrite the history of the "master" branch or any other special branches (i.e. used by production or CI servers).
- Keep the history clean and simple. Just before you merge your branch:
- Make sure it conforms to the style guide and perform any needed actions if it doesn't (squash/reorder commits, reword messages etc.)
- If your branch includes more than one commit, do not merge with a fast-forward
# good - ensures that a merge commit is created $ git merge --no-ff my-branch # bad $ git merge my-branch |
|---|
Keep Commit History during the PR Review
(per Monthly Architect's Meeting of 3/15/21)
When committing during the process of PR reviews, try to keep the commit history to make it easier for reviewers to see and follow the prior feedback conversations. This means that, in general (subject to discusssions between committers and reviewers), don't squash the commit history until the PR is approved. Also, don't force push the updates during the review/feedback process. Instead, when making commits during the review process, follow the following commit process:
- Make commits with your new commit comments: git commit -s -m "your review comment with appropriate semantic version type/scope tags"
- Commit without a force: git push origin yourbranch (vs git push -f origin yourbranch)
- On the last commit when the review has been completed (or whenever the PR needs to be rebased during the review cycle), a force push is ok if the PR is only being rebased: git push -f origin yourbranch
At the end of the review process, use the GitHub Merge button's options to squash the commit history (see below).
...
Miscellaneous
- Be consistent. This is related to the workflow but also expands to things like commit messages, branch names and tags. Having a consistent style throughout the repository makes it easy to understand what is going on by looking at the log, a commit message etc.
- Test before you push. Do not push half-done work.
- Use annotated tags for marking releases or other important points in the history. Prefer lightweight tags for personal use, such as to bookmark commits for future reference.
- Keep your repositories at a good shape by performing maintenance tasks occasionally:
...