Git, GitHub and open-source contribution

A starting question

Two students work on the same file. One sends it to the other by messaging; the other replies with "final version 2". Three days later nobody knows which version is right. Git solves this problem: it keeps the history of each change, who made it, when, and why.

What a commit is

A commit is a snapshot of all the project's files at a given moment, with: an author, a date, a message, and a link to the parent commit(s). Git identifies each commit by a hash computed from all this content, including the parent's hash. Historically this hash is a SHA-1; Git can also work with SHA-256 (see the note below).

As with a blockchain, changing an old commit changes its hash, hence that of all its descendants. In the hash tool, change one letter of a text and watch: the hash is completely different. In the chain explorer, edit block 2: all later ones "break". It is the same idea.

Two honest differences from a blockchain:

• There is no consensus. Everyone owns a full copy and can rewrite their local history. The project's "truth" is whatever the team agreed to treat as the reference repository (usually the main branch of the main repository).
• A Git hash identifies content; it does not prove who wrote it (except through commit signing, see lesson 4).

The three areas

working directory  --git add-->  index (staging area)  --git commit-->  repository (history)

• git status shows what changed and what is ready to be committed.
• git add file chooses what enters the next commit (one commit = one idea, not everything you touched).
• git commit creates the snapshot.

Branches: labels that move

A branch is simply a pointer to a commit. Creating a branch copies nothing:

git switch -c feature/fees       # create and move to the branch
git log --oneline --graph --decorate --all

Example output:

* 9f3c2ab (HEAD -> feature/fees) Add fee estimate helper
* 41d7e90 Fix typo in README
| * c0a11fe (origin/main, main) Update CI node version
|/
* 7b2e5d1 Initial import

Reading: from the initial commit 7b2e5d1, main advanced by one commit (c0a11fe) and feature/fees by two. HEAD is the branch you are on. origin/main is what you know of main on the server as of the last git fetch.

Good commit messages

A message is read months later by someone searching why a line exists. A widespread convention (not a law):

Reject negative amounts in transfer()

A negative amount credited the sender. Validate amount > 0
and add tests for -1 and 0.

A short imperative subject (about 50 characters), a blank line, then the why. A message like "fix" or "WIP" teaches nothing. A commit mixing three subjects cannot be undone cleanly.

Controlled rewriting

Git lets you rewrite history: git commit --amend (the last commit), git rebase -i HEAD~3 (combine, rename, reorder three commits). Every rewrite creates new commits with new hashes. Golden rule:

• Rewriting is safe as long as the commits are yours alone (not yet pushed, or on your pull-request branch that nobody else uses). To push after rewriting: git push --force-with-lease (more cautious than --force: it refuses if the remote branch has moved since your last fetch, for instance because someone else pushed to it; an automatic git fetch by your editor can however update your view and defeat this protection).
• Rewriting is forbidden on a shared branch (main): your colleagues built on it.
• To undo a commit already shared, use git revert <hash>: it creates a new commit that cancels the old one, rewriting nothing.

Safety net: git reflog lists the places HEAD has been, even after a rewrite, which generally lets you recover a "lost" commit for some time. git reset --hard, however, permanently discards uncommitted changes.

What this does NOT guarantee

• A clean history is not correct code: it says what changed, not that it works.
• Git does not prove the author's identity: a commit's name and e-mail are fields anyone can write.
• git revert does not erase the trace of a secret or a mistake: the old commit stays in history.

Recap

A commit = a snapshot linked to its parent by a hash; a branch = a pointer. Rewrite only what is yours alone, and use revert for what is shared.

The problem

Amina and Paul each edit a tool's configuration file. Amina sets fees to 15 on her branch; Paul, after talking with the team, sets them to 12 on main. When Amina wants to bring in main, Git cannot guess who is right. It stops and asks: this is a conflict. It is not a failure; it is Git refusing to choose for you.

Two ways to integrate

Merge: git merge main (from your branch) creates a merge commit that has two parents. History keeps the real shape of the work, with its forks. If your branch has not diverged, Git simply moves the pointer forward (fast-forward), with no merge commit.

Rebase: git rebase main replays your commits one by one on top of the latest commit of main. History becomes a straight line, but your commits receive new hashes: it is a rewrite (lesson 1). You therefore rebase your own unshared commits, never those of a branch others use.

Projects choose their policy (merge, rebase, "squash" into a single commit): read the CONTRIBUTING file before choosing.

Anatomy of a conflict

After git merge main, Git prints:

