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.
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.
- What Is a Release?
- Releases vs. Tags vs. Branches
- Navigating Releases on GitHub
- Understanding Version Numbers
- Reading Release Notes
- For Maintainers: Creating a Release
- Draft and Pre-Release States
- Accessibility Agents:
/draft-release
- What Is the Insights Tab?
- Navigating to Insights
- Pulse - Recent Activity Summary
- Contributors - Who Builds the Project
- Traffic - Who Visits the Repo
- Commits and Code Frequency
- Dependency Graph
- Network and Forks
- Community Standards
- Screen Reader Navigation Reference
- Accessibility Agents:
/my-statsand/team-dashboard
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.
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 |
- 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
From any repository page:
- Look on the right sidebar for a "Releases" section showing the latest release
- Activate "Releases" or the version link to go to the full releases page
- Alternatively: navigate to
github.com/owner/repo/releases
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
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
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 |
v2.0.0→ major release, breaking changes possiblev2.1.0→ new features addedv2.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 unstablev2.1.0-beta.2→ feature-complete but still testingv2.1.0-rc.1→ release candidate, nearly final
PR opened → PR reviewed → PR merged → default branch updated
↓
Next release prepared
↓
Tag created → Release published → v2.1.1
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.
This section is relevant if you become a maintainer or contribute to a project that asks you to prepare releases.
- Navigate to
github.com/owner/repo/releases/new - 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 - Choose a target branch: The branch the tag will be applied to (usually
main) - Release title: Usually the same as the tag (e.g.,
v2.1.0) - Release notes: Write manually, or click "Generate release notes" - GitHub auto-generates from merged PR titles since the last release
- Assets: Optionally attach compiled binaries or other files
- Pre-release toggle: Mark as pre-release if it's alpha/beta
- Draft toggle: Save as draft to prepare without publishing immediately
- Publish release
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.
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.
The /draft-release command automates release note generation from your merged pull requests.
/draft-release v2.1.0
/draft-release owner/repo v2.1.0
- 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
## 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.0See also: The
/release-prepcommand 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.
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.
- Anyone can see Insights on a public repository
- Private repository Insights require collaborator access
- Individual user data in detail (e.g., lines per commit per person)
- Real-time data (most views update daily or weekly)
- Code quality scores
From any repository:
- Navigate to the repository's main tab bar
- Find and select the Insights tab
- The Insights sub-navigation has multiple views listed on the left (or top on smaller screens)
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
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
- 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)
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
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.
- Username
- Number of commits (with a link to filtered commit history)
- Additions (lines added)
- Deletions (lines removed)
- Sorted by total commits by default
- 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
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
Traffic shows who is viewing and cloning the repository. Available only to repository owners and collaborators with push access.
| 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 |
- 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
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.
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.
- 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.
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.
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.
H / 2 → "Community Standards" section heading
Tab → Each checklist item (links to add missing files)
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
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
H / 2 → Section headings within release notes
I → List items (change entries)
K → Links (PRs referenced, comparison link, asset downloads)
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 left sidebar:
K → Navigate sidebar links: Pulse, Contributors, Traffic, Commits, Code frequency, Dependency graph, Network, Forks, Community
Enter → Open that Insights view
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)
2 → "Merged pull requests", "Opened issues", etc. sections
3 → Individual PR/issue titles
K → Links to each item
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.
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
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
Use these instead of navigating the Insights UI when you want contribution data without leaving VS Code and without dealing with canvas charts.