docs: Add Table of Contents and consolidated guide to signing.md (#455) (#692)

Signed-off-by: Rishabh Ranjan Singh <[email protected]>
Signed-off-by: exploreriii <[email protected]>
Co-authored-by: exploreriii <[email protected]>

Author: Rishabh1925

CHANGELOG.md

@@ -27,6 +27,7 @@ This changelog is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.
 - fix: Replaced `collections.namedtuple` with `typing.NamedTuple` in `client.py` for improved type checking.
 - chore: Refactored examples/custom_fee.py into three separate example files.
 - Expanded `docs/sdk_developers/checklist.md` with a self-review guide for all pull request submission requirements (#645).
+- Expanded docs/sdk_developers/signing.md to clarify GPG and DCO requirements and add a Table of Contents (#455).
 - chore: Standardized client initialization across all examples/ files to promote consistency (#658).
 
 

docs/sdk_developers/signing.md

@@ -1,30 +1,49 @@
-# ✅ Commit Signing Guidelines (DCO + GPG)
+# Commit Signing Guidelines (DCO + GPG)
 
 To contribute to this repository, **both DCO sign-off and GPG signature verification** are required for your commits to be merged successfully.
 
 This guide walks you through how to correctly configure and sign your commits, and how to ensure **all commits are properly signed**.
 
 ---
 
-## 🛡️ Why Commit Signing?
+## Table of Contents
+- [Achieving Verified Commits (The Requirements)](#achieving-verified-commits-the-requirements)
+- [Step-by-Step Setup](#step-by-step-setup)
+  - [1. Generate a GPG Key](#1-generate-a-gpg-key)
+  - [2. Add Your GPG Key to GitHub](#2-add-your-gpg-key-to-github)
+  - [3. Configure Git to Use Your GPG Key](#3-configure-git-to-use-your-gpg-key)
+- [Make Signed Commits](#make-signed-commits)
+- [Fixing Unsigned Commits](#fixing-unsigned-commits)
+- [Rebasing and Signing](#rebasing-and-signing)
+- [Verify Signed Status of Commits](#verify-signed-status-of-commits)
+- [Final Checklist](#final-checklist)
 
-* **DCO (`Signed-off-by`)** ensures you agree to the developer certificate of origin.
-* **GPG Signature** proves the commit was authored by a trusted and verified identity.
+---
+
+## Achieving Verified Commits (The Requirements)
+
+Achieving a **"Verified"** status on GitHub is a **MANDATORY** requirement for all Pull Requests to be merged into the Python SDK. PRs without this badge will be blocked by CI checks.
+
+| Signature | Flag | Purpose | GitHub Check | Required Documentation |
+| :--- | :--- | :--- | :--- | :--- |
+| **DCO Sign-off** | `-s` | Confirms legal right to contribute code (Required by the CI bot). | DCO Check | [CONTRIBUTING.md](/CONTRIBUTING.md) |
+| **GPG Signature** | `-S` | Proves you are the author of the commit (Requires GPG setup). | Verified Badge | [GitHub's GPG Docs](https://docs.github.com/en/authentication/managing-commit-signature-verification) |
+
+**CRITICAL WARNING:** To pass all checks and achieve the "Verified" status, **all commits** must be signed using **both** the `-S` and `-s` flags together.
 
 ---
 
-## ✍️ Step-by-Step Setup
+## Step-by-Step Setup
 
 ### 1. Generate a GPG Key
 
-If you don’t already have a GPG key:
+If you don't already have a GPG key:
 
 ```bash
 gpg --full-generate-key
 ```
 
 Choose:
-
 * Kind: RSA and RSA
 * Key size: 4096
 * Expiration: 0 (or choose as per your need)
@@ -50,7 +69,6 @@ gpg --armor --export YOUR_KEY_ID
 ```
 
 Paste the output into GitHub:
-
 * [Add GPG key on Github](https://github.com/settings/gpg/new)
 
 ---
@@ -64,7 +82,7 @@ git config --global commit.gpgsign true
 
 ---
 
-## ✨ Make Signed Commits
+## Make Signed Commits
 
 **All commits must be signed using both DCO and GPG.**
 
@@ -79,7 +97,7 @@ git commit -S -s -m "chore: your commit message"
 
 ---
 
-## 🛠️ Fixing Unsigned Commits
+## Fixing Unsigned Commits
 
 If you accidentally forgot to sign commits, there are **two ways to fix them**:
 
@@ -91,8 +109,8 @@ Soft revert the impacted commits while keeping changes locally:
 git reset --soft HEAD~n
 ```
 
-* `HEADn` = number of commits to go back
-* Example: To fix the last 3 commits: `git reset --soft HEAD`
+* `HEAD~n` = number of commits to go back
+* Example: To fix the last 3 commits: `git reset --soft HEAD~3`
 
 Then, recommit each commit with proper signing:
 
@@ -110,25 +128,25 @@ Alternatively, you can **amend commits retroactively**:
 
 ```bash
 git commit --amend -S -s
-git rebase -i HEAD~n  # For multiple commits
+git rebase -i HEAD~n            # For multiple commits
 git push --force-with-lease
 ```
+
 ## Rebasing and Signing
 
 Rebase operations will be required when your branch is behind the upstream main. See [rebasing.md](./rebasing.md) for instructions on how to keep your main branch up to date and how to rebase.
 
-
 When rebasing, you must use this command to ensure your commits remain verified:
 
 ```bash
 git rebase main -S
 ```
 
-> **Note:** `--force-with-lease` safely updates the remote branch without overwriting others’ changes.
+> **Note:** `git push --force-with-lease` safely updates the remote branch without overwriting others' changes.
 
 ---
 
-## ✅ Verify Signed Status of Commits
+## Verify Signed Status of Commits
 
 To check that your commits are signed correctly:
 
@@ -147,7 +165,7 @@ git log -n 5 --pretty=format:'%h %an %G? %s'
 
 ---
 
-## ✅ Final Checklist
+## Final Checklist
 
 * [ ] All commits signed with `-S`
 * [ ] DCO added with `-s`
@@ -158,5 +176,5 @@ git log -n 5 --pretty=format:'%h %an %G? %s'
 
 ### Still Need Help?
 
-* Refer to [GitHub’s GPG Docs](https://docs.github.com/en/authentication/managing-commit-signature-verification)
-* Ask maintainers on the **Hiero Discord** if stuck
+* Refer to [GitHub's GPG Docs](https://docs.github.com/en/authentication/managing-commit-signature-verification)
+* Ask maintainers on the **Hiero Discord**