DCO Check - Signing Off (With GitHub Web Editor Explanation)

I still see many pull requests with a failing DCO Check and sometimes questions why this check fails or if its even necessary for the small change.

Instead of repeating my answers on github again and again i would like to write a short FAQ on dco check and the usage in the openhab-docs repository.

What is a sign-off-statement

Basically that is just a “comment” you make for every commit you are trying to contribute,
which has to be in a specified format with specified contents and it should be the last line of each commit you want to contribute.

Important: A sign-of-statement is not related to securely signed or verified commits. No need to dig into signatures and keys. We just need the comment with your name and email!

You can find additional information about the sign-off in our contribution docs.
Especially why we need to have this statement from your side.

Two thing in advance

  1. The check is automated and runs for every pull request.
  2. It doesn’t know or look on the contents you are trying to contribute.
    It just looks for your sign-off paragraph.

So what can i do to handle DCO check better.

There are two options:

  1. If you know you have a small changed introduced which doesn’t need a sign-off statement,
    the reviewer (this is mostly myself at the time of writing this Post) will take care of it and override it if its reasonable.
  2. You can always do a correct sign-off and the problem is solved immediately

I have chosen the second option some time ago.
For me it is the easiest way of dealing with sign-off.
I don’t have to think about whether a pull request is small enough for an exception or not.
It turned to an automatism and is done very fast.

Yeah fine, but how is this done correct?

On the commandline

This is really straight forward if you are already working with the git command line.
You just have to configure your credentials one time with:

$ git config --global user.name "John Doe"
$ git config --global user.email johndoe@example.com

(Of course with your name and email.)

You can then sign off a commit with the -s flag:

$ git commit -s -m "This is my commit message"

That’s it. Git will add the correct paragraph at the end of your commit message.

In the GitHub web editor

This is also not difficult, but unfortunately there is no native way to automate this.
(I think GitHub should have come up with a native solution long ago, but thats how it is currently…)

When you use the web editor, you have some form at the bottom of the edit page.

You can add your sign-off-statement in the extended description.
Make sure that it is the last sentence of your commit.

DCO Check will recognise it and should pass.
(Maybe there can be other problems with your github account configuration, but mostly it should work now.)

7 Likes

Once a commit has been submitted, TMK there is no way to amend the commit through the GH web interface. If you refuse to touch the command line to correct this :frowning_face:, you’d need to close the PR, commit again to another branch, and submit another PR. If you are willing to use the commandline, you will need to amend your commit (from inside a directory of your local repository)…

git commit --amend

… which will bring up your commit message in your commandline editor (like vi, if in Linux), where you can modify the commit message to include your Signed-Off-By. After the edit, save the commit message (escape, :wq, if in vi), then force push to get the changes to the remote…

git push --force

If you forget this command, you will find it in the details of the DCO message or https://help.github.com/en/articles/changing-a-commit-message. There is some more documentation about signing your work here…

2 Likes

Thanks for complementing this. :slight_smile:

1 Like

Let’s say you forgot the sign-off-statement or, as more often occurs in my case, I added the signed off line to the wrong thing (the PR comment instead of the commit comment).

I know there is a way to added the sign off after the fact from the command line, but if I made the PR completely through the browser in github there is no way that I could find to retroactively add the signoff through GitHub. As far as I can tell, I’d have to clone my fork to a local machine, checkout to the right branch, then run git commit --amend -s followed by git push -f (note this is based on research, I’ve not done it yet so can’t say for sure it works).

Edit: Oops, looks like Scott beat me to the punch. That’s what I get for leaving the browser page up for awhile before responding.

As already stated above.

I think its a pitty that GitHub can’t deal with that.
SIgn-off is a common practice in open source repositories, so there is a huge usecase for sure.

Since a lot of us are using VSCode, I suppose it’s worth mention that you you can do this through VSCode as well.

To create a PR and sign off your commits properly in VSCode…

Assumptions:

  • already forked the main repo
  • cloned your fork to a local directory
  • opened the repo into VSCode
  • you are already checked out to the “main” branch, whatever that may be named for the given repo (it’s not always “main”)
  1. Create a branch for your PR. First click on the Source Control Icon on the left (ctrl-shift-g)
    image

  2. Click the three dots menu to bring up “More Actions” and choose “Check out to”
    image

  3. Choose “Create new branch…” or, if you want to create a new branch from some other branch that isn’t main, or you are not currently checked out to the main branch choose “Create new branch from…”. Give the branch a meaningful name.

  4. Make your edits.

  5. Return the source Control tab. All of your changes should be in the list.
    image

  6. When you hover over each file you will see three icons. Click the “+” to stage the change. This is the equivalent of running git add <filename>.

  7. Once you’ve staged all the changes you want to check in, click the three dots again and choose “Commit staged (Signed Off)”.

  8. Enter your commit message.

  9. Click the three dots again and choose “Push”. Since this is a new branch it will ask if you want to publish the branch. Choose “OK”

  1. Select “origin” from the list. Unless you are a maintainer like Confectrician or 5iver you probably don’t have permission to push to “upstream”. You only have to do this once. Subsequent pushes will go to origin.

  2. Open your fork on GitHub. You will see a new button asking if you want to compare and create a PR. Click on it.

  1. Fill out the comments and make sure the PR has a meaningful name and click the “Create pull request” button.

Where I’ve gone wrong in the past is I’ve tried to add the signed off line to the PR comment, not the commit. It needs to be made to the commit.

Question, do all commits need to be signed off or just the first commit of the PR?

Hope someone finds this useful.

3 Likes

A sign off is done and checked per commit.

Adding a note for Windows users, as I had an hard time to get signatures running.
If you have problems with signatures (that is, every time you start a session with VScode your signature seem to be gone and you seem to be required to restartthe signing creation process once again from scratch,),
this is the solution which worked for me:
a) install GPG4win
b) at elevated prompt, issue

git config --global gpg.program “C:\Program Files (x86)\GnuPG\bin\gpg.exe”

Signing off is something different that signing your commit. Sign-off is a comment in the commit message and with that you acknowledge you created the code. Signing a commit is what requires pgp and will result in GitHub showing it as verified. We do require to sign-off on commits, but we don’t require to sign your commits. So setting it up with pgp is not needed to contribute to openHAB.

1 Like

wow… I did not know that! I thought that both were required. How much time spoiled then!
Now I understand… I was thinking what’s the point of adding that text if you have already a securely signed commit? Just wish DCO were smart enough to consider the commmit signed if it is securely signed.
@Confectrician you may want to consider adding a line on this in your directions. Maybe it’s me, but I gave for assumed that signing off was just a part of the signing process that - once you google it - gets you in the gpg tunnel.

1 Like

Sorry for the spoiled time.
We should than add this for sure!

2 Likes

no worries. Now I can show off around flashy digital signatures (ahem :nerd_face:)

I have added following paragraph in the first posting:

What is a sign-off-statement

Basically that is just a “comment” you make for every commit you are trying to contribute,
which has to be in a specified format with specified contents and it should be the last line of each commit you want to contribute.

Important: A sign-of-statement is not related to securely signed or verified commits. No need to dig into signatures and keays. We just need the comment with your name and email!

1 Like

The documentation also contains some details about this that are relevant but not mentioned here. Like you need to use your real name and a valid email address: Contribution | openHAB

Also it may not be clear why this sign off is needed. It’s a legal thing. In short it means you wrote the contribution yourself and agree it will be distributed by openHAB under the license specified by the project (I summarized the Developer Certificate of Origin that is described at the documentation page I mentioned.)

I have added that as link in the first posting too.

what I am curious about is… the legal validity. I mean, couldn’t I sign
Signed-off-by: Genghis Khan g.huangdi@mongol.empire?

1 Like

Maybe you can. But i’d expect that to fail checks (possibly some “test email address” bot, possibly the maintainer who will commit your change).

BTW: WTF means DCO? Oh well, i know. Got it from Mrs Google asking for “GitHub DCO”. Anyhow I think it’s worth to be mentioned in the first article. Developer Certificate of Origin (DCO ) that is, isn’t it? :wink:

But if DCO is unrelated to signing, what certificate is used?? :thinking:

well obviously I was not being aggressive but I was thinking of false impersonation
something like
Signed-off-by: Marino Schwedhelm marino.schw********@bingo-ev.de

As for DCO, GitHub Apps - DCO · GitHub

AFAIK, DCO will fail if that user/e-mail is not connected with your github user account.

1 Like