5.2 Repository Maintenance and Collaboration Best Practices

Why GH-900 tests maintenance habits

The same Domain 2 slice that covers Insights also asks you to recognize best practices for repository maintenance and collaboration. GitHub's own “Best practices for repositories” page is short on purpose: ship a README, secure the repository, favor branching over forking for people who already collaborate, and use Git Large File Storage (Git LFS) instead of stuffing binaries into Git. GH-900 expands that list with default-branch protection (high level), LICENSE and other community files, archive versus delete, topics, releases and tags, keeping secrets out of Git, keeping the default branch green, CODEOWNERS, templates, and deleting stale branches.

Think of maintenance as the difference between a repository people can trust and a dump of files. A green default branch, a license, and a security contact do more for collaboration than another Insights chart.

Make the landing page honest: README, LICENSE, community files

GitHub recommends a README in every repository so people can understand and navigate the work. A README is often the first thing a visitor sees. Typical contents: what the project does, why it is useful, how to get started, where to get help, and who maintains it. GitHub auto-surfaces a README from .github/, the repository root, or docs/, in that order if more than one exists. Rendered README content beyond 500 KiB is truncated. Pair the README with a LICENSE so others know whether they may use, modify, and redistribute the code. A public repo without a license is not “public domain”; it is an unclear legal situation, which is why community profiles flag a missing LICENSE.

Community health files turn a repo from “code exists” into “contributions are welcome.” GitHub's community profile checklist for public repositories looks for recommended files in supported locations: README, CODE_OF_CONDUCT, LICENSE, CONTRIBUTING, a SECURITY.md security policy, and issue templates. Issue templates must live in .github/ISSUE_TEMPLATE and include valid name: / about: keys (Markdown templates) or name: / description: keys (YAML issue forms) to count as added. Pull request templates belong in the same community-health family: they ask contributors for test plans and linked issues instead of an empty PR body. Maintainers can click Add on a missing checklist item; outside contributors can click Propose. Domain 2.1 already named these files; D2.5 asks you to use them as ongoing hygiene, not one-time scaffolding.

Protect the default branch and keep it green

GitHub's branching advice for regular collaborators is: one repository, pull requests between branches, and protected branches with required status checks and pull request reviews on important branches such as main. Protected branches exist to stop accidental (or hostile) history edits on the line of development everyone depends on. By default a protection rule blocks force pushes and blocks deletion of matching branches. Optional settings GH-900 expects at a high level include:

• Require pull request reviews before merging, optionally from code owners.
• Require status checks before merging, so CI must be successful, skipped, or neutral.
• Require conversation resolution so review comments are handled.
• Do not allow bypassing so even admins follow the rule.

“Keep the default branch green” means you do not merge until required checks pass and required reviews are in. A red build on main blocks every downstream clone, fork, and release. Strict required checks also demand that the head branch is up to date with the base before merge; loose checks do not, which is faster but can land incompatible changes. Full ruleset versus classic protection-rule mechanics, admin bypass lists, and org policy live in Domain 6—here you only need the collaboration practice: protect main, require a reviewed pull request, require the checks that prove the branch is healthy.

Plan trap: on private repositories, required reviewers, multiple reviewers, protected branches, and code owners are advanced tools on GitHub Pro, GitHub Team, and GitHub Enterprise. Public repositories on GitHub Free include a much fuller feature set. If a scenario is a private repo on Free and the owner wants required reviews, the blocker is the plan—not a missing CODEOWNERS file.

CODEOWNERS, templates, and a branching workflow

A CODEOWNERS file names individuals or teams who own paths. Owners must have write permission (teams must be visible and also have write). GitHub automatically requests those owners on pull requests that touch their files. Draft pull requests do not auto-request code owners; marking the draft ready for review does. Place the file in .github/, the repository root, or docs/ of the branch you care about. If files exist in more than one of those locations, GitHub searches .github/, then root, then docs/ and uses the first it finds. Last matching pattern wins inside the file. The file must stay under 3 MB or GitHub will not load it. “Require review from Code Owners” on a protection rule means any one listed owner of the changed path can satisfy the requirement—not every owner. CODEOWNERS is not a substitute for write permission, and it is not a star list.

