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.

If you are completely new to GitHub then the Hello World project is a time-honored tradition in computer programming. It is a simple exercise that gets you started when learning something new.  By following the GitHub hello world example you will learn how to:

Contribution Guidance - Top 4 things to do (or not do)

While this document and the others on our Wiki site provide a lot of great guidance to developers planning to make contributions to the project, we would ask that developers (and the maintainers/committers) of the project pay particular attention to the following "top 4" practices and adhere to them closely when working on project repositories.


1.    Commit subject line messages should explain the problem that the commit is solving in  50 characters or less.  “Fixing bug” or “adding comments” doesn’t explain the problem the commit is solving!.

2.    Provide a message body to the commit to provide more detail explanation.  When you do, keep lines in the body to 72 characters or less.

You can add a commit subject line and multiple message bodies like this:

git commit –s –m “This is the subject; keep to 50 char” –m “This is the first line of the message body"$'\n'"This is the second line of the message body."$'\n'"Keep all message lines to 72 char.”

3.    Commit your changes in logical chunks.  Make it easier for the community to review, comment on, and accept your contribution.  For example, create a separate commit for a big fix and an enhancement.

4.    Rebase the upstream development branch into your topic branch.  Do not merge master into your local PR branch (this is the lazy approach to dealing with committed code locally in a branch, and then realizing that your PR isn’t merge-able because HEAD has changed).  See https://git-scm.com/book/en/v2/Git-Branching-Rebasing if you need more help.

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.

1.      Create a Fork on GitHub (see fork example).

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.

From this point the basic workflow is as follows:

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.

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:

Branching Conventions

# 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.

$ 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.

Commits

       Tip: Use git add -p to interactively stage specific portions of the modified files.

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.

The seven rules of a good Git commit message are:

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why vs. how

For example:

Summarize changes in around 50 characters or less 

More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of the commit and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); various tools like `log`, `shortlog` and `rebase` can get confused if you run the two together.

Explain the problem that this commit is solving. Focus on why you are making this change as opposed to how (the code explains that).

Are there side effects or other unintuitive consequences of this change? Here's the place to explain them.

Further paragraphs come after blank lines.

  • Bullet points are okay, too
  • Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank lines in between, but conventions vary

If you use an issue tracker, put references to them at the bottom, like this:

Resolves: #123

See also: #456, #789

Ultimately, when writing a commit message, think about what you would need to know if you run across the commit in a year from now.

$ git commit --squash f387cab2

Merging

         That said never rewrite the history of the "master" branch or any other special branches (i.e. used by production or CI servers).

# good - ensures that a merge commit is created

$ git merge --no-ff my-branch

# bad

$ git merge my-branch

Miscellaneous











1.    Commit subject line messages should explain the problem that the commit is solving in  50 characters or less.  “Fixing bug” or “adding comments” doesn’t explain the problem the commit is solving!.

2.    Provide a message body to the commit to provide more detail explanation.  When you do, keep lines in the body to 72 characters or less.

You can add a commit subject line and multiple message bodies like this:

git commit –s –m “This is the subject; keep to 50 char” –m “This is the first line of the message body"$'\n'"This is the second line of the message body."$'\n'"Keep all message lines to 72 char.”

3.    Commit your changes in logical chunks.  Make it easier for the community to review, comment on, and accept your contribution.  For example, create a separate commit for a big fix and an enhancement.

4.    Rebase the upstream development branch into your topic branch.  Do not merge master into your local PR branch (this is the lazy approach to dealing with committed code locally in a branch, and then realizing that your PR isn’t merge-able because HEAD has changed).  See https://git-scm.com/book/en/v2/Git-Branching-Rebasing if you need more help.