Making a repository easy to review

A hiring manager may give your project a couple of minutes, by the estimate in GitHub’s own tutorial for job seekers, and the first screen of its repository decides how they spend them: the About box, the file list and the README under it. A repository that answers what the project is, how to run it and how it is tested on that screen earns the rest of the reader’s time.

This lesson cleans up the canteen queue tracker’s repository: its first screen, the signs of care a reader looks for, and what must never be in a repository you share.

The first screen decides what a reader does next

GitHub’s tutorial names three repository details that help a hiring manager understand a project quickly: a brief description, a website where the project can be seen in action, and topic tags. They sit in the About box beside the file list, and the README appears under the files. Step through the canteen tracker’s first screen, as it was and after the clean-up:

The clean-up changed no code. Every step from the fifth on fixed something the reader sees before opening a single file, and the README went from two words to the four parts GitHub’s tutorial lists: the key features, how to set up and run the project, an example or a demo, and how to test it.

Topicstopics: Tags on a GitHub repository that say what it is about or what it uses, written in lowercase letters, numbers and hyphens. They appear on the repository's main page. have rules of their own. GitHub accepts lowercase letters, numbers and hyphens, at most 50 characters for each topic and no more than 20 topics, which is why “Flask” and “college project” could not be added as written. You edit the description, the website and the topics from the gear icon beside About on the repository’s main page.

Seven signals a reader can see, before and after

The first screen can show seven signals in all: the three About details, a README in four parts, tests, a workflow that runs them, which is continuous integrationcontinuous integration: Running a project's tests automatically on every change pushed to its repository, usually with a workflow file, so that a change that breaks them shows at once. or CI, and a licence. The program checks the canteen tracker’s repository for each, as it was and after the clean-up:

# Checks the seven things the first screen of a repository can show a reader, for the canteen queue tracker before and
# after a clean-up: the About details GitHub's tutorial for job seekers asks for (a description, a website, topics),
# GitHub's rules for topics (lowercase letters, numbers and hyphens, at most 50 characters each, at most 20), the four
# parts of a helpful README in that tutorial (features, how to set up and run, a demo, how to test), tests, a CI
# workflow and a licence. The repository is invented. Press Edit, describe your own repository in MINE, and run it.
import re

BEFORE = {
    "description": "",
    "website": "",
    "topics": ["Flask", "college project", "queue"],
    "files": ["app.py", "canteen/queue.py", "tests/test_queue.py", "requirements.txt", "README.md"],
    "readme": "# canteen\n\nour project\n",
}
AFTER = {
    "description": "A token queue for a college canteen: students take a numbered token and wait seated until it is called",
    "website": "https://canteen-queue-example.onrender.com/",
    "topics": ["flask", "sqlite", "queue", "python", "student-project"],
    "files": ["app.py", "canteen/queue.py", "tests/test_queue.py", "requirements.txt", "README.md", "LICENSE",
              ".github/workflows/tests.yml"],
    "readme": "# Canteen queue tracker\n\n## Features\n\n## Set up and run\n\n## Demo\n\n## Run the tests\n",
}
MINE = None  # your own repository, in the same shape
README_PARTS = {"features": ("feature",), "setup and run": ("set up", "setup", "install", "run"),
                "demo": ("demo", "example"), "tests": ("test",)}
TOPIC = re.compile(r"[a-z0-9-]{1,50}")


def signals(repo):
    headings = [h.lower() for h in re.findall(r"^##+ (.+)$", repo["readme"], flags=re.M)]
    readme_parts = [part for part, words in README_PARTS.items() if any(w in h for h in headings for w in words)]
    return {
        "a description": bool(repo["description"].strip()),
        "a website": repo["website"].startswith("https://"),
        "valid topics": 0 < len(repo["topics"]) <= 20 and all(TOPIC.fullmatch(t) for t in repo["topics"]),
        "a README in four parts": len(readme_parts) == len(README_PARTS),
        "tests": any(f.startswith("tests/") or re.search(r"(^|/)test_\w+\.py$", f) for f in repo["files"]),
        "a CI workflow": any(f.startswith(".github/workflows/") for f in repo["files"]),
        "a licence": any(f.split("/")[-1] in ("LICENSE", "LICENSE.md", "LICENCE") for f in repo["files"]),
    }


for name, repo in [("before", BEFORE), ("after", AFTER)] + ([("mine", MINE)] if MINE else []):
    found = signals(repo)
    print(f"{name}: {sum(found.values())} of {len(found)} signals")
    print(f"  missing: {', '.join(s for s, ok in found.items() if not ok) or 'nothing'}")
    bad = [t for t in repo["topics"] if not TOPIC.fullmatch(t)]
    if bad:
        print(f"  topics GitHub will not accept: {bad}")

