Table of Contents
...
The types and scope will vary per repository. The tables below provide the types and scopes for edgex-go as an example.
...
following is the current standard as of 2020-09-24
From: EdgeX-TSC-Core@lists.edgexfoundry.org <EdgeX-TSC-Core@lists.edgexfoundry.org> On Behalf Of Jim White
Sent: Thursday, September 24, 2020 12:12 PM
To: Core WG <edgex-tsc-core@lists.edgexfoundry.org>
Subject: [Edgex-tsc-core] Conventional Commits
Hello core working group members. Per the Core WG meeting today, I am looking for feedback on our upcoming adoption of conventional commits specification across repositories under Core WG purview. Thanks to Mike Johanson, the types and scopes for edgex-go are to be set at these:
edgex-go
types: feat (for feature), fix, docs, style, refactor, perf (for performance), test, build, ci, revert
scopes: core-data (or data), core-metadata (or metadata or meta), core-command (or command or cmd), snap, docker, security, scheduler, notifications, sma, deps (for dependencies), all
For the other repositories, I propose the following.
all mods (bootstrap, core-contracts, messaging, registry, configuration)
types: feat (for feature), fix, docs, style, refactor, perf (for performance), test, build, ci, revert
scopes: [no scope for general code or scope does not apply], models, errors, clients, config, docker
edgex-docs
types: feat (for feature), fix, style, build, ci, revert
scopes: [no scope for general docs or scope does not apply], intro (and getting started), api, adr, design, examples, microservices, ref (for reference)
edgex-cli
types: feat (for feature), fix, docs, style, refactor, perf (for performance), test, build, ci, revert
scopes: [no scope for general code or scope does not apply], res, samples, config
edgex-ui-go
types: feat (for feature), fix, docs, style, refactor, perf (for performance), test, build, ci, revert
scopes: [no scope for general code or scope does not apply], image
docker-edgex-consul
types: feat (for feature), fix, docs, refactor, perf (for performance), ci, revert
scopes: [no scope for general code or scope does not apply], config, scripts (or bin)
docker-edgex-mongo
types: feat (for feature), fix, docs, refactor, perf (for performance), ci, revert
scopes: [no scope for general code or scope does not apply], config, scripts (or bin)
developer-scripts
types: feat (for feature), fix, docs, style, refactor, perf (for performance), test, build, ci, revert
scopes: no scope or compose or source (for compose source)
edgex-examples
types: feat (for feature), fix, docs, style, refactor, perf (for performance), test, build, ci, revert
scopes: app (for app services), device (for device services), temp (for templates), security, all, or no scope if it does not apply to these
Please weigh in with any other changes or additions. We'll resolve and adopt with next week's meeting.
Jim White
Examples of proper messages (in the context of sample Git CLI commands) are:
...
The body of the commit should contain a reference to issue that is addressed (closes and/or fixes). Example:
- git commit -s -m "fix(core-data): fixed some big error description" -m "fixes: #123"
- git commit -s -m "fix(core-data): fixed some big error description" -m "closes: #123"
EdgeX GitHub Getting Started
...
2. Create a local clone of your fork.
$ git clone git@github.com:$MYACCOUNT/$REPO |
|---|
3. Configure Git to sync your fork with the original repository.
4. Add a remote reference so that Git can sync your fork with the master project repository.
$ cd $REPO $ git remote add upstream git@github.com:$UPSTREAM/$REPO |
|---|
A detailed example illustrating these steps is provided here.
...
1. Start new work on a new feature branch.
$ git checkout -b new-feature |
|---|
2. Update your code and commit. You can either:
a. explicitly add individual file changes in your working directory to you index.
$ git add file1.txt # or to add all files $ git add . # review changes $ git diff –cached $ git commit -s |
|---|
b. use the git commit -a to automatically stage all tracked, modified files before the commit If you think the git add stage of the workflow is too cumbersome. This basically tells Git to run git add on any file that is "tracked" - that is, any file that was in your last commit and has been modified. Please use caution when using this approach as it's easy to accidently commit files unintentionally (eg. build artifacts, temp files from editors, ...).
| git commit -as |
|---|
The -s option used for both alternatives causes a committer signed-off-by line to be appended to the end of the commit message body. It certifies that committer has the rights to submit this work under the same license and agrees to our Developer Certificate of Origin (see Contributor's Guide for more details about our DCO). E.g.
signed-off by: John Doe johndoe@example.com |
|---|
In order to use the -s option, you need to make sure you configure your git name (user.name) and email address (user.email):
$ git config --global user.name “John Doe” $ git config --global user.email johndoe@example.com
# To check $ git config --list |
|---|
3. Add a commit message: See Commit Messages section below.
4. Push work to your repository as a new branch.
$ git push origin new-feature |
|---|
5. Create a Pull Request. This is a formal request for the project's maintainers to review the diff and approve/merge, or possibly request that changes be made.
6. While that is happening you can work on something else! Sync your fork of the repository to keep it up-to-date with the upstream repository. Fetch the branches and their respective commits from the upstream repository.
$ git fetch upstream |
|---|
7. Check out your fork's local master branch.
$ git checkout master |
|---|
8. Rebase the changes from upstream/master into your local master branch. This brings your fork's master branch into sync with the upstream repository, without losing your local changes.
| $ git pull --rebase upstream master |
|---|
9. Push the updated master back to your fork.
$ git push origin master |
|---|
Note: it was suggested to use git checkout master, then git pull origin master in preference to above (to be discussed).
10. Start new feature.
$ git checkout -b new-feature2 |
|---|
11. Repeat the steps above as appropriate
12. If a change was requested on the new-feature PR then simply rebase your working branch from upstream:
$ git pull --rebase upstream master |
|---|
13. Make changes.
14. Update the PR killing off the older changes.
| $ git commit -as --amend |
|---|
15. Force push the updated PR back up.
$ git push origin new-feature2 –-force |
|---|
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.
...
- Choose short and descriptive names
# good $ git checkout -b oauth-migration # bad - too vague $ git checkout -b login-fix |
|---|
Identifiers from corresponding tickets in an external service (e.g. a GitHub issue) are also good candidates for use in branch names. For example:
# GitHub issue #15 $ git checkout -b issue-15 |
|---|
Use hyphens to separate words.
- When naming Feature branches common practice is to use the naming convention feature/my-feature. This allows feature specific branches to be easily identified in the repository.
- When several people are working on the same feature, it might be convenient to have personal feature branches and a team-wide feature branch. Use of a team-wide branch will require the co-operation of the project’s Maintainers/Committers to setup the branch in the main repository. Use the following naming convention:
$ git checkout -b feature/master # team-wide branch $ git checkout -b feature/maria # Maria's personal branch $ git checkout -b feature/nick # Nick's personal branch |
|---|
Merge at will the personal branches to the team-wide branch. Eventually, the team-wide branch will be merged to master.
...
- 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.
...
- 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 |
|---|
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:
...