mirror of
https://gitlab.eurecom.fr/oai/openairinterface5g.git
synced 2026-07-13 04:30:28 +00:00
doc: add a Git guide and fix addconsoletrace typo
Add doc/git-guide.md, a single entry point for the practical Git knowledge needed to contribute to OAI, consolidating the how-tos that were scattered across the documentation: - Setting up commit signing: moved from CONTRIBUTING.md, which keeps the normative DCO/Verified requirements and links to the guide; led by a compact SSH recipe, with the allowed_signers troubleshooting and a note on repository-level configuration for shared servers. - Managing your own branch: moved from code-style-contrib.md, which keeps the workflow policy and links to the guide; mentions git switch and covers fixup commits with git rebase --autosquash, including the --fixup=amend:<commit> variant. - Working with submodules: the update command and the unintended submodule-pointer-update pitfall seen in past PRs. - Recovering from mistakes: git restore --staged, git restore, git reset --soft/--hard, and git reflog. - Reusing conflict resolutions with git rerere: enabling, typical flow, inspecting, seeding from existing history, sharing the cache, and caveats, clarifying that contribution branches must keep a linear history while forks may carry merge commits. The guide is referenced from doc/README.md (Developer tools), code-style-contrib.md, and CONTRIBUTING.md. Guidance coupled to its own document is cross-linked instead of moved: clang-format.md (pre-commit hook), GET_SOURCES.md (branch and tag model), and doc_best_practices.md (docs: commit prefix). Also fix a typo in the T tracer addconsoletrace documentation. Signed-off-by: Andrea Lacava <thecave003@gmail.com>
This commit is contained in:
Andrea Lacava
112
CONTRIBUTING.md
112
CONTRIBUTING.md
@@ -30,114 +30,10 @@ Every pull request must pass two CI checks before it can be merged:
|
||||
|
||||
### Signing Commits
|
||||
|
||||
GitHub supports commit signing using either SSH keys or GPG keys.
|
||||
For more information, see the
|
||||
[GitHub documentation](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits).
|
||||
|
||||
Before configuring commit signing:
|
||||
|
||||
- Generate an SSH key pair or GPG key pair.
|
||||
- Add your public key to your GitHub account.
|
||||
- Verify your GitHub email address (required for “Verified” commits to work).
|
||||
- If using SSH signing, ensure the key is registered in GitHub for:
|
||||
- Authentication (SSH and GPG keys)
|
||||
- Signing commits (Signing Keys)
|
||||
|
||||
> **NOTE:**
|
||||
> Adding an SSH key for repo access does not automatically enable commit signing.
|
||||
> The key must also be added under GitHub's Signing Keys settings.
|
||||
|
||||
|
||||
To ensure commits show as Verified on GitHub:
|
||||
|
||||
- Your `git config user.email` must match a GitHub email
|
||||
- That email must be verified in your GitHub account
|
||||
|
||||
For more information, see the
|
||||
[GitHub Docs](https://docs.github.com/en/account-and-profile/how-tos/email-preferences/verifying-your-email-address)
|
||||
|
||||
Configure your repository's `.git/config`:
|
||||
|
||||
```ini
|
||||
# Edit the git configuration
|
||||
|
||||
[user]
|
||||
name = YOUR NAME
|
||||
email = YOUR VERIFIED EMAIL ADDRESS
|
||||
|
||||
# REQUIRED for commit signing
|
||||
# Use ONE signing method (SSH or GPG)
|
||||
|
||||
signingkey = YOUR_SIGNING_KEY
|
||||
|
||||
# Examples:
|
||||
# SSH signing:
|
||||
# signingkey = ~/.ssh/id_ed25519.pub
|
||||
|
||||
# GPG signing:
|
||||
# signingkey = YOUR_GPG_KEY_ID
|
||||
|
||||
[gpg]
|
||||
# REQUIRED: defines signing method (SSH or GPG)
|
||||
|
||||
format = YOUR_SIGNING_FORMAT
|
||||
|
||||
# Examples:
|
||||
# SSH signing:
|
||||
# format = ssh
|
||||
|
||||
# GPG signing:
|
||||
# format = openpgp
|
||||
|
||||
[commit]
|
||||
gpgsign = true
|
||||
```
|
||||
|
||||
> The private key is used automatically by SSH/Git when signing commits (SSH only).
|
||||
|
||||
#### Verifying Signed Commits
|
||||
|
||||
You can verify that commits are properly signed locally using:
|
||||
|
||||
```bash
|
||||
git log --show-signature
|
||||
```
|
||||
|
||||
GitHub should also display a Verified badge next to signed commits once the
|
||||
signing key has been correctly configured in your account.
|
||||
|
||||
##### SSH Signature Verification (`allowed_signers`)
|
||||
|
||||
For SSH commit signing, local Git verification may require an `allowed_signers`
|
||||
file. This is only used for local verification in Git and is not required
|
||||
by GitHub.
|
||||
|
||||
If you see errors such as:
|
||||
|
||||
```text
|
||||
No principal matched
|
||||
Can't check signature
|
||||
error: gpg.ssh.allowedSignersFile needs to be configured
|
||||
```
|
||||
you may need to configure it.
|
||||
|
||||
Create the file and add your signing identity:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/git
|
||||
touch ~/.config/git/allowed_signers
|
||||
echo "user@example.com ssh-ed25519 AAAACexamplekeystringhere" > ~/.config/git/allowed_signers
|
||||
```
|
||||
|
||||
Enable it in local repository Git config:
|
||||
|
||||
```bash
|
||||
git config gpg.ssh.allowedSignersFile ~/.config/git/allowed_signers
|
||||
```
|
||||
|
||||
> **NOTE:**
|
||||
> This is only for local Git signature verification and does not affect GitHub,
|
||||
> or remote repository behavior.
|
||||
GitHub supports commit signing using either SSH keys or GPG keys. For the
|
||||
step-by-step setup (key generation, Git configuration, registering the key on
|
||||
GitHub, and verifying signatures locally), see the
|
||||
[commit signing section of the Git guide](doc/git-guide.md#setting-up-commit-signing).
|
||||
|
||||
> **NOTE:** If your commits are not signed, the CI framework will not accept the PR.
|
||||
For more information regarding contribution guidelines
|
||||
|
||||
Reference in New Issue
Block a user