Companion Podcast and Transcript

Use audio and transcript companions to review concepts in a conversational format.

Releases, Tags, and Insights

Companion audio: this episode reinforces key ideas and may not be a word-for-word reading of this page.

Open audio file (external) Full transcript source (external)

Transcript preview

Alex: Welcome back. Today we're looking at two parts of GitHub that help you understand where a project has been and where your work may show up later: releases and repository Insights.

Jamie: I like that pairing, because releases feel very official, and Insights can feel a little mysterious. Both can answer the question, is this project active, and where do my contributions fit?

Alex: Exactly. A release is about a versioned snapshot. Insights are about activity, participation, traffic, dependencies, and other signals that help you read the health of a repository.

Jamie: So we're not just clicking around. We're learning how maintainers communicate progress, and how contributors can tell what is happening.

Appendix S: Releases, Tags, and Repository Insights

Listen to Episode 25: Releases, Tags, and Insights - a conversational audio overview of this chapter. Listen before reading to preview the concepts, or after to reinforce what you learned.

Reference companion to: Chapter 08: Open Source Culture

Authoritative source: GitHub Docs: About releases

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?
  2. Releases vs. Tags vs. Branches
  3. Navigating Releases on GitHub
  4. Understanding Version Numbers
  5. Reading Release Notes
  6. For Maintainers: Creating a Release
  7. Draft and Pre-Release States
  8. Accessibility Agents: /draft-release

Part 2 - Repository Insights

  1. What Is the Insights Tab?
  2. Navigating to Insights
  3. Pulse - Recent Activity Summary
  4. Contributors - Who Builds the Project
  5. Traffic - Who Visits the Repo
  6. Commits and Code Frequency
  7. Dependency Graph
  8. Network and Forks
  9. Community Standards
  10. Screen Reader Navigation Reference
  11. 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

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)
2 → Jump between release title headings
K → Navigate links (download assets, compare, tag links)
↓ → Read release notes

Learning Cards: Navigating Releases

Screen reader users
  • On the repository home page, press H or 3 to find the "Releases" heading in the right sidebar, then K to the version link — Enter opens the latest release directly
  • On the Releases list page, each release is a heading — use 2 or 3 to jump between releases and arrow down to read the notes inline
  • The "Latest" badge appears next to the most recent stable release — listen for it to distinguish stable releases from pre-releases or older versions
Low vision users
  • The Releases link on the repo home page sits in the right sidebar — at high zoom the sidebar may collapse below the main content; scroll down to find it
  • Release notes use Markdown headings (Breaking Changes, New Features, Bug Fixes) — zoom in and scan the bold section labels for quick triage
  • The green "Latest" badge next to the newest stable release is small — zoom to 150%+ to spot it among the release list entries
Sighted users
  • On the repository home page, look at the right sidebar for the Releases section showing the latest version number and a link to all releases
  • On the Releases list page, each release card shows a title, date, tag, and a "Latest" badge on the most recent stable version
  • Scroll through release notes to see categorized change lists — look for the "Full Changelog" link at the bottom to see every merged PR between two versions

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

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:

## 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.

Learning Cards: Creating a Release

Screen reader users:

  • The release creation form at github.com/owner/repo/releases/new has several fields -- Tab through them in order: tag selector (combobox), target branch, title input, release notes textarea, asset upload, pre-release checkbox, draft checkbox, and publish button
  • The tag selector is a combobox -- type a new version tag (e.g., v2.1.0) and the option to create it appears; arrow down and press Enter to select
  • The "Generate release notes" button auto-fills the textarea with merged PR titles -- after clicking it, arrow through the generated notes to verify accuracy before publishing

Low-vision users:

  • The release creation page uses a single-column form layout -- zoom in and the form fields stack vertically for easy scanning
  • The "Pre-release" and "Draft" checkboxes are at the bottom of the form, below the release notes editor -- scroll past the potentially long textarea to find them
  • The "Generate release notes" button is a small link-style button near the release notes textarea -- look for it above or beside the text area at high magnification

Sighted users:

  • The tag selector dropdown shows existing tags and a text input for creating new ones -- type v to filter for version tags
  • Click "Generate release notes" to auto-populate from merged PRs since the last release -- review and manually categorize the entries (Breaking Changes, Features, Bug Fixes) for a polished result
  • The Assets section at the bottom accepts drag-and-drop file uploads for binaries, installers, or compiled packages

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

/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

## 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

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

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

Learning Cards: Pulse (Recent Activity Summary)

Screen reader users
  • Pulse is the Insights landing page — after entering the Insights tab, you land here; use 2 to jump between section headings (Merged PRs, Opened Issues, etc.)
  • Each section lists linked PR or issue titles — press 3 to jump between individual items, or K to navigate the links directly
  • Use the time period selector (last 24 hours, 7 days, 30 days) at the top to scope the summary — Tab to it and select with arrow keys
Low vision users
  • Pulse displays activity counts in large numbers at the top of the page — zoom in to read the open/closed/merged totals
  • The merged PR and opened issue lists below the summary use standard link formatting — increase font size to scan titles comfortably
  • The time period toggle (24h, 7d, 30d) sits near the top — it can be small at default zoom; look for the underlined active period indicator
Sighted users
  • Pulse shows a dashboard-style summary at the top with counts for issues opened/closed and PRs opened/merged/closed in the chosen time period
  • Below the summary, merged PRs and proposed PRs are listed as clickable links — scan titles to see recent activity at a glance
  • Use the time period selector (24 hours, 7 days, 30 days) at the top right to adjust the window — 7 days is the default and most useful for weekly check-ins

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.

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

Learning Cards: Contributors

Screen reader users:

  • The contributor chart is a canvas graphic that screen readers cannot access -- skip it and navigate to the data table below with T (next table) which contains the same information in accessible form
  • The table has sortable column headers (Commits, Additions, Deletions) -- Tab to a header and press Enter to sort; the table reloads with the new sort order
  • Each contributor's username is a link to their filtered commit list -- activate it to see every commit that person made to this repository

Low-vision users:

  • The bar chart uses color to distinguish contributors -- the table below provides the same data as text; zoom in on the table if the chart colors are hard to differentiate
  • Sorting by Commits (default) puts top contributors first -- at high zoom, the table may require horizontal scrolling to see the Additions and Deletions columns
  • After your first merged PR, your username appears in this table -- link to it (github.com/owner/repo/graphs/contributors) as proof of contribution in your portfolio

Sighted users:

  • The color-coded bar chart at the top shows commit frequency over time -- each contributor is a different color in the stacked bars
  • The table below the chart is sortable by column -- click Commits, Additions, or Deletions to reorder and quickly find the most active contributors
  • Your name appears here after your first merged PR -- bookmark the URL to reference your contribution history when building your developer portfolio

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 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

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)

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

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

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:

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

Insights Pages

Insights tab bar (sub-navigation)

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.

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

Pulse view

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:

/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:

/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

Next: Appendix T: Community and Social
Back: Appendix R: Projects Deep Dive
Teaching chapter: Chapter 08: Open Source Culture

Authoritative Sources

Use these official references when you need the current source of truth for facts in this chapter.

Section-Level Source Map

Use this map to verify facts for each major section in this file.