# First Contributions — Content Guide

> **First Contributions** is a hands-on tutorial repository that walks complete beginners through making their very first open source contribution. It isn't software you install or run — it's a guided, low-stakes practice ground. You fork it, add your name to a single file (`Contributors.md`), and open a pull request, completing the full *fork → clone → branch → edit → commit → push → pull request* workflow that every open source contributor uses. The collection covers this workflow from the command line, from seven different graphical Git tools, and in more than 60 languages, plus a library of advanced Git how-tos and guidance for non-programmers who want to contribute.

This guide explains what the collection contains, how to navigate it, and which path to take based on the tools you use and the language you read. Everything described here is drawn directly from the repository at commit `e63c867`.

> [!NOTE]
> This is a **learning resource**, not a code project. There is nothing to build, deploy, or configure. The "deliverable" is *you* successfully opening your first pull request and getting it merged.

---

## What's in This Collection

The repository is organized around one canonical tutorial (the root `README.md`) with supporting material branching out from the `docs/` directory. The top-level structure maps as follows:

| Path | What's here |
|------|-------------|
| `README.md` | The **main tutorial** — the command-line *fork → clone → branch → edit → commit → push → PR* walkthrough. This is the starting point. |
| `Contributors.md` | The file you actually edit. A long, alphabetically-loose list of every contributor's name (1,456 lines). Adding your name here is the practice task. |
| `docs/translations/` | 108 files — the `README` tutorial translated into 60+ languages (e.g. `README.es.md`, `README.zh-cn.md`, `README.ar.md`). |
| `docs/cli-tool-tutorials/` | Command-line tutorials for the **GitHub CLI** (`gh`) and plain **git CLI**, plus their translations (30 files total). |
| `docs/gui-tool-tutorials/` | Step-by-step tutorials for **seven graphical Git tools**, plus translations (58 files total). |
| `docs/additional-material/git_workflow_scenarios/` | 24 advanced Git how-to documents (amending, rebasing, squashing, resolving merge conflicts, and more). |
| `docs/additional-material/Things a non Programmer can do.md` | 23 concrete ways to contribute to open source *without* writing code. |
| `docs/how-to-contribute-to-open-source-projects.md` | A long-form beginner essay on why and how to contribute to open source generally. |
| `.github/CONTRIBUTING.md` | How to contribute *to this repository* — primarily aimed at people adding or reviewing translations. |
| `.github/SECURITY.md`, `LICENSE` | Security-reporting policy and the MIT license. |

> [!TIP]
> If you only read one file, read the root `README.md`. Every other document in this collection either translates it, re-tells it for a specific tool, or extends it with advanced techniques.

---

## How to Read / Use This

This collection is meant to be **done, not just read**. The intended path is linear for your first pass, then browse-by-topic afterward.

**Prerequisites (the only real ones):**

