Table of Contents
Introducing GitHub
The EdgeX has selected GitHub as the code management repository for the project. GitHub is a web-based Git or version control repository and Internet hosting service. It offers all of the distributed version control and source code management (SCM) functionality of Git as well as adding its own features. It provides access control and several collaboration features such as bug tracking, feature requests, task management, and wikis for every project.
...
- Create or clone a repository
- Start and manage a new branch
- Make changes to a file and push them to GitHub as commits
- Open and merge a pull request
EdgeX GitHub Getting Started
The EdgeX GitHub organization has been configured such that all repositories it hosts have been setup with branch protection in place. This requires new contributors to fork a project repository and work on a local copy before submitting a Pull Request so that any new changes get merged back into the master project repository on GitHub. It is not an option for a committer to just clone the repository and push changes directly back to it.
...
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 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.
...
- 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.
- 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).
...
Branching Conventions
- Choose short and descriptive names
...
Merge at will the personal branches to the team-wide branch. Eventually, the team-wide branch will be merged to master.
Commits
- Each commit should be a single logical change. Don't make several logical changes in one commit. For example, if a patch fixes a bug and optimizes the performance of a feature, split it into two separate commits.
...
Note: While working alone on a local branch that has not yet been pushed, it's fine to use commits as temporary snapshots of your work. However, it still holds true that you should apply all of the above before pushing it.
Commit Messages
EdgeX will follow will well-established conventions for creating consistent, well written Git commit messages. Just follow the seven rules below and you shouldn’t run into any problems.
...
$ git commit --squash f387cab2 |
|---|
...
Merging
- 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.
...
# 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:
...