Auto-merging config.toml
CONFLICT (content): Merge conflict in config.toml
Automatic merge failed; fix conflicts and then commit the result.

And the file contains:

<<<<<<< HEAD
fee = 15
=======
fee = 12
>>>>>>> main
timeout = 30

• Between <<<<<<< HEAD and =======: your version (the branch you are on).
• Between ======= and >>>>>>> main: the version coming from the other branch.
• timeout = 30 is outside the markers: Git merged it without difficulty.

Resolving: decide, edit, commit

Reminder: the team decided 12 (discussion in the ticket). The steps:

1. Decide which value is right. Git cannot decide; do not take "mine" by reflex.
2. Edit the file so it contains the intended result, with no marker at all:

fee = 12
timeout = 30

1. git add config.toml to mark the conflict as resolved.
2. git merge --continue (or git commit) to finish the merge. In a rebase, it would be git rebase --continue.
3. Run the tests. A merge with no markers is not necessarily correct (see below).

To undo everything and return to the earlier state: git merge --abort (or git rebase --abort). It is the emergency exit.

Not losing work

• Before a risky merge, commit (git commit) or set aside (git stash) your changes.
• Create a backup branch: git branch backup-before-merge; it costs nothing.
• After resolving, re-read with git diff and run the tests.
• If you are lost: git status says exactly what state you are in and what to do next. Then git merge --abort.

A semantic conflict: no markers, but wrong

Amina renames the function compute_fee to estimate_fee on her branch. Paul adds on main a new call to compute_fee in another file. Git merges without conflict, since the changed lines differ. But the code now calls a function that no longer exists: the program fails. A successful textual merge does not guarantee a correct program, hence the "run the tests" step.

Worked example

Two branches modify the same 200-line file: B changes 10 lines, C changes 4 (Git always merges two branches at a time). If 3 consecutive lines of C are also modified by B, Git produces a single conflict block of 3 lines; if those 3 lines are separated by unchanged lines, there is one block per group. Beware: changes to adjacent lines (line 2 on one side, line 3 on the other) are already a conflict, even with no overlap; at least one unchanged line is needed between two modified areas for Git to merge them alone (behaviour observed with Git 2.43 on default settings). A conflict is a block of lines, not a line.

What this does NOT guarantee

• Resolving a conflict is not the team's agreement: if you ignore the ticket's decision, you create a silent bug.
• git merge --abort does not recover work you yourself discarded with reset --hard.
• A clean rebase says nothing about the state of the tests.

Recap

A conflict calls for a human decision. Decide, edit with no markers, add, continue, test; --abort is always possible; back up before risking.

The problem

You want to fix a typo in the documentation of a repository that is not yours. You are not allowed to write to it directly, and fortunately so: anyone could otherwise break the project. The standard flow lets you propose a change that maintainers examine before accepting.

The flow, step by step

1. Fork: on GitHub, you create your copy of the repository (the fork). You can write to it.
2. Clone: you copy your fork to your machine.
3. Upstream remote: you declare the original repository as a second remote, to follow it.
4. Branch: you work on a dedicated branch, never directly on main.
5. Push: you push the branch to your fork.
6. Pull request (PR): on GitHub, you ask for your branch to be integrated into the original repository.
7. Review: maintainers comment; you answer and fix; they accept or not.

git clone <url-of-your-fork>
cd repo
git remote add upstream <url-of-the-original-repo>
git remote -v                          # origin = your fork, upstream = the original
git fetch upstream
git switch -c docs/fix-typo-install    # dedicated branch, meaningful name
# ... edit, then:
git add docs/install.md
git commit -m "Fix typo in install instructions"
git push -u origin docs/fix-typo-install

Then, on GitHub, open the PR: base = the original repository's main branch, compare = your branch in your fork.

A good pull request

• A single subject, small. The bigger a PR, the slower it is to review and the easier to reject.
• A clear title and a description: what, why, how verified. If it answers a ticket, write Closes #123: when merged into the default branch, GitHub closes ticket 123 automatically.
• The automatic checks (CI) must pass. They are described in workflow files; see the GitHub Actions documentation.
• Read `CONTRIBUTING` before writing: style, tests, message format, sometimes a Signed-off-by line (git commit -s) or a contribution agreement.
• For a big change, open a ticket first to ask whether the project wants it.
• A draft PR signals "not ready for review yet".

Answering a review

The reviewer writes: "Can you add a test for the amount = 0 case? And rename tmp?". Good conduct:

