Skip to content

docs: describe save_file's real sequence in the Python README #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
dmccoystephenson merged 1 commit into from
Sep 26, 2026
Merged

docs: describe save_file's real sequence in the Python README #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 11 additions & 6 deletions python/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,17 +60,22 @@ print(result.created) # False when it added to an existing open PR

## What a save actually does

1. Look up the repository's default branch and its current tip SHA.
2. Ensure the per-file branch `docs-edit/<slugified-path>` exists, branching it
off the default branch if it does not.
3. PUT the new content to that branch through the Contents API — one commit,
carrying the file's current SHA *on that branch* so the API updates rather
than rejecting the write as a conflicting create.
1. Look up the repository's default branch.
2. Ensure the per-file branch `docs-edit/<slugified-path>` exists. If it does
not, look up the default branch's current tip SHA and branch it off that.
3. Read the file's current SHA *on that branch*, then PUT the new content to
that branch through the Contents API — one commit, carrying that SHA so the
API updates rather than rejecting the write as a conflicting create.
4. Reuse the open PR for that branch if there is one, else open a new one.

Step 4 is what makes repeated saves *update*. The pull request is the review
mechanism, which is why there is no diff or version UI to build.

Step 3 also means a save edits a file that already exists. A path with no file
on the branch fails that read, and `save_file` raises `GitHubDocsError` with
`.status` 404 before anything is committed — though a per-file branch created
in step 2 is left behind.

The default branch is never written to. That is the whole point: a doc repo
whose history already goes through review for every change should not grow a
side door just because the edit arrived from a web form.
Expand Down
7 changes: 4 additions & 3 deletions python/src/github_docs/client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,10 +15,11 @@

Flow for a save (see :meth:`GitHubDocsClient.save_file`):

1. Look up the repository's default branch and its current tip SHA.
1. Look up the repository's default branch.
2. Ensure a per-file branch ``<prefix><slugified-path>`` exists, branched off
the default branch if it does not yet.
3. PUT the new file content to that branch via the Contents API (one commit).
the default branch's current tip if it does not yet.
3. Read the file's current SHA on that branch, then PUT the new file content
to that branch via the Contents API (one commit).
4. Reuse an existing open PR for that branch if one exists, else open a new
one. This is what makes repeated saves to the same file *update* rather
than pile up duplicate PRs: the PR itself is the review mechanism, so no
Expand Down
Loading