Awesome/awesome-copilot
1
0
Fork 0
mirror of https://github.com/github/awesome-copilot.git synced 2026-10-12 23:04:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Refactor Learning Hub content to reduce changelog-audit-trail noise (#3589)

Browse Source 
* Refactor Learning Hub content to reduce changelog-audit-trail noise

Follows up on the Learning Hub content audit report: automated
changelog-driven PRs had turned several evergreen guide pages into a
version-history audit trail rather than current-state documentation
(e.g. copilot-configuration-basics.md had 86 inline vX.Y.Z+ tags).

Content changes:
- copilot-configuration-basics.md, installing-and-using-plugins.md,
  building-custom-agents.md, automating-with-hooks.md, and
  understanding-mcp-servers.md: removed decorative inline version
  tags from the main teaching flow so pages read as 'how to use this
  today' rather than 'when this changed'. Genuinely actionable
  history (renames, removed flags/settings, breaking defaults) is
  consolidated into a new Compatibility and Migration Notes section
  per page instead of being scattered inline.

Automation change:
- .github/workflows/learning-hub-updater.md (+ recompiled .lock.yml):
  added a 'stale version notes' detection step, a content model that
  distinguishes evergreen guides from Compatibility and Migration
  Notes sections, consolidation rules, and a required content-cleanup
  checklist item in the PR body, so future automated updates keep
  this pattern instead of re-accumulating inline version chronology.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

* Address Learning Hub review feedback

