Skip to content

Point README at the published docs instead of restating them - #3

Merged
darthwillis merged 1 commit into
mainfrom
readme-dedupe-live-docs
Oct 1, 2026
Merged

darthwillis merged 1 commit into
mainfrom
readme-dedupe-live-docs

Conversation

@darthwillis

@darthwillis darthwillis commented Sep 29, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

The Integrating custom properties with an external system guide is now live. It covers what external custom properties are, display names and namespacing, the permission model, and installation behavior — and it links to this repository as the example implementation.

That establishes the division this PR applies: the docs own the concepts and setup, this README owns configuring and running the server.

What changed

Five areas restated GitHub behavior that the published docs now own. The concern isn't length, it's that each was an independent statement of platform behavior that can drift as the feature changes.

Section Change
Intro Condensed from three paragraphs to two. Two of the three duplicated the guide's lead — one restating its intro: frontmatter, the other its external-properties-intro reusable, down to the same examples (ownership, service tier, compliance status).
How it works: namespaces and registration Removed. Replaced with a pointer to the guide.
Permissions and who registers Collapsed to the choice this sample makes (Admin, self-registering), linking to Selecting permissions. Dropped the 6-row endpoint/permission table — the REST reference documents the required permission on each endpoint page.
Step 5: Install the App Removed the repository-access explanation, linked to Install the app.
Step 3 — DISPLAY_NAME Replaced the inline "1–15 alphanumeric characters" rule with a link to the registration endpoint, which documents the rules next to the validation errors they produce.

That last one is the clearest example of the risk: the REST reference gained an authoritative statement of those rules the same day, so the README was a second, independently-maintained copy.

API Reference table

The table previously listed all six endpoints with links to their REST reference pages — the same six endpoints, with the same links, that the guide already lists under Create the automation.

Rather than delete it, the table now pairs each endpoint with the helper function in example-server/app.js that calls it, and the endpoint path itself carries the reference link:

Endpoint Helper function
POST /orgs/{org}/properties/installations registerNamespace
GET /orgs/{org}/properties/installations getRegisteredInstallations
GET /orgs/{org}/properties/installations/schema readOrgSchema
PATCH /orgs/{org}/properties/installations/values writeExternalCustomProperties
PATCH /orgs/{org}/properties/installations/values/{property_name} updateExternalCustomPropertyValues
DELETE /orgs/{org}/properties/installations/values/{property_name} deleteExternalCustomPropertyValues

This keeps the reference one click away while making the column that remains something only this repository can provide. It also makes the README's existing claim that "each endpoint maps to a helper function" navigable rather than asserted.

324 → 265 lines.

What deliberately did not change

All sample-specific content is untouched: Smee proxy setup, credential and .env configuration, npm install and the two-terminal run, expected terminal output, the helper function inventory, and webhook troubleshooting.

Prerequisites was also left alone. It shares a heading with the guide's Prerequisites, but the content doesn't overlap — the guide describes the people and roles involved, while this describes local tooling (Node 24, an organization, a webhook proxy).

Verification

  • All 16 internal anchors resolve, and the table of contents matches the headings exactly
  • All 11 distinct docs.github.com anchors referenced were confirmed present on the live pages
  • Each endpoint-to-anchor pairing in the table was checked against x-github-internal.path and http-method in the operation definitions, not matched by path alone — two rows share a path and differ only by method (PATCH vs DELETE on …/values/{property_name})
  • All six helper function names were confirmed to exist in app.js, and all six endpoint strings confirmed to be requested there
  • npm run lint clean, 21/21 tests pass

One anchor broke during editing and was caught by the anchor check: Step 2 referenced the removed #write-only-apps-org-admin-controlled-namespacing subsection. It now points at the guide instead.

@darthwillis
darthwillis force-pushed the readme-dedupe-live-docs branch from 24625a5 to dba8ccf Compare September 29, 2026 21:15
@darthwillis
darthwillis marked this pull request as ready for review September 29, 2026 21:15
@darthwillis
darthwillis requested a review from a team as a code owner September 29, 2026 21:15
@darthwillis
darthwillis requested review from isaacmbrown and joshbanks14 and a balanced review from Copilot and removed request for a team and Copilot September 29, 2026 21:15

@isaacmbrown isaacmbrown left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Much cleaner, thanks for doing this! 🚀

Comment thread README.md
Comment thread README.md Outdated
Copilot AI balanced review requested due to automatic review settings September 30, 2026 16:31

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

Removing the permissions subsection leaves a runtime error message pointing users to documentation that no longer exists.

Review effort: Balanced
Findings: 1 Medium severity

Open (1)
What changed in this PR

Refocuses the README on configuring and running the sample server while linking to authoritative GitHub Docs for platform behavior.

Changes:

  • Removes duplicated conceptual and permission documentation.
  • Links setup details and constraints to published documentation.
  • Maps REST endpoints to sample helper functions.
File Description
README.md Streamlines guidance and adds authoritative documentation links.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread README.md

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

The API reference summary inaccurately implies every endpoint entry documents all listed constraints and behaviors.

Review effort: Balanced
Findings: 1 Low severity

Open (1)
Resolved since last review (1)

Comment thread README.md Outdated
The "Integrating custom properties with an external system" guide is now live
on docs.github.com and covers what external custom properties are, display
names and namespacing, the permission model, and installation behavior. That
guide also links here as the example implementation, so this README should
cover configuring and running the server rather than re-explaining the feature.

Several sections restated GitHub behavior the docs now own, which meant they
could drift out of sync as the feature changes:

- Condensed the intro. Two of its three paragraphs duplicated the guide's
  lead, one restating its intro frontmatter and the other its
  external-properties-intro reusable, down to the same examples.
- Removed "How it works: namespaces and registration" in favor of a pointer
  to the guide.
- Collapsed "Permissions and who registers" to the choice this sample makes,
  linking to Selecting permissions for the full model.
- Trimmed the repository-access explanation from Step 5, linking to Install
  the app.
- Replaced the inline display name length and character rules with a link to
  the registration endpoint, which documents them alongside the validation
  errors they produce.

The API Reference table previously repeated the endpoint list already in the
guide. Each endpoint now links to its own REST reference anchor and is paired
with the helper function in app.js that calls it, which is information only
this repository can provide. Permission links point at the programmatically
maintained permissions reference, which also documents the token types each
endpoint accepts.

Removing the "Write-only apps" section broke the 403 handler in
registerNamespace, which directed users to it by name. That runtime guidance
now links to the published guide, and the remaining "write-only app" phrasing
is replaced with "Read and write" to match the permission level the UI shows.

Sample-specific content is unchanged: Smee setup, credentials, running the
server, expected terminal output, the helper function inventory, and webhook
troubleshooting. Prerequisites was also left in place; it shares a heading
with the guide but covers local tooling rather than the people and roles
involved.

Verified all 16 internal anchors resolve, the table of contents matches the
headings, and every docs.github.com anchor referenced is live. Each endpoint
to anchor pairing was checked against the x-github-internal path and
http-method in the operation definitions. Lint and all 21 tests pass.

324 to 265 lines.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 97372c67-02e2-4b8b-a713-1d9e9c42f6ca

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟢 Approval recommended

The documentation links, endpoint mappings, terminology, and runtime guidance are consistent and complete.

Review effort: Balanced
Findings: None

Resolved since last review (1)

@joshbanks14 joshbanks14 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

@darthwillis
darthwillis merged commit 7058a18 into main Oct 1, 2026
6 checks passed
@darthwillis
darthwillis deleted the readme-dedupe-live-docs branch October 1, 2026 12:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants