|
| 1 | +# Commit Signing Requirements |
| 2 | + |
| 3 | +This document explains how to ensure your commits comply with both the Developer Certificate of Origin (DCO) requirements and GPG signing requirements for this project. |
| 4 | + |
| 5 | +## What is the DCO? |
| 6 | + |
| 7 | +The Developer Certificate of Origin (DCO) is a lightweight way for contributors to certify that they wrote or otherwise have the right to submit the code they are contributing to the project. See the full text in the [CONTRIBUTING.md](../CONTRIBUTING.md#developer-certificate-of-origin-signing-your-work) file. |
| 8 | + |
| 9 | +## Two Required Signature Types |
| 10 | + |
| 11 | +All commits to this repository must have two types of signatures: |
| 12 | + |
| 13 | +1. **DCO Sign-off**: A `Signed-off-by` line in the commit message |
| 14 | +2. **GPG Signature**: A cryptographic signature verifying the committer's identity |
| 15 | + |
| 16 | +## Adding DCO Sign-offs to Commits |
| 17 | + |
| 18 | +All commits must include a `Signed-off-by` line in the commit message. This line certifies that you have the right to submit your contribution under the project's license. |
| 19 | + |
| 20 | +### Using the -s Flag |
| 21 | + |
| 22 | +The simplest way to add a sign-off to your commits is to use the `-s` flag with the `git commit` command: |
| 23 | + |
| 24 | +```sh |
| 25 | +git commit -s -m "Your commit message" |
| 26 | +``` |
| 27 | + |
| 28 | +This will automatically add a `Signed-off-by` line with your name and email to the commit message. |
| 29 | + |
| 30 | +### Configuring Git for Automatic Sign-offs |
| 31 | + |
| 32 | +You can configure Git to automatically add sign-offs to all your commits: |
| 33 | + |
| 34 | +```sh |
| 35 | +git config --global commit.signoff true |
| 36 | +``` |
| 37 | + |
| 38 | +Alternatively, you can create a Git alias for creating signed-off commits: |
| 39 | + |
| 40 | +```sh |
| 41 | +git config --global alias.cs 'commit -s' |
| 42 | +``` |
| 43 | + |
| 44 | +Then use `git cs` instead of `git commit` to create commits with sign-offs. |
| 45 | + |
| 46 | +## GPG Signing Your Commits |
| 47 | + |
| 48 | +In addition to DCO sign-offs, all commits must be GPG signed to verify your identity. |
| 49 | + |
| 50 | +### Setting Up GPG |
| 51 | + |
| 52 | +1. If you don't have a GPG key, generate one: |
| 53 | + |
| 54 | + ```sh |
| 55 | + gpg --full-generate-key |
| 56 | + ``` |
| 57 | + |
| 58 | + Choose RSA and RSA, 4096 bits, and an expiration date of your preference. |
| 59 | + |
| 60 | +2. List your keys to get the ID: |
| 61 | + |
| 62 | + ```sh |
| 63 | + gpg --list-secret-keys --keyid-format=long |
| 64 | + ``` |
| 65 | + |
| 66 | + Look for the line starting with "sec" and note the key ID after the "/". |
| 67 | + |
| 68 | +3. Configure Git to use your GPG key: |
| 69 | + |
| 70 | + ```sh |
| 71 | + git config --global user.signingkey YOUR_KEY_ID |
| 72 | + ``` |
| 73 | + |
| 74 | + Replace YOUR_KEY_ID with your actual GPG key ID. |
| 75 | + |
| 76 | +4. Configure Git to sign commits automatically: |
| 77 | + |
| 78 | + ```sh |
| 79 | + git config --global commit.gpgsign true |
| 80 | + ``` |
| 81 | + |
| 82 | +### Creating GPG Signed Commits |
| 83 | + |
| 84 | +With automatic signing enabled, normal commit commands will create signed commits. You can also explicitly sign with: |
| 85 | + |
| 86 | +```sh |
| 87 | +git commit -S -m "Your commit message" |
| 88 | +``` |
| 89 | + |
| 90 | +To create a commit with both GPG signature and DCO sign-off: |
| 91 | + |
| 92 | +```sh |
| 93 | +git commit -S -s -m "Your commit message" |
| 94 | +``` |
| 95 | + |
| 96 | +### Adding Your GPG Key to GitHub |
| 97 | + |
| 98 | +1. Export your public key: |
| 99 | + |
| 100 | + ```sh |
| 101 | + gpg --armor --export YOUR_KEY_ID |
| 102 | + ``` |
| 103 | + |
| 104 | +2. Copy the output and add it to your GitHub account under Settings > SSH and GPG keys. |
| 105 | + |
| 106 | +## Adding Both Signatures to Existing Commits |
| 107 | + |
| 108 | +If you forgot to sign your commits, you can fix them: |
| 109 | + |
| 110 | +### For the Last Commit |
| 111 | + |
| 112 | +```sh |
| 113 | +git commit --amend --no-edit -S -s |
| 114 | +``` |
| 115 | + |
| 116 | +### For Multiple Commits |
| 117 | + |
| 118 | +For adding both DCO sign-offs and GPG signatures to a range of commits, use interactive rebase: |
| 119 | + |
| 120 | +1. Start the rebase: |
| 121 | + |
| 122 | + ```sh |
| 123 | + git rebase -i HEAD~n |
| 124 | + ``` |
| 125 | + |
| 126 | + Replace `n` with the number of commits you want to sign. |
| 127 | + |
| 128 | +2. In the editor, change `pick` to `edit` for each commit. |
| 129 | + |
| 130 | +3. For each commit that opens during the rebase: |
| 131 | + |
| 132 | + ```sh |
| 133 | + git commit --amend --no-edit -S -s |
| 134 | + git rebase --continue |
| 135 | + ``` |
| 136 | + |
| 137 | +Alternatively, for adding just DCO sign-offs to multiple commits: |
| 138 | + |
| 139 | +```sh |
| 140 | +git rebase --signoff HEAD~n |
| 141 | +``` |
| 142 | + |
| 143 | +## Verification |
| 144 | + |
| 145 | +The project uses automated checks to verify that all commits include both the required DCO sign-off and GPG signature. If you receive a signature verification failure notification, please follow the instructions above to add the required signatures. |
| 146 | + |
| 147 | +## Troubleshooting |
| 148 | + |
| 149 | +### GPG Signing Issues |
| 150 | + |
| 151 | +If you encounter issues with GPG signing: |
| 152 | + |
| 153 | +- Ensure your GPG key is properly generated and configured with Git |
| 154 | +- Set the `GPG_TTY` environment variable: `export GPG_TTY=$(tty)` |
| 155 | +- For Git GUI tools, you may need to configure GPG agent |
| 156 | +- On Windows, you might need to specify the full path to gpg.exe |
| 157 | + |
| 158 | +### DCO Sign-off Issues |
| 159 | + |
| 160 | +If you encounter issues with DCO sign-offs: |
| 161 | + |
| 162 | +- Ensure your Git user name and email are correctly configured |
| 163 | +- Check that the commit author email matches your configured email |
| 164 | +- For commits created through GitHub's web interface, you'll need to add the sign-off manually in the commit message |
0 commit comments