Clarify the evergreen and compatibility section model and restore version thresholds needed for troubleshooting older CLI installations.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Aaron Powell
2026-09-23 11:25:17 +10:00
committed by GitHub
co-authored by Copilot App
parent 79eac37348
commit 1874d1b88b
7 changed files with 163 additions and 137 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/learning-hub-updater.lock.yml
Generated
+1 -1
View File
@@ -1,4 +1,4 @@
# gh-aw-metadata: {"schema_version":"v4","frontmatter_hash":"71be7bf13cd61ce7e5d48a2d2e5978e9be648bdc956d1684b2da2bca4cad11e0","body_hash":"173edcea3d4067513e6b172ab889f21a07bfa9181d38c1dfcc79617a2fa98019","compiler_version":"v0.86.2","strict":true,"agent_id":"copilot","engine_versions":{"copilot":"1.0.79"}}
# gh-aw-metadata: {"schema_version":"v4","frontmatter_hash":"71be7bf13cd61ce7e5d48a2d2e5978e9be648bdc956d1684b2da2bca4cad11e0","body_hash":"43a4718bf818e0555b685c7a173049713a294828b0753c1fa7378a3ad47120e6","compiler_version":"v0.86.2","strict":true,"agent_id":"copilot","engine_versions":{"copilot":"1.0.79"}}
# gh-aw-manifest: {"version":1,"secrets":["GH_AW_CI_TRIGGER_TOKEN","GH_AW_GITHUB_MCP_SERVER_TOKEN","GH_AW_GITHUB_TOKEN","GITHUB_TOKEN"],"actions":[{"repo":"actions/cache/restore","sha":"55cc8345863c7cc4c66a329aec7e433d2d1c52a9","version":"v6.1.0"},{"repo":"actions/cache/save","sha":"55cc8345863c7cc4c66a329aec7e433d2d1c52a9","version":"v6.1.0"},{"repo":"actions/checkout","sha":"3d3c42e5aac5ba805825da76410c181273ba90b1","version":"v7.0.1"},{"repo":"actions/download-artifact","sha":"3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c","version":"v8.0.1"},{"repo":"actions/github-script","sha":"3a2844b7e9c422d3c10d287c895573f7108da1b3","version":"v9.0.0"},{"repo":"actions/setup-node","sha":"820762786026740c76f36085b0efc47a31fe5020","version":"v7.0.0"},{"repo":"actions/upload-artifact","sha":"043fb46d1a93c77aae656e7c1c64a875d1fc6a0a","version":"v7.0.1"},{"repo":"github/gh-aw-actions/setup","sha":"6aab9e5b5c91c615506061f09bedd81a23babe3c","version":"v0.86.2"}],"containers":[{"image":"ghcr.io/github/gh-aw-firewall/agent:0.27.44","digest":"sha256:0d727725c737b58c7bdf51f640cffb928385ec46517e0917c7f1a02f1bada8b4","pinned_image":"ghcr.io/github/gh-aw-firewall/agent:0.27.44@sha256:0d727725c737b58c7bdf51f640cffb928385ec46517e0917c7f1a02f1bada8b4"},{"image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.27.44","digest":"sha256:b50fbadba138f6e9aba94aca09711335c489bb3b15861220cb66f6092e042dc7","pinned_image":"ghcr.io/github/gh-aw-firewall/api-proxy:0.27.44@sha256:b50fbadba138f6e9aba94aca09711335c489bb3b15861220cb66f6092e042dc7"},{"image":"ghcr.io/github/gh-aw-firewall/squid:0.27.44","digest":"sha256:83e48bbe12c634be8c228a576832fe45f66c529ac3659db92bddbcf2eeb6d627","pinned_image":"ghcr.io/github/gh-aw-firewall/squid:0.27.44@sha256:83e48bbe12c634be8c228a576832fe45f66c529ac3659db92bddbcf2eeb6d627"},{"image":"ghcr.io/github/gh-aw-mcpg:v0.4.9","digest":"sha256:e5a1569aeaf41820fa7bdee3e94468cae448133cdbf00119ad24f5b74db1ab9f","pinned_image":"ghcr.io/github/gh-aw-mcpg:v0.4.9@sha256:e5a1569aeaf41820fa7bdee3e94468cae448133cdbf00119ad24f5b74db1ab9f"},{"image":"ghcr.io/github/gh-aw-node","digest":"sha256:0d9f1fb5fd6610c0ac1f5194a38e45a8a1e81f8a390d5142d8e4e6f26a4b3196","pinned_image":"ghcr.io/github/gh-aw-node@sha256:0d9f1fb5fd6610c0ac1f5194a38e45a8a1e81f8a390d5142d8e4e6f26a4b3196"},{"image":"ghcr.io/github/github-mcp-server:v1.9.0","digest":"sha256:881b53d6f75f69bdbc1b5b10fc2f1361717c19054143b3a8529fb5c32061a50e","pinned_image":"ghcr.io/github/github-mcp-server:v1.9.0@sha256:881b53d6f75f69bdbc1b5b10fc2f1361717c19054143b3a8529fb5c32061a50e"}]}
# This file was automatically generated by gh-aw (v0.86.2). DO NOT EDIT. To debug this workflow, load the skill at https://github.com/github/gh-aw/blob/main/debug.md
#
.github/workflows/learning-hub-updater.md
+15 -1
View File
@@ -58,6 +58,7 @@ Identify:
- **Missing features** — new capabilities not yet documented
- **Outdated information** — features that have been renamed, deprecated, or significantly changed
- **Missing links** — new official docs or blog posts not in the Further Reading section
- **Stale version notes** — inline `vX.Y.Z+` callouts, "previously"/"as of"/"breaking change" notes, or superseded feature descriptions that are candidates for consolidation or removal now that a newer release has landed
If there is nothing new or everything is already up to date, stop here and report that no updates are needed.
@@ -65,6 +66,18 @@ If there is nothing new or everything is already up to date, stop here and repor
If updates are needed, make a decision on whether a new page needs to be added (e.g., for a major new feature) or if existing pages can be updated with new sections.
**Content model — read this before editing.** The Learning Hub distinguishes between two kinds of content, and each page should keep them clearly separated into distinct sections:
- **Evergreen guides** (most pages, e.g. `copilot-configuration-basics.md`, `building-custom-agents.md`, `installing-and-using-plugins.md`, `understanding-mcp-servers.md`, `automating-with-hooks.md`) must describe **current behavior as the primary voice** — write "Use X to do Y", not "In vA.B.C, X was added". These pages are not a changelog and must not be allowed to become one.
- **Compatibility and migration notes** are where release-specific history belongs: breaking changes, renamed settings, removed commands, and minimum-version requirements that a reader upgrading from an older version needs. Put this material in a `## Compatibility and Migration Notes` section at the bottom of the relevant page (create the section if it doesn't exist yet) instead of inline in the main teaching flow.
Prefer **consolidation over addition**:
- Before adding a new inline `(vX.Y.Z+)` note, check whether the same section already has one or more older version notes on the same setting, command, or field. If so, rewrite that passage to describe only the current behavior, and move any genuinely useful migration detail (old name, old default, what breaks) into the Compatibility and Migration Notes section.
- Do not add a new inline version tag for a feature that has been generally available for more than a couple of releases — just document it as the current behavior.
- Only keep an inline version tag when a reader must know the version to make a decision right now (e.g., "requires v1.0.80 or later").
- If a page's main teaching flow already has more than roughly 8–10 inline version tags outside of a Compatibility and Migration Notes section, treat that as a signal to do a consolidation pass on that page during this run, not just append another note.
### For new pages:
A new page should be created for major features or capabilities that warrant their own documentation (e.g., a new feature of Copilot, a new pattern for working with Copilot, etc.).
@@ -77,7 +90,7 @@ To create a new page:
### For updates to existing pages:
If the new information can be added to existing pages, edit those pages to include refinements, new sections, or updated information as needed. Make sure to update any relevant links in the "Further Reading" sections.
If the new information can be added to existing pages, edit those pages to include refinements, new sections, or updated information as needed, following the content model above. Make sure to update any relevant links in the "Further Reading" sections.
## Step 4 — Open a pull request
@@ -86,5 +99,6 @@ Create a pull request with your changes, using the `main` branch as the base bra
1. What new features or changes were found
2. What sections of the guide were updated
3. Links to the source announcements
4. **Content cleanup** — what older inline version notes were consolidated, rewritten as current behavior, or moved into a Compatibility and Migration Notes section, or a brief note that none needed changes this run
The PR should target the `main` branch and include the labels `automated-update` and `copilot-updates`.