IntermediateLesson 11 of 307 min read

GitHub Accounts, Repositories and a Good README

Set up a home for your project, understand public versus private, and write a README and contributing note that a visitor can use.

In this lesson you will

  • Explain what GitHub adds to Git
  • Choose public or private with care
  • Write a README in Markdown
  • Know why a licence matters

About 28 minutes

A project nobody can understand

Nia puts the garden notes project online so that the other volunteers can find it. A week later Dev opens it for the first time and asks, “What is this, and what do I do with it?” The folder holds a plan, a rota and nothing else. There is no sentence anywhere that says who the project is for. The fix is a small file called the README, and today you learn to write one, and how to set up a home for your project on GitHub.

What GitHub adds to Git

Git keeps your history on your own computer. GitHub is a website that stores a copy of that history and wraps it in pages that people can browse: a front page for each project, a list of files, the history, and tools for talking about changes. The things you learned in the Beginner lessons all still apply. Remotes, push and clone are exactly how your computer talks to GitHub. What is new is everything around the code, such as issues, pull requests and published pages, which the rest of this course covers.

GitHub itself cannot be reached from the machine that builds these lessons, so the steps on the website are described as patterns. They are an outline of the usual path, and the site’s screens and wording change over time, so follow its current help pages as you go. Every Git command in this course really was run, and its output is real.

Setting up: the usual path

  1. Create an account with an email address you are happy to use in public, and choose a username carefully, because it becomes part of your project addresses.
  2. Turn on two step sign-in. GitHub strongly encourages it, and it protects everything you publish.
  3. Create a new repository. You choose a name, an optional description, and whether it is public (anyone can see it) or private (only people you invite).
  4. If your project already exists on your computer, create the new repository empty, copy its address, and connect it with git remote add origin and git push -u origin main, as in lesson 9.

Think about public versus private before you click. A public repository can be read by anyone, including its whole history and the author emails inside it. Lesson 6 explained that a committed secret stays in history, so check carefully before you publish anything. If you are unsure, start private. Features also differ by plan and by whether a repository is public or private, so check GitHub’s current pages when a feature you want seems to be missing.

The README: your project’s front door

GitHub shows the contents of a file named README.md on the front page of your project. The .md ending means Markdown, a very simple way to write headings and lists in plain text. A good README answers four questions quickly: what is this, how do I use it, how do I help, and what am I allowed to do with it.

You type It becomes
# Title A large heading
## Section A smaller heading
- item A bullet point
`code` Code in a fixed font
[words](address) A link

Here is Nia’s version, created and committed for real. The file has 15 lines, and the commit also holds a short CONTRIBUTING.md, a note that tells newcomers how to help. Notice how few commands are needed.

$ mkdir garden-notes
$ cd garden-notes
$ git init
Initialized empty Git repository in /home/nia/garden-notes/.git/
$ printf "# Garden notes\n\nPlanting plan and watering rota for our community garden.\n\n## Use it\n\nOpen plan.txt and rota.txt in any text editor.\n\n## Contribute\n\nSee CONTRIBUTING.md.\n\n## Licence\n\nTo be chosen by the club.\n" > README.md
$ printf "Beans: row 1\n" > plan.txt
$ printf "Mon: Nia\n" > rota.txt
$ printf "# Contributing\n\nOpen an issue first, then a pull request.\n" > CONTRIBUTING.md
$ git add .
$ git commit -m "Add README and contributing notes"
[main (root-commit) 4b8d5aa] Add README and contributing notes
 4 files changed, 20 insertions(+)
 create mode 100644 CONTRIBUTING.md
 create mode 100644 README.md
 create mode 100644 plan.txt
 create mode 100644 rota.txt
$ git ls-files
CONTRIBUTING.md
README.md
plan.txt
rota.txt
$ wc -l README.md
15 README.md
$ git log --stat --format="%s"
Add README and contributing notes

 CONTRIBUTING.md |  3 +++
 README.md       | 15 +++++++++++++++
 plan.txt        |  1 +
 rota.txt        |  1 +
 4 files changed, 20 insertions(+)