- A **GitHub account** (free).
- **Git installed** on your machine — the tutorial links to [GitHub's setup guide](https://docs.github.com/en/get-started/quickstart/set-up-git). If you plan to use a graphical tool instead, that tool bundles Git for you.

> [!IMPORTANT]
> You do **not** need to know how to program to complete this tutorial. The practice task is editing a plain text file (`Contributors.md`) and adding your name to it.

**Choose your path based on how you want to work with Git:**

=== "Command line"

    Start with the root [`README.md`](README.md). It uses plain `git` commands. If you prefer GitHub's official `gh` CLI, use [`docs/cli-tool-tutorials/github-cli-tutorial.md`](docs/cli-tool-tutorials/github-cli-tutorial.md) instead.

=== "Graphical tool"

    Skip to the [Section Walkthroughs](#section-walkthroughs) below and pick the tutorial that matches your tool — GitHub Desktop, VS Code, GitKraken, Sourcetree, IntelliJ IDEA, Visual Studio 2017, or Sublime Merge.

=== "In your language"

    Open [`docs/translations/Translations.md`](docs/translations/Translations.md) (or the flag grid at the top of `README.md`) and pick your language. Each translation mirrors the English tutorial.

**Suggested entry points by reader type:**

| You are... | Start here |
|------------|------------|
| A first-timer comfortable with a terminal | Root [`README.md`](README.md) |
| A first-timer who prefers buttons over commands | A [GUI tool tutorial](#2-gui-tool-tutorials-docsgui-tool-tutorials) |
| Not a programmer, but want to help | [`Things a non Programmer can do.md`](docs/additional-material/Things%20a%20non%20Programmer%20can%20do.md) |
| Already made a PR, want to go deeper on Git | [`git_workflow_scenarios/`](docs/additional-material/git_workflow_scenarios/additional-material.md) |
| Wanting the big-picture "why" first | [`how-to-contribute-to-open-source-projects.md`](docs/how-to-contribute-to-open-source-projects.md) |

> [!NOTE]
> After your pull request is merged, a maintainer note in the tutorial points you to the project's companion [web app](https://firstcontributions.github.io/#project-list), which lists other beginner-friendly projects with easy issues to tackle next.

---

## Section Walkthroughs

### 1. The Main Tutorial (`README.md`)

This is the heart of the collection. It walks you through the complete contribution workflow using plain `git` commands, with screenshots at each step:

1. **Fork** the repository (one click on GitHub).
2. **Clone** your fork locally: `git clone "url you just copied"`.
3. **Create a branch**: `git switch -c your-new-branch-name` (the tutorial includes a fallback to `git checkout -b` for older Git versions).
4. **Edit** `Contributors.md` — add your name anywhere in the middle of the file.
5. **Stage and commit**: `git add Contributors.md` then `git commit -m "Add your-name to Contributors list"`.
6. **Push**: `git push -u origin your-branch-name`.
7. **Open a pull request** with the *Compare & pull request* button on GitHub.

The tutorial anticipates the two most common beginner errors and tucks fixes into expandable `<details>` blocks: the `git switch` "not a git command" error (older Git) and the post-2021 **password-authentication-removed** push error (switch the remote to SSH or use a personal access token).

> [!WARNING]
> When adding your name to `Contributors.md`, put it **somewhere in the middle** of the file — not at the very beginning or very end. Edits clustered at the file boundaries are far more likely to cause merge conflicts with other newcomers doing the same exercise at the same time.

> [!TIP]
> The exact branch name doesn't matter, but make it descriptive — the tutorial's own example is `git switch -c add-alonzo-church`. A name like `add-yourname` keeps your work easy to identify.

### 2. CLI Tool Tutorials (`docs/cli-tool-tutorials/`)

For people who want to stay in the terminal. The primary English document, [`github-cli-tutorial.md`](docs/cli-tool-tutorials/github-cli-tutorial.md), uses GitHub's official [`gh` CLI](https://cli.github.com/), which collapses several manual steps into single commands:

```bash
gh auth login                                       # authenticate once
gh repo fork firstcontributions/first-contributions # fork + clone in one step
git switch -c add-john-doe                           # create your branch
git add Contributors.md && git commit -m "Add john-doe to Contributors list"
git push origin -u your-branch-name
gh pr create --repo firstcontributions/first-contributions  # open the PR from the terminal
```

This folder also contains plain-`git` CLI variants and translations (Bengali, Kannada, Hindi, Urdu, German, Gujarati, Indonesian, Korean, Malayalam, Portuguese (BR), Sinhala, Tamil, Arabic, French, Polish) — 30 files in total.

> [!NOTE]
> The `gh repo fork` command prompts you to clone the fork at the same time — accept the "yes" option so you end up with a local copy ready to edit.

### 3. GUI Tool Tutorials (`docs/gui-tool-tutorials/`)

The same contribution workflow, retold for people who prefer a graphical interface over the command line. Each tutorial is self-contained and screenshot-heavy. Seven tools are covered:

| Tool | Tutorial file |
|------|---------------|
| GitHub Desktop | [`github-desktop-tutorial.md`](docs/gui-tool-tutorials/github-desktop-tutorial.md) (plus an older-version variant) |
| Visual Studio Code | [`github-windows-vs-code-tutorial.md`](docs/gui-tool-tutorials/github-windows-vs-code-tutorial.md) |
| GitKraken | [`gitkraken-tutorial.md`](docs/gui-tool-tutorials/gitkraken-tutorial.md) |
| Atlassian Sourcetree (macOS) | [`sourcetree-macos-tutorial.md`](docs/gui-tool-tutorials/sourcetree-macos-tutorial.md) |
| IntelliJ IDEA | [`github-windows-intellij-tutorial.md`](docs/gui-tool-tutorials/github-windows-intellij-tutorial.md) |
| Visual Studio 2017 | [`github-windows-vs2017-tutorial.md`](docs/gui-tool-tutorials/github-windows-vs2017-tutorial.md) |
| Sublime Merge | [`sublime-merge-tutorial.md`](docs/gui-tool-tutorials/sublime-merge-tutorial.md) |

Including translations, this folder holds 58 files.

> [!TIP]
> Pick the tool you already have open during your normal work. The point of this exercise is to learn the *contribution flow*, not to install a new application. If you use VS Code or an IDE daily, use that tutorial.

### 4. Additional Material — Git Workflow Scenarios (`docs/additional-material/git_workflow_scenarios/`)

Once you've made your first PR, this is where you go to learn the Git techniques you'll hit in real projects. The folder's index, [`additional-material.md`](docs/additional-material/git_workflow_scenarios/additional-material.md), assumes you've finished the basic tutorial first. Highlights:

| Scenario | When you'll need it |
|----------|---------------------|
| [Amending a commit](docs/additional-material/git_workflow_scenarios/amending-a-commit.md) | Fix a commit message or forgotten change *before* pushing. |
| [Keeping your fork synced](docs/additional-material/git_workflow_scenarios/keeping-your-fork-synced-with-this-repository.md) | Pull upstream changes into your fork so it doesn't fall behind. |
| [Resolving merge conflicts](docs/additional-material/git_workflow_scenarios/resolving-merge-conflicts.md) | Two changes touch the same lines — the classic newcomer roadblock. |
| [Squashing commits](docs/additional-material/git_workflow_scenarios/squashing-commits.md) | A reviewer asks you to combine many commits into one. |
| [Reverting a commit](docs/additional-material/git_workflow_scenarios/reverting-a-commit.md) | Undo a commit you've already pushed. |
| [Undoing a local commit](docs/additional-material/git_workflow_scenarios/undoing-a-commit.md) | Reset your local repo when you've made a mess. |
| [Stashing a file](docs/additional-material/git_workflow_scenarios/stashing-a-file.md) | Set changes aside temporarily without committing. |
| [Rebase vs. merge](docs/additional-material/git_workflow_scenarios/rebase-vs-merge.md) | Understand the two ways to integrate branches. |

The folder contains 24 documents in all, also covering configuring Git, creating a `.gitignore`, storing credentials, deleting branches, moving commits between branches, resetting branches/commits, checking the commit log, installing Git on Arch/Ubuntu, and a curated [Useful Links](docs/additional-material/git_workflow_scenarios/Useful-links-for-further-learning.md) page.

> [!CAUTION]
> Several of these scenarios — reverting, resetting, and force-related rebase/squash steps — rewrite history. Read each document fully before running the commands on a branch you care about, and prefer practicing on a throwaway branch first.

### 5. Things a Non-Programmer Can Do

[`Things a non Programmer can do.md`](docs/additional-material/Things%20a%20non%20Programmer%20can%20do.md) is a standalone essay listing **23 concrete, non-coding ways to contribute** to open source. It's organized by area:

- **Listen & engage** — join mailing lists, follow project blogs, hang out in IRC/Discord.
- **Work with tickets** — diagnose bugs, triage and close stale issues.
- **Work with code (lightly)** — test a beta, write a test, silence a compiler warning, add a clarifying comment.
- **Work with community** — answer questions, write blog posts, improve the website.
- **Work with documentation** — write or improve docs, create how-to examples.
- **Modern outreach** — accessibility audits, organizing events, curating "awesome" lists, social media, localization, UX feedback, grant writing.

> [!NOTE]
> This document reinforces a core message of the whole project: code is only one way to contribute. Documentation, triage, translation, and community-building are all genuine, valued contributions.

### 6. The "How to Contribute" Essay

[`how-to-contribute-to-open-source-projects.md`](docs/how-to-contribute-to-open-source-projects.md) is a longer-form companion that answers the *why* and the *how* at a strategic level: why contributing builds skills, portfolio, and network; how to choose the right project; why to start small (good-first-issue, documentation, tests); and how to handle common challenges like imposter syndrome and large codebases. It points back to the `README` for the hands-on practice.

---

## Contributing / Extending

The repository's own contribution rules live in [`.github/CONTRIBUTING.md`](.github/CONTRIBUTING.md). Two points stand out:

- **Suggesting workflow or tutorial changes:** [open an issue](https://github.com/firstcontributions/first-contributions/issues/new) first so the change can be discussed collectively before any code is written.
- **Translations:** when you change a translation, request a review from the existing reviewer(s) for that language (the file lists named reviewers per language). The stated goal is for every translation to carry the **same content as the English `README.md`**, except for the inter-translation language links.

> [!IMPORTANT]
> Adding your name to `Contributors.md` is the *practice exercise*, not a substantive contribution to the project. It exists so you can rehearse the pull request flow safely. Real contributions are translations, tutorial improvements, and the workflow scenarios.

For security issues, [`.github/SECURITY.md`](.github/SECURITY.md) directs you to GitHub's private "Report a vulnerability" workflow, or email `[email removed]`. The project is released under the **MIT License**.

---

## Related Resources

These resources are referenced directly from the repository's tutorials:

- **Companion web app** — [firstcontributions.github.io](https://firstcontributions.github.io/) hosts a [project list](https://firstcontributions.github.io/#project-list) of beginner-friendly repos and a [social share](https://firstcontributions.github.io/#social-share) page to celebrate your first PR.
- **More practice** — [roshanjossey/code-contributions](https://github.com/roshanjossey/code-contributions) for a code-oriented follow-up exercise.
- **Set up Git** — [GitHub's Git setup guide](https://docs.github.com/en/get-started/quickstart/set-up-git), linked from the main tutorial.
- **GitHub CLI** — [cli.github.com](https://cli.github.com/), used in the CLI tutorial.
- **SSH authentication** — [GitHub's SSH key guide](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account), referenced in the tutorial's push-error troubleshooting.

> [!TIP]
> Once your first pull request here is merged, the most valuable next step is to find a *real* project that interests you. The web app's project list is curated specifically for that hand-off.

---

_Generated June 2026 from firstcontributions/first-contributions at e63c867. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._