Improve Changelog docs and expand guidance

Author: rich-iannone

user_guide/17-changelog.qmd

@@ -7,33 +7,35 @@ tags: [Quality, GitHub]
 
 # Changelog
 
-Great Docs can automatically generate a Changelog page from your GitHub Releases. Each published release becomes a section on the page, with its title, date, body content, and a link back to the release on GitHub.
+Users want to know what changed between versions, whether that's new features, bug fixes, or breaking changes. A well-maintained changelog builds trust and helps people decide when to upgrade. But keeping a separate changelog file in sync with your actual releases is tedious and error-prone.
+
+Great Docs solves this by automatically generating a Changelog page from your GitHub Releases. Each published release becomes a section on the page, with its title, date, body content, and a link back to the release on GitHub. If you keep your release notes up to date on GitHub, your documentation site reflects them without any extra work.
 
 ## How It Works
 
 When changelog generation is enabled (the default), `great-docs build` will:
 
-1. **Detect your GitHub repository** – reads the `Repository` URL from `[project.urls]` in `pyproject.toml`
-2. **Fetch releases** – calls the GitHub Releases API to retrieve published releases
-3. **Generate the page** – writes a `changelog.qmd` file in the build directory with one section per release
-4. **Add a navbar link** – adds a "Changelog" item to the site's top navigation bar
+1. **Detect your GitHub repository**: reads the `Repository` URL from `[project.urls]` in `pyproject.toml`
+2. **Fetch releases**: calls the GitHub Releases API to retrieve published releases
+3. **Generate the page**: writes a `changelog.qmd` file in the build directory with one section per release
+4. **Add a navbar link**: adds a "Changelog" item to the site's top navigation bar
 
-The result is a fully rendered Changelog page that stays in sync with your GitHub Releases (no manual maintenance needed).
+The result is a fully rendered Changelog page that stays in sync with your GitHub Releases. No manual maintenance is needed, and the page is regenerated on every build.
 
 ## Prerequisites
 
-Your `pyproject.toml` must include a `Repository` URL pointing to GitHub:
+For changelog generation to work, Great Docs needs to know where your repository lives. Your `pyproject.toml` must include a `Repository` URL pointing to GitHub:
 
 ```{.toml filename="pyproject.toml"}
 [project.urls]
 Repository = "https://github.com/your-org/your-package"
 ```
 
-If no GitHub URL is found, the changelog step is silently skipped.
+If no GitHub URL is found, the changelog step is silently skipped and the build continues normally.
 
 ## Configuration
 
-The changelog works out of the box with sensible defaults. To customize behavior, add a `changelog` section to `great-docs.yml`:
+The changelog works out of the box with sensible defaults. You only need to add a `changelog` section to `great-docs.yml` if you want to change the behavior:
 
 ```{.yaml filename="great-docs.yml"}
 changelog:
@@ -63,7 +65,7 @@ Releases are shown in reverse chronological order (newest first), so older relea
 
 ## Authentication
 
-The GitHub API allows unauthenticated requests but with a low rate limit (60 requests/hour). For most projects this is fine, but if you hit rate limits, particularly in CI, set a GitHub token:
+The GitHub API allows unauthenticated requests but with a low rate limit (60 requests/hour). For most projects this is sufficient because the changelog is only fetched once per build. If you hit rate limits (particularly in CI environments with many concurrent builds), set a GitHub token:
 
 ```{.bash filename="Terminal"}
 export GITHUB_TOKEN=ghp_your_token_here
@@ -79,25 +81,29 @@ In GitHub Actions workflows, `GITHUB_TOKEN` is already available automatically.
 
 ## Standalone CLI Command
 
-You can generate the changelog independently of a full build:
+You can generate the changelog independently of a full build. This is useful for testing your release notes formatting or regenerating just the changelog without rebuilding the entire site:
 
 ```{.bash filename="Terminal"}
 great-docs changelog
 ```
 
-This is useful for testing or regenerating just the changelog. You can also override the max releases:
+You can also override the max releases:
 
 ```{.bash filename="Terminal"}
 great-docs changelog --max-releases 10
 ```
 
+The output is written to the build directory, just as it would be during a full `great-docs build`.
+
 ## What Gets Included
 
+Not all GitHub Releases appear on the changelog page. Here is how each release type is handled:
+
 - **Published releases**: shown with their title, date, and body
 - **Pre-releases**: included but marked with a "(Pre-release)" badge
 - **Draft releases**: excluded (they aren't public yet)
 
-The release body is rendered as Markdown, so any formatting, lists, headings, or code blocks in your GitHub Release notes carry through to the documentation site.
+The release body is rendered as Markdown, so any formatting, lists, headings, or code blocks in your GitHub Release notes carry through to the documentation site. This means the changelog page looks just as rich as your release notes on GitHub.
 
 ## Generated Output
 
@@ -127,8 +133,12 @@ Here's an example of what a section looks like:
 - Removed deprecated `old_function()`
 ```
 
+The page is self-contained: readers can browse all release notes in one place without leaving your documentation site.
+
 ## Edge Cases
 
+Great Docs is designed to handle common failure scenarios gracefully. The changelog is never a hard failure; the build always completes successfully.
+
 | Scenario | Behavior |
 |---|---|
 | No GitHub URL in `pyproject.toml` | Changelog step is skipped silently |
@@ -137,12 +147,11 @@ Here's an example of what a section looks like:
 | GitHub API returns 404 | Warning printed; changelog skipped |
 | Network error | Warning printed; changelog skipped |
 
-In all cases, the build completes successfully (the changelog is never a hard failure).
-
 ## Next Steps
 
-The changelog is fully automatic: Great Docs fetches your GitHub Releases, formats them into a navigable page, and rebuilds it on every build. If you keep your release notes up to date on GitHub, your documentation site reflects them without any extra work.
+The changelog is fully automatic: Great Docs fetches your GitHub Releases, formats them into a navigable page, and regenerates it on every build. If you keep your release notes up to date on GitHub, your documentation site reflects them without any extra work.
 
-- [Configuration](configuration.qmd) covers all available `great-docs.yml` options
+- [Community Files](community-files.qmd) covers other auto-detected files like `CONTRIBUTING.md` and `ROADMAP.md`
 - [Deployment](deployment.qmd) covers publishing your docs (including the changelog) to GitHub Pages
-- [Link Checker](link-checker.qmd) explains how to validate links across your site
+- [Link Checker](link-checker.qmd) validates that changelog links to GitHub are not broken
+- [Configuration](configuration.qmd) covers all available `great-docs.yml` options