# GitHub Repository Best Practices

### A Professional Standards Guide for Clean, Maintainable Repositories

> **Audience:** Individual contributors, team leads, and open-source maintainers — especially those building in the Algorand ecosystem.
> **Goal:** Establish a reproducible, professional-grade repository standard from day one.
> **Platform:** [AlgoScan](https://algoscan.dev) surfaces repository signals directly — a clean, well-maintained repo is more visible, trusted, and impactful in the ecosystem.

_"Public code is public trust." — The foundation of open source and the ethos behind AlgoScan_

---

## Why This Matters

Maintaining a well-structured and consistently updated repository is not just good practice — it is essential to maximising visibility, collaboration, auditability, and long-term sustainability.

| Repository Signal | Impact                                                                             |
| ----------------- | ---------------------------------------------------------------------------------- |
| Clean commits     | Self-documenting history; AlgoScan uses commit frequency to gauge project activity |
| Semantic releases | Enables version-based timeline views and milestone tracking                        |
| Populated README  | Parsed by AlgoScan for instant project context; boosts contributor onboarding      |
| CI/CD workflows   | Signals active development; inferred from `.github/workflows/` presence            |
| Branch hygiene    | Clean graph analysis and accurate contributor mapping                              |

---

## Table of Contents

1. [Repository Initialization](#1-repository-initialization)
2. [README — Your Repo's Front Door](#2-readme--your-repos-front-door)
3. [Branch Strategy](#3-branch-strategy)
4. [Commit Conventions](#4-commit-conventions)
5. [Pull Requests & Code Review](#5-pull-requests--code-review)
6. [Issue & Project Management](#6-issue--project-management)
7. [GitHub Actions — CI/CD](#7-github-actions--cicd)
8. [Security Practices](#8-security-practices)
9. [Documentation Standards](#9-documentation-standards)
10. [Repository Hygiene & Maintenance](#10-repository-hygiene--maintenance)
11. [Community & Open Source Health Files](#11-community--open-source-health-files)
12. [Recommended Tools & Integrations](#12-recommended-tools--integrations)
13. [Quick Reference Checklist](#13-quick-reference-checklist)
14. [Key References](#14-key-references)

---

## 1. Repository Initialization

**Set up structure before the first meaningful commit.**

### Essential files at root level

```
/
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.yml
│   │   └── feature_request.yml
│   ├── PULL_REQUEST_TEMPLATE.md
│   ├── workflows/
│   │   ├── ci.yml
│   │   └── codeql.yml
│   ├── dependabot.yml
│   ├── CODEOWNERS
│   └── FUNDING.yml
├── docs/
│   └── adr/
├── src/
├── tests/
├── .gitignore
├── .editorconfig
├── LICENSE
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
└── SECURITY.md
```

### `.gitignore`

Never commit secrets, build artifacts, or OS/IDE-specific files.

- Generator: [gitignore.io](https://www.toptal.com/developers/gitignore)
- GitHub's built-in templates are available at repository creation.

📖 [GitHub — Ignoring files](https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files)

### `LICENSE`

Choose a license **before publishing**. No license = all rights reserved by default.

- Interactive selector: [choosealicense.com](https://choosealicense.com/)
- Common choices: MIT (permissive), Apache-2.0 (permissive + patent grant), GPL-3.0 (copyleft)

📖 [GitHub — Licensing a repository](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository)

### `.editorconfig`

Enforce consistent indentation, line endings, and encoding across all editors and IDEs.

📖 [editorconfig.org](https://editorconfig.org/)

---

## 2. README — Your Repo's Front Door

**The README is the single most important file in your repository.**

### Minimum required sections

```markdown
# Project Name

> One-line description — what it does and why it matters.

## Badges

![CI](https://github.com/org/repo/actions/workflows/ci.yml/badge.svg)
![License](https://img.shields.io/github/license/org/repo)
![Version](https://img.shields.io/github/v/release/org/repo)
![Coverage](https://codecov.io/gh/org/repo/branch/main/graph/badge.svg)

## Overview / Features

## Requirements / Prerequisites

## Installation

## Usage (with code examples)

## Configuration

## Contributing

## License

## Acknowledgements
```

### Rules

- Write for a **new user with zero context** — assume nothing.
- Keep installation steps **copy-pasteable** — test them yourself on a clean machine.
- Add **badges** for CI status, coverage, license, and version. Source: [shields.io](https://shields.io/)
- Use **screenshots or GIFs** for UI projects. Tools: [LICEcap](https://www.cockos.com/licecap/), [Kap](https://getkap.co/), or [peek](https://github.com/phw/peek)
- For Algorand projects, link to your [AlgoScan project page](https://algoscan.dev) for live ecosystem stats.

📖 [GitHub — About READMEs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes)
📖 [Make a README — best practices guide](https://www.makeareadme.com/)
📖 [Awesome README — curated examples](https://github.com/matiassingers/awesome-readme)

---

## 3. Branch Strategy

**Consistency in branching = predictable releases and safe collaboration.**

### Recommended: GitHub Flow (most teams)

```
main  ←  feature/xxx  (short-lived, PR-merged)
         fix/yyy
         chore/zzz
         docs/aaa
```

> Simple, CI-friendly, and continuous-delivery oriented.
> 📖 [GitHub Flow](https://docs.github.com/en/get-started/using-github/github-flow)

### When to use Git Flow instead

For versioned software with scheduled releases (libraries, firmware, SDKs).
📖 [Atlassian — Gitflow Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)

### Branch naming conventions

| Type    | Pattern                 | Example                  |
| ------- | ----------------------- | ------------------------ |
| Feature | `feature/<ticket>-slug` | `feature/42-user-auth`   |
| Bug fix | `fix/<ticket>-slug`     | `fix/87-login-crash`     |
| Hotfix  | `hotfix/<ticket>-slug`  | `hotfix/91-null-pointer` |
| Chore   | `chore/slug`            | `chore/update-deps`      |
| Docs    | `docs/slug`             | `docs/api-reference`     |
| Release | `release/v<x.y.z>`      | `release/v2.1.0`         |

### Branch protection rules (mandatory for `main`)

Enable all of these in **Settings → Branches → Branch protection rules**:

- ✅ Require pull request before merging
- ✅ Require status checks to pass before merging
- ✅ Require at least 1 (preferably 2) approvals
- ✅ Dismiss stale reviews when new commits are pushed
- ✅ Restrict who can push to matching branches
- ✅ Do not allow force pushes

📖 [GitHub — About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches)

---

## 4. Commit Conventions

**A clean commit history is self-documenting code archaeology.**

### Use Conventional Commits

```
<type>(<scope>): <short summary>

[optional body — explain WHY, not WHAT]

[optional footer: BREAKING CHANGE: …, Fixes #xxx, Co-authored-by: …]
```

**Allowed types:**

| Type       | Use for                                    |
| ---------- | ------------------------------------------ |
| `feat`     | New feature for the user                   |
| `fix`      | Bug fix for the user                       |
| `docs`     | Documentation changes only                 |
| `style`    | Formatting, no logic change                |
| `refactor` | Code restructuring, no feature/fix         |
| `test`     | Adding or updating tests                   |
| `chore`    | Build process, tooling, dependency updates |
| `perf`     | Performance improvement                    |
| `ci`       | CI/CD configuration changes                |
| `revert`   | Reverting a previous commit                |

**Examples:**

```
feat(auth): add OAuth2 login via GitHub
fix(api): handle null response from payment gateway
docs(readme): update installation steps for Windows
chore(deps): bump lodash from 4.17.20 to 4.17.21
feat!: redesign public API — BREAKING CHANGE
```

### Rules

- **Subject line ≤ 72 characters**
- Use **imperative mood**: "add feature" not "added feature"
- Reference issues in footer: `Fixes #42`, `Closes #87`
- **One logical change per commit** — never bundle unrelated changes
- Avoid vague subjects: `update`, `fix stuff`, `WIP`, `misc`

📖 [Conventional Commits Specification](https://www.conventionalcommits.org/)
📖 [Writing good commit messages — Erlang/OTP wiki](https://github.com/erlang/otp/wiki/writing-good-commit-messages)

### Enforce with tooling

| Tool           | Purpose              | Link                                                                         |
| -------------- | -------------------- | ---------------------------------------------------------------------------- |
| **commitlint** | Lint commit messages | [commitlint.js.org](https://commitlint.js.org/)                              |
| **Husky**      | Git hook runner      | [typicode.github.io/husky](https://typicode.github.io/husky/)                |
| **Commitizen** | Interactive CLI      | [commitizen-tools.github.io](https://commitizen-tools.github.io/commitizen/) |

---

## 5. Pull Requests & Code Review

**PRs are the highest-leverage communication and quality-control point in a codebase.**

### PR Template (`.github/PULL_REQUEST_TEMPLATE.md`)

```markdown
## Summary

<!-- What does this PR do? Why is it needed? Link to relevant issue. -->

## Type of change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## How has this been tested?

<!-- Describe tests added/run. Include environment details if relevant. -->

## Checklist

- [ ] My code follows the project style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have added/updated tests that prove my fix is effective or that my feature works
- [ ] I have updated the documentation accordingly
- [ ] No new warnings are introduced
- [ ] Linked to related issue(s): Fixes #
```

### PR best practices

| Practice                                | Rationale                             |
| --------------------------------------- | ------------------------------------- |
| Keep PRs small (< 400 lines)            | Easier to review, faster to merge     |
| One concern per PR                      | Reduces cognitive load for reviewers  |
| Self-review before requesting review    | Catch obvious issues before others do |
| Screenshots/recordings for UI changes   | Reviewers can validate visually       |
| Draft PRs for early feedback            | Signal WIP; share direction early     |
| Never merge your own PR (team projects) | Mandatory second set of eyes          |

### Code review etiquette

- Comment on **code, not the author** — "this function" not "you wrote"
- Use **prefixes** to signal intent: `nit:`, `question:`, `blocker:`, `suggestion:`, `praise:`
- Approve **explicitly** when satisfied — don't silently stop commenting
- Resolve your own comments after addressing them
- Keep reviews timely — aim for < 24h on open PRs

📖 [GitHub — About pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
📖 [Google Engineering Practices — Code Review Guide](https://google.github.io/eng-practices/review/)

### `CODEOWNERS`

Auto-assign reviewers based on path ownership. Place at `.github/CODEOWNERS`.

```
# Global fallback
*                   @org/core-team

# Documentation
/docs/              @org/tech-writers

# Backend API
/src/api/           @org/backend-team

# Infrastructure
*.tf                @org/infra-team
*.yml               @org/devops-team
```

📖 [GitHub — About code owners](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)

---

## 6. Issue & Project Management

### Issue Templates

Create YAML-based form templates under `.github/ISSUE_TEMPLATE/` for consistent, actionable reports.

- `bug_report.yml` — Steps to reproduce, expected vs. actual, environment details, logs
- `feature_request.yml` — Problem statement, proposed solution, alternatives considered
- `question.yml` — Or configure to redirect to GitHub Discussions

📖 [GitHub — Configuring issue templates](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository)

### Labeling strategy

Maintain a consistent label taxonomy across all repos:

| Category     | Examples                                                 |
| ------------ | -------------------------------------------------------- |
| **Type**     | `bug`, `feature`, `docs`, `chore`, `security`            |
| **Priority** | `p0-critical`, `p1-high`, `p2-medium`, `p3-low`          |
| **Status**   | `needs-triage`, `in-progress`, `blocked`, `wont-fix`     |
| **Size**     | `size/xs`, `size/s`, `size/m`, `size/l`, `size/xl`       |
| **Area**     | `area/frontend`, `area/backend`, `area/infra`, `area/ci` |

Sync labels programmatically: [github-label-sync](https://github.com/nicedoc/github-label-sync)

### GitHub Projects

Use **GitHub Projects (V2)** for roadmap, sprint, and backlog management with custom fields and board views.
📖 [GitHub Projects documentation](https://docs.github.com/en/issues/planning-and-tracking-with-projects)

### Milestones

Group issues and PRs into versioned milestones (`v1.0`, `v2.0`). Use them to track release readiness and velocity.

---

## 7. GitHub Actions — CI/CD

**Automate everything repeatable. If you do it twice manually, it should be a workflow.**

### Minimal CI workflow — lint, test, build on every PR

```yaml
# .github/workflows/ci.yml
name: CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [20, 22]
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.3.0
        with:
          node-version: ${{ matrix.node-version }}
          cache: npm
      - run: npm ci
      - run: npm run lint
      - run: npm test -- --coverage
      - uses: codecov/codecov-action@84508a3e8796f03e33c19f23cf10ad0f3fe2e9de # v4.6.0
```

### Dependabot configuration

```yaml
# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: npm
    directory: /
    schedule:
      interval: weekly
    labels:
      - chore
      - dependencies
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly
```

📖 [GitHub Actions documentation](https://docs.github.com/en/actions)
📖 [GitHub — Dependabot](https://docs.github.com/en/code-security/dependabot)
📖 [actions/starter-workflows — official templates](https://github.com/actions/starter-workflows)

### Workflow best practices

- **Pin action versions to a full SHA** — prevents supply-chain attacks:
  ```yaml
  uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
  ```
- Use **job matrices** for multi-version or multi-OS testing
- **Cache dependencies** with `actions/cache` for significant speed gains
- Use **GitHub Environments** with required reviewers for production deploy gates
- Store all secrets in **GitHub Secrets** (`Settings → Secrets and variables`) — never in code or workflow files
- Use `permissions:` at job level, granting least privilege

📖 [Security hardening for GitHub Actions](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions)

---

## 8. Security Practices

**Security is not a feature — it is a baseline requirement.**

### Enable GitHub's native security features

In **Settings → Security**, enable:

- ✅ **Dependency graph**
- ✅ **Dependabot alerts** — CVE notifications for dependencies
- ✅ **Dependabot security updates** — automated fix PRs
- ✅ **Secret scanning** — detect leaked credentials
- ✅ **Push protection** — block pushes containing secrets before they land

📖 [GitHub — Secret scanning](https://docs.github.com/en/code-security/secret-scanning/introduction/about-secret-scanning)

### `SECURITY.md`

Document your vulnerability disclosure policy clearly at the top of the repository.

```markdown
# Security Policy

## Supported Versions

| Version | Supported |
| ------- | --------- |
| 2.x     | ✅        |
| 1.x     | ❌        |

## Reporting a Vulnerability

**Do NOT open a public GitHub issue.**

Use GitHub's private vulnerability reporting or email security@yourorg.com.

Response SLA: 48-hour acknowledgement — 90-day remediation target.
```

📖 [GitHub — Private vulnerability reporting](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability)

### Code Scanning (SAST) with CodeQL

```yaml
# .github/workflows/codeql.yml
name: CodeQL
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 8 * * 1' # Weekly Monday 8am UTC

jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      - uses: github/codeql-action/init@28deaae8ccd58e35f8f0ef86827de2b5d52e9195 # v3.28.8
        with:
          languages: javascript, python
      - uses: github/codeql-action/analyze@28deaae8ccd58e35f8f0ef86827de2b5d52e9195 # v3.28.8
```

📖 [GitHub — Code scanning with CodeQL](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning-with-codeql)

### Supply chain security

- [Snyk](https://snyk.io/) — deep dependency vulnerability and licence scanning
- [Socket.dev](https://socket.dev/) — malicious package detection and supply chain analysis
- [TruffleHog](https://github.com/trufflesecurity/trufflehog) — detect secrets across git history

---

## 9. Documentation Standards

**Code explains how. Documentation explains why.**

### Docsite options

For significant projects, publish a dedicated documentation site via GitHub Pages:

| Tool                  | Best for           | Link                                                                                |
| --------------------- | ------------------ | ----------------------------------------------------------------------------------- |
| **MkDocs + Material** | Python / general   | [squidfunk.github.io/mkdocs-material](https://squidfunk.github.io/mkdocs-material/) |
| **Docusaurus**        | React/JS           | [docusaurus.io](https://docusaurus.io/)                                             |
| **VitePress**         | Vue/Vite           | [vitepress.dev](https://vitepress.dev/)                                             |
| **Starlight (Astro)** | Any — modern, fast | [starlight.astro.build](https://starlight.astro.build/)                             |

📖 [GitHub Pages documentation](https://docs.github.com/en/pages)

### `CHANGELOG.md` — Keep a Changelog format

```markdown
# Changelog

All notable changes to this project will be documented in this file.
Format: [Keep a Changelog](https://keepachangelog.com/) — [Semantic Versioning](https://semver.org/)

## [Unreleased]

## [1.2.0] - 2026-03-01

### Added

- OAuth2 GitHub login support (#42)

### Fixed

- Null pointer exception in payment handler (#87)

### Changed

- Migrated test runner from Jest to Vitest

### Removed

- Deprecated v1 API endpoints

## [1.1.0] - 2026-01-15
```

Automate changelog generation and releases:

- [Release Please](https://github.com/googleapis/release-please) — Google's GitHub Action, Conventional Commits-driven
- [semantic-release](https://semantic-release.gitbook.io/) — fully automated versioning and publishing

### Code-level documentation

| Language              | Standard                        | Reference                                            |
| --------------------- | ------------------------------- | ---------------------------------------------------- |
| JavaScript/TypeScript | JSDoc                           | [jsdoc.app](https://jsdoc.app/)                      |
| Python                | Google-style / NumPy docstrings | [sphinx.readthedocs.io](https://www.sphinx-doc.org/) |
| REST APIs             | OpenAPI 3.x (Swagger)           | [swagger.io](https://swagger.io/)                    |
| Elixir                | ExDoc                           | [hexdocs.pm/ex_doc](https://hexdocs.pm/ex_doc/)      |

### Architecture Decision Records (ADRs)

Capture major technical decisions with context and rationale in `/docs/adr/`.

```markdown
# ADR-001: Use PostgreSQL as primary database

**Date:** 2026-01-10
**Status:** Accepted

## Context

…

## Decision

…

## Consequences

…
```

📖 [ADR GitHub organization — templates and tooling](https://adr.github.io/)

---

## 10. Repository Hygiene & Maintenance

**A repository is a living artifact — neglect accumulates as technical debt.**

### Stale issue and PR automation

```yaml
# .github/workflows/stale.yml
- uses: actions/stale@v9
  with:
    stale-issue-message: 'This issue has been inactive for 60 days and will close in 14 days unless there is further activity.'
    stale-pr-message: 'This PR has been inactive for 30 days. Please update or it will be closed.'
    days-before-issue-stale: 60
    days-before-pr-stale: 30
    days-before-close: 14
    exempt-issue-labels: 'pinned,security,p0-critical'
```

📖 [actions/stale](https://github.com/actions/stale)

### Semantic versioning and tagging

Use `MAJOR.MINOR.PATCH` — [semver.org](https://semver.org/)

```bash
# Create an annotated release tag
git tag -a v1.2.0 -m "Release v1.2.0: add OAuth login, fix payment handler"
git push origin v1.2.0
```

Always create a **GitHub Release** from the tag with release notes summarising changes.
Automate end-to-end with [Release Please](https://github.com/googleapis/release-please).

📖 [GitHub — Managing releases](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository)

### Repository settings checklist

In **Settings → General**:

- [ ] **Topics** set (3–10 relevant keywords for discoverability)
- [ ] **Description** and **website URL** filled in
- [ ] **Social preview image** set (1280×640 px)
- [ ] **Default branch** is `main`
- [ ] **Automatically delete head branches** enabled
- [ ] **Discussions** enabled (if community-facing project)
- [ ] **Wikis** disabled — use `/docs/` folder for version-controlled documentation
- [ ] **Merge strategies**: Squash and merge for features; Merge commit for release branches

### Archiving

Archive (don't delete) deprecated or completed repositories to preserve links, search indexing, and historical reference.

📖 [GitHub — Archiving repositories](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories)

---

## 11. Community & Open Source Health Files

GitHub surfaces these files prominently in the **Community Standards** checklist (Insights → Community Standards).

| File                 | Purpose                                          | Location           |
| -------------------- | ------------------------------------------------ | ------------------ |
| `README.md`          | Project overview and entry point                 | Root or `docs/`    |
| `CONTRIBUTING.md`    | How to contribute, setup, PR process             | Root or `.github/` |
| `CODE_OF_CONDUCT.md` | Community behaviour standards                    | Root or `.github/` |
| `SECURITY.md`        | Vulnerability reporting policy                   | Root or `.github/` |
| `SUPPORT.md`         | Where to get help (Discussions, Slack, etc.)     | Root or `.github/` |
| `GOVERNANCE.md`      | Decision-making process (large OSS only)         | Root               |
| `FUNDING.yml`        | Sponsor links (GitHub Sponsors, Open Collective) | `.github/`         |

### `.github` organisation repository

Store default community health files for your **entire organisation** in a public repo named `.github`. GitHub will use these as defaults for any repos in the org that don't have their own.

📖 [GitHub — Default community health files](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file)
📖 [Contributor Covenant](https://www.contributor-covenant.org/) — widely adopted Code of Conduct template

---

## 12. Recommended Tools & Integrations

### Developer workflow

| Tool                    | Purpose                            | Link                                                               |
| ----------------------- | ---------------------------------- | ------------------------------------------------------------------ |
| **GitHub CLI**          | Automate GitHub from your terminal | [cli.github.com](https://cli.github.com/)                          |
| **pre-commit**          | Multi-language Git hook framework  | [pre-commit.com](https://pre-commit.com/)                          |
| **Husky + lint-staged** | JS/TS pre-commit quality hooks     | [typicode.github.io/husky](https://typicode.github.io/husky/)      |
| **act**                 | Run GitHub Actions locally         | [github.com/nektos/act](https://github.com/nektos/act)             |
| **GitHub Copilot**      | AI-assisted code & PR authoring    | [github.com/features/copilot](https://github.com/features/copilot) |

### Code quality

| Tool           | Purpose                               | Link                                      |
| -------------- | ------------------------------------- | ----------------------------------------- |
| **Codecov**    | Coverage reporting and trend analysis | [codecov.io](https://codecov.io/)         |
| **SonarCloud** | Code quality, smells, and security    | [sonarcloud.io](https://sonarcloud.io/)   |
| **Codacy**     | Automated PR code review              | [codacy.com](https://www.codacy.com/)     |
| **DeepSource** | Static analysis, anti-patterns        | [deepsource.com](https://deepsource.com/) |

### Release automation

| Tool                 | Purpose                              | Link                                                                                 |
| -------------------- | ------------------------------------ | ------------------------------------------------------------------------------------ |
| **Release Please**   | Automated changelogs and releases    | [github.com/googleapis/release-please](https://github.com/googleapis/release-please) |
| **semantic-release** | Fully automated versioning & publish | [semantic-release.gitbook.io](https://semantic-release.gitbook.io/)                  |
| **changesets**       | Monorepo versioning and changelogs   | [github.com/changesets/changesets](https://github.com/changesets/changesets)         |

### Security

| Tool           | Purpose                             | Link                                                                                   |
| -------------- | ----------------------------------- | -------------------------------------------------------------------------------------- |
| **Dependabot** | Automated dependency security PRs   | [docs.github.com — Dependabot](https://docs.github.com/en/code-security/dependabot)    |
| **Snyk**       | Supply chain and SAST scanning      | [snyk.io](https://snyk.io/)                                                            |
| **Socket**     | Malicious package detection         | [socket.dev](https://socket.dev/)                                                      |
| **TruffleHog** | Secret detection across git history | [github.com/trufflesecurity/trufflehog](https://github.com/trufflesecurity/trufflehog) |

### Documentation

| Tool                | Purpose                        | Link                                                                                |
| ------------------- | ------------------------------ | ----------------------------------------------------------------------------------- |
| **MkDocs Material** | Documentation site generator   | [squidfunk.github.io/mkdocs-material](https://squidfunk.github.io/mkdocs-material/) |
| **Docusaurus**      | React-based documentation site | [docusaurus.io](https://docusaurus.io/)                                             |
| **Starlight**       | Astro-based documentation site | [starlight.astro.build](https://starlight.astro.build/)                             |

---

## 13. Quick Reference Checklist

### New repository setup

- [ ] `README.md` — complete with overview, install, usage, badges
- [ ] `LICENSE` — choose and commit before first publish
- [ ] `.gitignore` — project-specific, no build artifacts or IDE files
- [ ] `.editorconfig` — consistent formatting across editors
- [ ] Branch protection on `main` — PR required, status checks required, no force push
- [ ] PR template (`.github/PULL_REQUEST_TEMPLATE.md`)
- [ ] Issue templates (`.github/ISSUE_TEMPLATE/`)
- [ ] `CODEOWNERS` — auto-assign relevant reviewers
- [ ] `CONTRIBUTING.md` — how to set up locally and submit changes
- [ ] `SECURITY.md` — vulnerability disclosure policy
- [ ] `CODE_OF_CONDUCT.md` — community behaviour standards
- [ ] Dependabot enabled — npm + GitHub Actions ecosystems
- [ ] Secret scanning + push protection enabled
- [ ] CI workflow — lint, test, build on every push and PR
- [ ] Repository settings — topics, description, social preview image

### Ongoing habits

- [ ] Review and merge Dependabot PRs weekly
- [ ] Triage new issues within 48 hours
- [ ] Update `CHANGELOG.md` on every release
- [ ] Audit and clean stale branches monthly
- [ ] Review security alerts promptly (aim for < 7 days for p1+)
- [ ] Update documentation alongside every code change
- [ ] Rotate any secrets that appear in scan results immediately

---

## 14. Key References

### GitHub documentation

- [GitHub Docs — home](https://docs.github.com/)
- [GitHub Skills — interactive courses](https://skills.github.com/)
- [GitHub Engineering Blog](https://github.blog/engineering/)
- [Open Source Guides by GitHub](https://opensource.guide/)
- [GitHub Actions starter-workflows](https://github.com/actions/starter-workflows)

### Standards and specifications

- [Conventional Commits](https://www.conventionalcommits.org/)
- [Semantic Versioning — semver.org](https://semver.org/)
- [Keep a Changelog](https://keepachangelog.com/)
- [Choose a License](https://choosealicense.com/)
- [OpenAPI Specification](https://spec.openapis.org/oas/latest.html)
- [Architecture Decision Records](https://adr.github.io/)

### Community and ecosystem

- [Contributor Covenant — Code of Conduct](https://www.contributor-covenant.org/)
- [AlgoScan — Algorand repository explorer](https://algoscan.dev)
- [Algorand Developer Portal](https://dev.algorand.co/)
- [Algorand Developer Forum](https://forum.algorand.co/)

---

_Document version: 2.0 — March 2026_
_Maintained against GitHub's current platform features._