Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 36 ยท Projects and Practice

Project: Set Up an Open-Source Repository

Turn a bare repository into a welcoming open-source project: README, license, CONTRIBUTING, code of conduct, issue and PR templates, labels, security policy and a health checker.

A repository with code but nothing else is hard to adopt and harder to contribute to. Visitors decide within seconds whether a project is alive, safe and friendly. In this project you will add the files and settings that make a repository ready for other people, using the features from the earlier chapters.

Everything here is configuration, so the file examples are read-only. The stand-in at the end is a health checker that audits a list of file names, the way GitHub's Community Standards page does.

The checklist at a glance

Item File or setting
Explain the project README.md
Say how it may be used LICENSE
Explain how to contribute CONTRIBUTING.md
Set behavior expectations CODE_OF_CONDUCT.md
Standardize reports issue forms, pull request template
Make security reporting private SECURITY.md, private vulnerability reporting
Automate quality CI workflow, Dependabot, code scanning
Organize triage labels, CODEOWNERS, milestones
Help discovery description, topics, social preview

README.md

The README is your front door, rendered under the file list. Cover, in this order: what the project is in one sentence, why it exists, a short quick start (install and one usage example that works when copied), links to docs, how to contribute, and the license. Add a few badges at the top (CI status, version, license) using the workflow badge Markdown from the Actions tab:

MARKDOWN
# octo-lib

Tiny, dependency-free helpers for parsing release notes.

[![CI](https://github.com/OWNER/octo-lib/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/octo-lib/actions/workflows/ci.yml)

## Quick start

    npm install octo-lib

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Be kind: [Code of Conduct](CODE_OF_CONDUCT.md).

Put a README.md in .github/ or docs/ if you prefer; GitHub picks the first it finds (.github, then root, then docs).

LICENSE

Without a license, the default is "all rights reserved": nobody may legally use your code, however public it is. Pick a license on purpose. MIT and Apache-2.0 are permissive (reuse allowed, even in closed-source products; Apache adds an explicit patent grant). GPL-3.0 is copyleft: derivative works must stay open under the same terms. GitHub's Add file -> Create new file shows a license picker when you type LICENSE, filling in the text. Choose before accepting outside contributions, since changing it later needs everyone's agreement. (This is general information, not legal advice.)

CONTRIBUTING and the code of conduct

CONTRIBUTING.md answers the questions every newcomer has: how to set up the project, how to run tests, the branch and commit conventions, how to propose big changes (open an issue first), how reviews work and how long to wait. GitHub links it when someone opens an issue or pull request. A CODE_OF_CONDUCT.md (the Contributor Covenant is a common starting text) states expected behavior and how to report violations; name a real contact.

Issue forms and templates

Free-text issues arrive without versions, steps or logs. Issue forms are structured YAML templates under .github/ISSUE_TEMPLATE/:

YAML
# .github/ISSUE_TEMPLATE/bug.yml
name: Bug report
description: Something does not work as documented
labels: ["bug", "needs-triage"]
body:
  - type: markdown
    attributes:
      value: "Thanks for reporting! Please search existing issues first."
  - type: input
    id: version
    attributes:
      label: Version
      placeholder: "1.4.0"
    validations:
      required: true
  - type: textarea
    id: steps
    attributes:
      label: Steps to reproduce
    validations:
      required: true
  - type: dropdown
    id: os
    attributes:
      label: Operating system
      options: [Linux, macOS, Windows]

A config.yml next to it can disable blank issues and add contact links, for example pointing questions to Discussions:

YAML
blank_issues_enabled: false
contact_links:
  - name: Ask a question
    url: https://github.com/OWNER/octo-lib/discussions
    about: Usage questions belong in Discussions

For pull requests, a .github/pull_request_template.md pre-fills the description with a checklist (what changed, how it was tested, linked issue such as Closes #123, docs updated).

Security and automation

Add SECURITY.md with the private reporting channel and switch on private vulnerability reporting. Then enable Dependabot alerts and updates, code scanning and secret scanning with push protection, and the CI pipeline. Protect main with a ruleset requiring a pull request, the CI gate and review from CODEOWNERS.

Labels, milestones and discovery

Create a small, consistent set of labels: bug, enhancement, documentation, good first issue, help wanted, question, wontfix, plus a few area labels. good first issue is special: GitHub surfaces those issues to newcomers searching for ways to contribute. Group planned work with milestones (v1.5). Fill in the repository description, website and topics (such as javascript, parser), upload a social preview image, and pin the repository to your profile.

Community profile and funding

Under Insights -> Community Standards, GitHub shows a checklist (description, README, code of conduct, contributing, license, security policy, issue templates, pull request template) and which items are still missing. A .github/FUNDING.yml adds a Sponsor button:

YAML
github: [mona]
open_collective: octo-lib

If you own several repositories, put the shared files (code of conduct, contributing, issue forms) in a public repository named .github in your account or organization; they become the default for every repository that lacks its own.

A stand-in: community health checker

The checker below mirrors the idea of the Community Standards page. Give it the list of paths in a repository and it reports what is missing. It is our own simplified helper, not GitHub's implementation.

JS Stand-in: repository health checker (simplified)

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Add the missing paths to repoFiles and watch the score reach 100%.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does an unlicensed public repository mean legally, by default?

    Without a license, copyright law's default applies, so you must choose a license to allow reuse.
  2. 2. Where do issue forms live?

    Issue forms are YAML templates inside .github/ISSUE_TEMPLATE/.
  3. 3. How can one set of community files apply to all your repositories?

    A .github repository provides defaults for repositories without their own files.
  4. 4. Which label helps newcomers find a way to contribute?

    GitHub highlights issues labeled good first issue to people looking to contribute.

Summary

  • A ready repository has a README, an intentional license, contributing and conduct documents, security policy and templates.
  • Issue forms and PR templates collect complete information; labels and milestones organize triage.
  • Automation (CI, Dependabot, scanning, rulesets, CODEOWNERS) keeps quality up without heroics.
  • Use the Community Standards page and a shared .github repository to stay consistent across projects.

Next: Project: Automated Release Pipeline