Issue and pull request templates keep incoming work structured. Regular collaborators should not fork the product repository for every feature; they clone, branch, open a PR, merge, and delete the feature branch. GitHub Flow's last step is housekeeping: leftover branches confuse CODEOWNERS reviews, stale-check runs, and the network graph. Use Git LFS for large binaries because GitHub limits file sizes in ordinary Git storage.

Secrets, topics, releases, archive versus delete

Never commit secrets

GitHub's security baseline for public repositories (free) is: enable Dependabot alerts, secret scanning, push protection, and code scanning. For D2.5 you need the collaboration rule, not the Advanced Security SKU list: do not commit API keys, tokens, certificates, or passwords, even to a private repository. History is copied on every clone and every fork. Secret scanning alerts after a supported secret lands; push protection blocks the push so the secret never enters the default branch. If something leaks, rotate the credential—deleting the file in a later commit does not erase it from history. Add SECURITY.md so researchers know how to report issues, and consider private vulnerability reporting. Deep configuration, org security overview, and GitHub Secret Protection packaging belong to Domain 6; the maintenance exam answer is “don’t put secrets in Git, and turn on the free public-repo guards that stop you if you try.”

Topics make the repository discoverable

Topics are labels on the repository About box: purpose, subject, language, community. Admins can add any topic they want. Public repository content can receive suggested topics; private content is not analyzed for suggestions. You may attach topics to public and private repositories, but topic search only shows private repos you can access. Hard limits: lowercase letters, numbers, and hyphens; 50 characters or fewer; no more than 20 topics. The exam-grade trap: topic names are always public, even when you create the topic from a private repository. Do not put an internal product codename in a topic if that name is confidential.

Releases and tags package a point in history

Releases are deployable iterations you package with notes and binaries. They are based on Git tags, which mark a specific commit. A tag’s date can differ from the release date because you can tag now and publish the GitHub Release later. Anyone with read access can view and compare releases; write permission is required to manage them. GitHub always attaches a zip and a tarball of the repository at that tag. Up to 1,000 release assets may attach to a single release; each file must be under 2 GiB; GitHub documents no total size or bandwidth cap for releases. Optional automatically generated release notes keep the changelog honest. Releases are how you tell users “use this snapshot,” which is different from starring (bookmark) and different from protecting main (quality gate).

Archive when the project is finished; delete only when you mean it

Archiving makes the repository read-only and signals that it is no longer maintained. GitHub recommends closing issues and pull requests and updating the README and description first. After archive you cannot add or remove collaborators or teams. People who still have access may fork or star the project. Issues, pull requests, code, labels, milestones, projects, wiki, releases, commits, tags, branches, comments, and permissions all freeze. Unarchive to make changes again. Archived repos remain searchable. Archiving an organization archives all of its repositories. Customers on a legacy per-repository billing plan are still charged for archived repos until they upgrade plans. Secret scanning can still run on archived repos if GitHub Secret Protection is in play—another reminder that archive is not delete.

Deleting a repository is a Danger Zone action for owners/admins (org or enterprise policy may block it). Deleting permanently drops team permissions; GitHub says that cannot be undone. Deleting a public repository does not delete forks; those forks remain. Deleting a private repository deletes all forks of that private repo. Some deleted repositories can be restored within 90 days. If the goal is “this project is finished but the code should stay readable and public forks should survive,” archive. If the goal is “wipe this private experiment and its private forks,” delete—and understand the 90-day restore window is a safety net, not a workflow.

Exam traps for D2.5

• Forking is not the default for teammates. Branch in one repo; fork for outsiders.
• Private-repo protections are often paid. Public Free ≠ private Free.
• CODEOWNERS last-match-wins, search order .github/ → root → docs/, write access required, drafts do not auto-request owners.
• Topic names are public even on private repositories.
• Archive ≠ delete. Archive is reversible read-only; delete of a private repo destroys forks; public delete leaves forks; 90-day restore may apply.
• Releases wrap tags; tags are Git objects, not a substitute for a LICENSE.
• Green default branch means required checks and reviews, not “someone starred it.”
• Secrets in Git are a maintenance failure, even in private repos.