before: 1 of 7 signals
  missing: a description, a website, valid topics, a README in four parts, a CI workflow, a licence
  topics GitHub will not accept: ['Flask', 'college project']
after: 7 of 7 signals
  missing: nothing

Before, the repository showed one signal of seven, its tests folder. After, it shows all seven, and nothing in the code changed: the work was a sentence, a link, five topics, a README, a workflow file and a licence.

Three more things decide whether a repository is ready to share, and each needs a check of its own. A README follows rules on GitHub beyond its four parts, such as which copy is shown and how much of it. A repository must hold no secrets, no very large files and no generated clutter, such as cache folders, in any commit of its history. And each sign of care, from tests to a licence, tells a reader something specific about how you work.

A README GitHub shows the way you meant, with a preview image Pro: opens with a Pro, Premium or Ultimate pass

Secrets, large files and clutter, found and fixed before you share Pro: opens with a Pro, Premium or Ultimate pass

Tests, CI, dependencies and a licence: what each tells a reader Pro: opens with a Pro, Premium or Ultimate pass

Practise: clean up a repository’s first screen

Arjun’s library seat booker has a repository whose first screen says almost nothing. Fix it from his records; the sample tests check the description, the website, the topics, the README’s four parts, and the tests, workflow and licence in its files:

# Arjun's repository as a reader first sees it. Fix it from his records in the prompt.
REPO = {
    "description": "",
    "website": "http://seat-booker-example.vercel.app/",
    "topics": ["Django", "Library Management", "postgres"],
    "files": ["manage.py", "booker/models.py", "booker/views.py", "tests/test_booking.py", "requirements.txt",
              "README.md"],
    "readme": "# seat-booker\n\nDjango project.\n",
}

import re

from repo import REPO

TOPIC = re.compile(r"[a-z0-9-]{1,50}")
README_PARTS = {"features": ("feature",), "setting up and running": ("set up", "setup", "install", "run"),
                "a demo": ("demo", "example"), "the tests": ("test",)}


def test_description_and_website():
    """gives a one-sentence description and an https website"""
    description = REPO["description"].strip()
    assert description, "write a description: what the project is, in one sentence"
    assert len(description) <= 160, f"the description has {len(description)} characters: at most 160"
    assert REPO["website"].startswith("https://"), "the website should start with https://"


def test_topics_github_accepts():
    """has three to six topics that GitHub accepts"""
    topics = REPO["topics"]
    assert 3 <= len(topics) <= 6, f"{len(topics)} topics: give three to six"
    bad = [t for t in topics if not TOPIC.fullmatch(t)]
    assert not bad, f"GitHub accepts only lowercase letters, numbers and hyphens: {bad}"


def test_readme_in_four_parts():
    """has a README whose headings cover features, setup and run, a demo and the tests"""
    headings = [h.lower() for h in re.findall(r"^## (.+)$", REPO["readme"], flags=re.M)]
    missing = [part for part, words in README_PARTS.items() if not any(w in h for h in headings for w in words)]
    assert not missing, f"the README has no heading for: {missing}"


def test_tests_workflow_and_licence():
    """shows tests, a workflow that runs them and a licence in its files"""
    files = REPO["files"]
    assert any(f.startswith("tests/") for f in files), "keep the tests folder"
    assert any(re.fullmatch(r"\.github/workflows/[\w.-]+\.ya?ml", f) for f in files), "add a workflow file under .github/workflows/"
    assert "LICENSE" in files, "add a LICENSE file"

Then answer questions on the first screen and its seven signals, starting with the idea you have answered worst so far:

Interview questions

Warm-up (fresher to mid-level): What does a reader look at first when they open your repository?

The first screen: the About box, the file list and the README under it. The About box should say in one sentence what the project is, link a place where it runs and carry a few topics. The file list shows at a glance whether there are tests, a workflow that runs them and a licence. The README should list what the project can do, give the commands that install and start it, link a demo and give the command that runs the tests. If those answer what it is, how to run it and how it is tested, the reader spends the rest of their time on the code.

Three questions of this module’s bank go further:

Key takeaways

• A reader decides from the first screen: the About box with a description, a website and topics, and a README in four parts under the file list.
• Topics take lowercase letters, numbers and hyphens, at most 50 characters each and no more than 20.
• Seven signals can show before any code is read: the three About details, the README, tests, CI and a licence.