Checking a README with code

A README is writing, and no program can judge whether it is good. But a program can check that the basic sections exist. The checker below looks for a title, a sentence saying what the project is, a section on use, a section on contributing, and a licence section that is really filled in.

import re
text = open("/home/nia/garden-notes/README.md").read()
headings = re.findall(r"^#{1,3} (.+)$", text, re.M)
results = []
def check(name, ok):
    results.append(ok)
    print(("PASS " if ok else "FAIL ") + name)
check("has a title", text.startswith("# "))
check("says what the project is", len(text.split("\n\n")[1].split()) >= 5)
check("explains how to use it", any("use" in h.lower() for h in headings))
check("explains how to contribute", any("contribut" in h.lower() for h in headings))
placeholder = re.search(r"(?i)licen[cs]e\s*\n+(.*)", text)
check("licence section is filled in", bool(placeholder) and "to be chosen" not in placeholder.group(1).lower())
print("headings found:", len(headings))
print("checks passed:", sum(results), "of", len(results))
PASS has a title
PASS says what the project is
PASS explains how to use it
PASS explains how to contribute
FAIL licence section is filled in
headings found: 4
checks passed: 4 of 5

The README passed 4 of 5 checks. The one failure is honest: the licence heading exists, but the text under it says the club has not chosen yet. A placeholder is better than nothing, but it is not an answer.

Choosing a licence

A licence is a short statement of what other people may do with your work. Without one, the default rules of copyright usually apply, which in many places means others may look but have no clear permission to reuse or change your work. Many open projects pick a well known licence so that everyone understands the terms at a glance. GitHub’s help pages explain the common choices. This is an outline, not legal advice, and a club or a business should get proper advice before deciding.

Common mistake: an empty front door

Publishing a project with no README and no licence, then wondering why nobody uses it. Visitors decide in seconds, and the front page is all they see.

Patterns, not screens

The project, names and README text are made up, and the checker is a simple sketch of the idea. Account steps, screens, plan features and wording on GitHub change over time, so confirm them on the site. Nothing here is legal advice.

Write a README for one of your own projects with a title, one sentence about it, how to use it, how to help, and a licence line. Then run the checker idea by eye and see what is missing.

Practice for this lesson

Check what you learned

Five quick questions. Pick an answer and you will see straight away whether it is right and why.

What does GitHub add to Git?

  1. A replacement for commits
  2. A website that stores your project and adds tools for working with others
  3. A text editor
  4. A faster computer

Push and clone connect to it; issues and pull requests come next.

Which file is shown on the front page of a project?

  1. plan.txt
  2. config
  3. notes.log
  4. README.md

The README is displayed automatically.

What does Markdown use ## for?

  1. A smaller heading
  2. A bullet point
  3. A link
  4. A comment

One hash is a title and two hashes make a section heading.

Why think before making a repository public?

  1. Public repositories cost money
  2. Public repositories cannot be edited
  3. Anyone can read its files, its history and author emails
  4. Git forbids it

A committed secret stays in history, even in a public project.

Why did the README checker fail the licence check?

  1. The section was missing
  2. The file was empty
  3. The title was missing
  4. The section existed but still said it was to be chosen

A placeholder is not a decision.

Summary

  • GitHub is a website around your Git history; the push and clone commands are the same.
  • Decide public or private before you publish, and check for secrets first.
  • A README answers: what is it, how to use it, how to help, what is allowed.
  • A licence states what others may do; it is an outline here, not legal advice.

Next lesson

Lesson 12 uses issues to track work and link it to commits.

Questions

Do I need to pay to use GitHub?

GitHub has a free plan, and features differ between plans and between public and private repositories. Check its current plans page, because details change.

Can I change a repository from public to private later?

Usually yes through its settings, but copies that other people already made stay with them. Treat publishing as hard to undo.

Do I have to write the README in Markdown?

Markdown is the usual choice because GitHub displays it nicely. Plain text works too, but it will not have headings or links.

Progress is saved in this browser.