# Appendix H: Releases, Tags, and Repository Insights
>
> **Listen to Episode 25:** [Releases, Tags, and Insights](../PODCASTS.md) - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

## Understanding Versioned Releases and Repository Activity

> Two things help you understand a repository's health and your place in it: **releases** (the versioned snapshots your contributions land in) and **insights** (the activity metrics that show how a project grows). This appendix covers both.


## Table of Contents

### Part 1 - Releases and Tags

1. [What Is a Release?](#1-what-is-a-release)
2. [Releases vs. Tags vs. Branches](#2-releases-vs-tags-vs-branches)
3. [Navigating Releases on GitHub](#3-navigating-releases-on-github)
4. [Understanding Version Numbers](#4-understanding-version-numbers)
5. [Reading Release Notes](#5-reading-release-notes)
6. [For Maintainers: Creating a Release](#6-for-maintainers-creating-a-release)
7. [Draft and Pre-Release States](#7-draft-and-pre-release-states)
8. [Accessibility Agents: `/draft-release`](#8-accessibility-agents-draft-release)

### Part 2 - Repository Insights

1. [What Is the Insights Tab?](#9-what-is-the-insights-tab)
2. [Navigating to Insights](#10-navigating-to-insights)
3. [Pulse - Recent Activity Summary](#11-pulse---recent-activity-summary)
4. [Contributors - Who Builds the Project](#12-contributors---who-builds-the-project)
5. [Traffic - Who Visits the Repo](#13-traffic---who-visits-the-repo)
6. [Commits and Code Frequency](#14-commits-and-code-frequency)
7. [Dependency Graph](#15-dependency-graph)
8. [Network and Forks](#16-network-and-forks)
9. [Community Standards](#17-community-standards)
10. [Screen Reader Navigation Reference](#18-screen-reader-navigation-reference)
11. [Accessibility Agents: `/my-stats` and `/team-dashboard`](#19-accessibility-agents-my-stats-and-team-dashboard)


## Part 1 - Releases and Tags

## 1. What Is a Release?

A **release** is a named snapshot of a repository at a specific point in history, packaged and published for users.

For software projects, a release typically includes:

- A version number (e.g., `v2.1.0`)
- Release notes explaining what changed
- Links to download the compiled or packaged software (if applicable)
- Source code archives (automatically generated by GitHub)

For documentation-only or non-software projects, releases are often used to mark stable checkpoints or versions of a document.

**When your PR gets merged:** Your change becomes part of the code on the default branch. It will be *included* in the next release whenever the maintainer decides to publish one - this might be days, weeks, or months away depending on the project's release cadence.


## 2. Releases vs. Tags vs. Branches

These three concepts are closely related:

| Concept | What It Is | Lives |
| ---  | ---  | ---  |
| **Branch** | A movable pointer to the latest commit on a line of work | Permanently moves as commits are added |
| **Tag** | A fixed pointer to a single specific commit | Never moves - always points to the same commit |
| **Release** | A tag + release notes + optional downloadable assets published on GitHub | Based on a tag |

### The relationship

- Every release is backed by a tag
- A tag without a release is just a version marker in the git history
- GitHub automatically creates a tag when you create a release


## 3. Navigating Releases on GitHub

### Finding the Releases Page

From any repository page:

1. Look on the right sidebar for a **"Releases"** section showing the latest release
2. Activate "Releases" or the version link to go to the full releases page
3. Alternatively: navigate to `github.com/owner/repo/releases`

#### Screen reader path

```text
On the repository home page:
→ H or 3 to find "Releases" heading in the right sidebar
→ Tab to the latest release link → Enter
→ Or: Tab to "N Releases" count link → Enter → Opens full releases list
```

### The Releases List Page

Each release appears as a section with:

- The release title (usually the version number)
- A badge: "Latest" (most recent stable), "Pre-release", or nothing (older release)
- Publication date
- The tag name
- Release notes (the main body)
- Asset downloads (if included)
- Source code download links (always present - auto-generated zip/tar.gz)

#### Navigation

```text
2 → Jump between release title headings
K → Navigate links (download assets, compare, tag links)
↓ → Read release notes
```


## 4. Understanding Version Numbers

Most projects follow **Semantic Versioning** (semver): `MAJOR.MINOR.PATCH`

| Part | When It Changes | Meaning |
| ---  | ---  | ---  |
| `MAJOR` (e.g., `2.x.x`) | Breaking changes | Existing behavior changed in an incompatible way; users may need to update their code |
| `MINOR` (e.g., `x.1.x`) | New features, backward-compatible | New functionality added; existing code still works |
| `PATCH` (e.g., `x.x.1`) | Bug fixes | Something was broken and is now fixed |

### Examples

- `v2.0.0` → major release, breaking changes possible
- `v2.1.0` → new features added
- `v2.1.3` → three bug fixes since v2.1.0

**Pre-release suffixes** (not part of semver core, but common):

- `v2.1.0-alpha.1` → early preview, may be unstable
- `v2.1.0-beta.2` → feature-complete but still testing
- `v2.1.0-rc.1` → release candidate, nearly final

### Your contribution's journey

```text
PR opened → PR reviewed → PR merged → default branch updated
                                              ↓
                                   Next release prepared
                                              ↓
                          Tag created → Release published → v2.1.1
```


## 5. Reading Release Notes

Release notes document what changed. High-quality release notes categorize changes:

```text
## What's New in v2.1.0

### Breaking Changes
- The `preferences.md` format has changed - see the migration guide

### New Features
- Added `/project-status` command (#42, @alice)
- Added `/onboard-repo` command (#38, @bob)

### Bug Fixes
- Fixed keyboard navigation in the triage workflow (#51, @charlie)
- Screen reader announcement now correct for merged PRs (#48, @alice)

### Dependencies
- Updated github-mcp-server to v3.0.1

**Full Changelog:** https://github.com/owner/repo/compare/v2.0.0...v2.1.0
```

**The "Full Changelog" link** at the bottom of many release notes goes to a comparison view showing every merged PR between two tags. This is where you'll see your PR listed by name, with your username credited.


## 6. For Maintainers: Creating a Release

This section is relevant if you become a maintainer or contribute to a project that asks you to prepare releases.

### Creating a Release from the GitHub UI

1. Navigate to `github.com/owner/repo/releases/new`
2. **Choose a tag:** Type a new version tag (e.g., `v2.1.0`) - GitHub will create it on publish, or select an existing tag if you already created one
3. **Choose a target branch:** The branch the tag will be applied to (usually `main`)
4. **Release title:** Usually the same as the tag (e.g., `v2.1.0`)
5. **Release notes:** Write manually, or click **"Generate release notes"** - GitHub auto-generates from merged PR titles since the last release
6. **Assets:** Optionally attach compiled binaries or other files
7. **Pre-release toggle:** Mark as pre-release if it's alpha/beta
8. **Draft toggle:** Save as draft to prepare without publishing immediately
9. **Publish release**

### Using Accessibility Agents for Release Notes

The `/draft-release` command generates structured release notes automatically from your merged PRs - much faster and more consistent than writing them manually. See [Section 8](#8-accessibility-agents-draft-release).


## 7. Draft and Pre-Release States

**Draft release:** Saved but not published. Only visible to repository collaborators. Use drafts to prepare release notes in advance.

**Pre-release:** Published and visible, but not marked "Latest." Users who look for the latest stable version won't be directed to it automatically. Use for alpha/beta/RC versions.

**Latest release:** The most recent non-pre-release, non-draft release. This is what GitHub highlights in the sidebar and what `github.com/owner/repo/releases/latest` redirects to.


## 8. Accessibility Agents: `/draft-release`

The `/draft-release` command automates release note generation from your merged pull requests.

### Usage

```text
/draft-release v2.1.0
/draft-release owner/repo v2.1.0
```

### What it produces

- Auto-categorized changes: Breaking Changes, Features, Bug Fixes, Dependencies
- Each PR listed with number, title, and author
- A full changelog link
- Markdown formatted and ready to paste into GitHub's release editor

### Example output

```markdown
## v2.1.0

### New Features
- Add `/project-status` command (#42, @alice)
- Add `/onboard-repo` for first-time repo scanning (#38, @bob)

### Bug Fixes
- Fix keyboard navigation in triage workflow (#51, @charlie)
- Correct screen reader announcement for merged PRs (#48, @alice)

### Dependencies
- Update github-mcp-server to v3.0.1 (#55)

**Full Changelog:** https://github.com/community-access/accessibility-agents/compare/v2.0.0...v2.1.0
```

> **See also:** The `/release-prep` command runs a complete pre-release checklist (milestone status, open PRs, CI health, security, and then generates release notes) - useful when preparing a release from scratch rather than just generating notes.


## Part 2 - Repository Insights

## 9. What Is the Insights Tab?

The Insights tab shows quantitative activity data for a repository. It is primarily read-only and chart-heavy - but all underlying data is also presented in tables that screen readers can navigate.

### Who can see Insights

- Anyone can see Insights on a public repository
- Private repository Insights require collaborator access

### What Insights does NOT show

- Individual user data in detail (e.g., lines per commit per person)
- Real-time data (most views update daily or weekly)
- Code quality scores


## 10. Navigating to Insights

From any repository:

1. Navigate to the repository's main tab bar
2. Find and select the **Insights** tab
3. The Insights sub-navigation has multiple views listed on the left (or top on smaller screens)

### Screen reader path

```text
T → navigate the repository tab bar
→ "Insights" link → Enter
→ Left sidebar has sub-navigation: Pulse, Contributors, Traffic, Commits, etc.
→ K to navigate sidebar links → Enter to open each view
```


## 11. Pulse - Recent Activity Summary

**Pulse** is the Insights landing page. It summarizes activity in a chosen time period (last 24 hours, 7 days, or 30 days):

- **Open issues / Closed issues** - net change in the time period
- **Open pull requests / Merged pull requests / Closed pull requests** - with counts
- **Authors:** N contributors pushed M commits to N branches
- A list of merged PRs (each linked to the PR)
- A list of proposed PRs (open)
- A list of opened and closed issues

### What it tells you as a contributor

- Is this project actively maintained? (Are PRs being merged regularly?)
- Is there a backlog? (Many open issues vs. few closures)
- Is the maintainer responsive? (Time between PR open and merge)

### Screen reader navigation

```text
2 → Section headings: "Merged pull requests", "Proposed pull requests", "Closed issues", etc.
3 → Individual PR/issue title links within each section
K → Navigate all links
```


## 12. Contributors - Who Builds the Project

The Contributors view shows a bar chart of commits over time, with each contributor represented by a different color. Below the chart is a sortable table.

### The table (accessible)

- Username
- Number of commits (with a link to filtered commit history)
- Additions (lines added)
- Deletions (lines removed)
- Sorted by total commits by default

### Why this matters as a new contributor

- You can see how active top contributors are
- After your first merged PR, your name appears here (with your commits)
- You can link to your section (`github.com/owner/repo/graphs/contributors`) as proof of contribution

### Screen reader

The chart is a canvas graphic - not directly readable. The table below it is fully accessible. Navigate with `T` to reach the table, then `Tab` for sorting controls.

```text
T → Contributors table
Tab → Column headers (click to sort: Commits, Additions, Deletions)
↓ → Navigate rows (each contributor is a row)
K → Links to each contributor's filtered commit list
```


## 13. Traffic - Who Visits the Repo

**Traffic** shows who is viewing and cloning the repository. Available only to repository owners and collaborators with push access.

### Metrics

| View | What It Shows |
| ---  | ---  |
| **Visitors** | Unique visitors and total page views over 14 days |
| **Git clones** | Number of times the repo was cloned (git clone, not forks) |
| **Referring sites** | Where traffic comes from (Google, Hacker News, direct, etc.) |
| **Popular content** | Which files and pages in the repo get the most views |

### Why this matters

- If the README is the most-viewed file, documentation improvements have high impact
- If traffic spiked when a blog post linked the repo, that's a good signal for community growth


## 14. Commits and Code Frequency

**Commits** shows commit frequency over the past year, by week. Useful for identifying:

- Active development periods (many commits)
- Dormant periods (no commits) - a project with 6+ months of inactivity may be unmaintained
- Release sprints (burst of commits before a release tag)

**Code Frequency** shows additions and deletions per week as an area chart. A healthy codebase has more additions than deletions until it matures, then stabilizes.

**Churn** (high deletions alongside high additions) can indicate:

- Heavy refactoring
- Ongoing maintenance of large files
- Active cleanup of technical debt

**Screen reader note for both views:** The charts are visual canvas elements. For a text-based view of commit history, use the Commits tab on the main repository page instead.


## 15. Dependency Graph

The **Dependency Graph** shows:

- What your project depends on (libraries, packages)
- What depends on your project (if others import your repo)

**Dependents** - repositories that depend on this one - is the "used by" count you see on the right sidebar of popular packages.

### Enabling/viewing

- Settings → Security & Analysis → Dependency graph → Enable
- Navigate to Insights → Dependency graph

**Why it matters for security:** The dependency graph feeds Dependabot. If a vulnerability is found in a library, Dependabot uses this graph to identify which repos use the affected version and opens automated PRs to update them. See [Appendix L: GitHub Security Features](appendix-l-github-security-features.md) for more on Dependabot.


## 16. Network and Forks

The **Network** view shows a graphical branch/fork network - who has forked the repo, what branches exist, and how they diverge.

**Screen reader note:** The network graph is a canvas visualization not accessible to screen readers. The underlying fork list is accessible separately at `github.com/owner/repo/forks`.

**The forks list** (at `/forks`) is a simple table of who forked the repo - navigable with standard table navigation.


## 17. Community Standards

The **Community Standards** view (found in the Insights sidebar or in the main repository homepage's "Recommended" sidebar section) shows a checklist of community health files:

| File | Purpose | Status |
| ---  | ---  | ---  |
| Description | One-line repo summary | Present or Missing |
| README | Project overview | Present or Missing |
| Code of Conduct | Community behavior standards | Present or Missing |
| Contributing guide | How to contribute | Present or Missing |
| License | Usage rights | Present or Missing |
| Issue templates | Structured issue forms | Present or Missing |
| Pull request template | PR checklist | Present or Missing |
| Security policy | How to report vulnerabilities | Present or Missing |

A fully green checklist signals a well-maintained project. For accessibility-agents contributors, **adding a missing community health file is always a welcome `good first issue` contribution.**

### Screen reader

```text
H / 2 → "Community Standards" section heading
Tab → Each checklist item (links to add missing files)
```


## 18. Screen Reader Navigation Reference

### Releases Pages

#### Repository home page (finding releases)

```text
Right sidebar:
→ H or 3 to find "Releases" heading
→ K to the version link (e.g., "v2.1.0") → Enter opens that release
→ K to the "N releases" count link → Enter opens full list
```

#### Releases list page

```text
2         → Major section headings
3         → Individual release title headings (each release is an h2 or h3)
K         → Navigate links (assets, tag, compare)
↓         → Read release notes inline
```

#### Individual release page

```text
H / 2     → Section headings within release notes
I         → List items (change entries)
K         → Links (PRs referenced, comparison link, asset downloads)
```

#### Comparing two releases (the Changelog)

The compare URL (`/compare/v1.0.0...v2.0.0`) shows a diff of all commits and merged PRs between two tags:

```text
3         → Individual commit or PR headings
I         → Commit list items
```

### Insights Pages

#### Insights tab bar (sub-navigation)

```text
Insights left sidebar:
K → Navigate sidebar links: Pulse, Contributors, Traffic, Commits, Code frequency, Dependency graph, Network, Forks, Community
Enter → Open that Insights view
```

#### Charts and graphs - general strategy

Most Insights charts are canvas or SVG visuals. They announce as "image" or "graphic" to screen readers. **Skip the chart and use the data table or list below it**, which contains the same information in accessible form.

```text
T → Jump to data tables
H → Section headings
I → List items (in Pulse views)
```

#### Pulse view

```text
2 → "Merged pull requests", "Opened issues", etc. sections
3 → Individual PR/issue titles
K → Links to each item
```


## 19. Accessibility Agents: `/my-stats` and `/team-dashboard`

Instead of navigating GitHub's chart-heavy Insights UI, Accessibility Agents provides two commands that deliver the same data in text form directly in VS Code.

### `/my-stats`

Shows your personal contribution statistics across all tracked repos:

```text
/my-stats
/my-stats last 30 days
/my-stats org:community-access
```

Output includes:

- PRs opened and merged
- Issues filed and closed
- Reviews conducted
- Commits pushed
- Compare to previous period

### `/team-dashboard`

Shows team-wide activity across tracked repos - who contributed what, response times, review coverage:

```text
/team-dashboard
/team-dashboard org:community-access
/team-dashboard sprint
```

Output includes:

- Per-person contribution summary
- Review coverage (how many PRs got reviews)
- Open issues by assignee
- CI health across team repos

**Use these instead of navigating the Insights UI** when you want contribution data without leaving VS Code and without dealing with canvas charts.


*Return to: [Resources](appendix-u-resources.md) | [Glossary](appendix-a-glossary.md)*