1. Read each comment and decide: I apply it, or I politely explain why not.
2. Make the fixes on the same branch and push: the PR updates itself. Do not close the PR to open a new one.
3. Answer each thread ("done in 3f2a9c1" or an explanation); mark "resolved" only what really is.
4. If the project asks for a clean history, combine the fixes with an interactive rebase then git push --force-with-lease — only on your PR branch.
5. Request review again once the points are handled.

A review criticises the code, not the person. A PR being refused is not a judgment on you: maintainers must preserve the project's coherence. If a disagreement persists, ask, do not argue.

Keeping your fork up to date

While your PR is in review, main moves on. To stay current:

git fetch upstream
git rebase upstream/main        # or: git merge upstream/main, depending on project policy
git push --force-with-lease     # if you rebased your PR branch

Worked example: a PR that is too big

A PR changes 1,200 lines in 14 files, for three subjects. A reviewer reading 200 lines per sitting will need 6 sittings and may no longer remember the beginning by the end. Split into three PRs of 400 lines on one subject each, each PR is reviewed in about 2 sittings and can be accepted or refused separately. The total reading is the same; the risk and the delay are not.

What this does NOT guarantee

• An approved PR is not a correct PR: human review misses errors. Tests are another safety net.
• A green CI proves the planned checks pass, not that no bug exists.
• Opening a PR gives no right to its acceptance or to a quick answer: maintainers are often volunteers.

Recap

Fork, dedicated branch, small and clear PR, review answers on the same branch, fork kept up to date. A review is an exchange about the code.

The problem

A motivated student wants to contribute to a large protocol repository. On day one they open ten PRs to "reformat the code". All are closed. Why? Because they neither read the rules nor asked what the project needed. Contributing is a relationship as much as code.

Where to start

Large protocol repositories are public, for example those of Polkadot SDK or Cosmos SDK. Reasonable first contributions are modest:

• Fix a documentation typo or a dead link.
• Improve or translate a guide (if the project accepts translations).
• Reproduce a reported bug and write a test case.
• Take a ticket marked for beginners (often "good first issue"), after commenting that you are taking it, so two people do not do the same thing.

Before proposing anything: read the README, CONTRIBUTING, the code of conduct, the licence. The licence says under what conditions your contribution is published and reused; by contributing you generally agree it will be under the project's licence. Never send code you have no right to publish (an employer's code, copied without a suitable licence).

Be brief and precise in a request for help: tool version, command run, full error message, what you already tried.

Proving who wrote a commit

A commit's name and e-mail are freely written; anyone can put a false one. To tie a commit to a key, Git lets you sign it (git commit -S, with a GPG key or, in recent versions, an SSH key). GitHub then shows "Verified" if the signature matches a key registered on your account and the commit's e-mail address is a verified address of that account. The signature proves the key holder created the commit; it does not prove the content is good (back to the workshop on signatures).

The accidentally pushed secret

Scenario: Aïssatou works on a public repository. She adds a .env file containing a test API key and pushes it. Ten minutes later she notices, deletes the file and pushes a new commit. Is it settled? No.

Why deleting is never enough:

• The file stays in the previous commit, hence in the history anyone can clone.
• Programs continuously scan public repositories looking for keys; a published key can be found very quickly. Assume it is already copied.
• Forks, clones and caches may have kept the version.
• Even if you rewrite history and force-push, copies already made still exist.

Correct order of action:

1. Revoke or renew the key immediately at the service provider (this is what makes it useless). For a chain wallet key: consider the funds exposed and move them to a new key, without waiting.
2. Check usage: the service's access logs, the key's activity, to know whether it was used.
3. Remove the secret from current files and add the pattern to the .gitignore file (.env). Beware: .gitignore does not affect a file Git already tracks; you also need git rm --cached .env so that Git stops tracking it.
4. Only then, clean the history if needed (for example with the git filter-repo tool then a forced push, warning the team): this is hygiene, not security.
5. Prevent recurrence: a .env.example file without values, an automatic secret check before commit or in CI, and the host's secret-scanning feature (which detects only known patterns).

Worked example of what the order costs: renewing the key takes 5 minutes; cleaning the history and warning a team of 10 takes an hour. If you clean first, the key stays valid during that hour. The order is not a matter of taste.

What this does NOT guarantee

• Signing your commits does not protect against theft of the signing key: protect it like an SSH key.
• A secret-detection tool does not find everything: a key with no recognisable pattern slips through.
• Contributing to a large repository guarantees neither an answer, nor acceptance, nor a job: it is a way to show verifiable work.

Recap

Start small, read the rules, ask before launching in. A pushed secret is a lost secret: revoke first, clean afterwards.