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
2026-07-09 10:43:17 -04:00
parent 0dab3bb6a1
commit 4bff655952
5 changed files with 404 additions and 146 deletions

View File

@@ -118,43 +118,12 @@ e.g., `v3.0`. We target to make releases bi-yearly.
### How to manage your own branch
Before starting to work, please make sure to branch off the latest `develop`
branch. Make commits as appropriate.
```bash
$ git fetch origin
$ git checkout develop
$ git checkout -b my-new-feature # name as appropriate
$ git add -p # add changes for change set 1, use `-p` to review what to include
$ git commit # in the editor, describe your changes
$ git add -p # add changes for change set 2
$ git commit # in the editor, describe your changes
```
Again, commit message should take multiple lines; after the initial title, a
blank line should follow. Read the `DISCUSSION` section in `man git commit` for
more information.
If your development takes longer, make sure to synchronize regularly with
`origin/develop` using `git rebase`:
```bash
$ git fetch origin
$ git rebase -i origin/develop
```
If you do logical changes, you should not have to resolve the same conflicts
over and over again. Note that if you jumped over multiple develop tags, you
can also rebase in intermediate steps, in case you fear the differences might
be too big.
```
$ git rebase -i 2023.w38
$ git rebase -i 2023.w41
$ git rebase -i develop
```
Once you rebased, push the changes to the remote
```
$ git push origin my-new-feature --force-with-lease # force with lease let's you only overwrite what you also have locally in origin/my-new-feature
```
Branch off the latest `develop` branch before starting to work, keep your
branch synchronized with `origin/develop` through regular rebases, and push
with `--force-with-lease` after rebasing. The step-by-step commands — including
how to rebase over multiple develop tags in intermediate steps and how to avoid
resolving the same conflicts repeatedly with `git rerere` — are in the
[branch management section of the Git guide](./git-guide.md#managing-your-own-branch).
### Use of git commit trailers