docs: move version control section to end of chapter 1 (#911) - #935
Open
gdsmith1 wants to merge 2 commits into
Open
docs: move version control section to end of chapter 1 (#911)#935gdsmith1 wants to merge 2 commits into
gdsmith1 wants to merge 2 commits into
Conversation
- Relocate docs/6-software-development-practices/6.3-* → docs/1-introduction/1.5-* - Move 9 git-related SVGs from img6/ → img1/, rewrite image refs - Update docs/_sidebar.md: add 1.5.x to Chapter 1 tail, remove 6.3.x from Chapter 6 - Add bidirectional see-also cross-links between 1.5.3-github.md and 2-Github/2.0-overview.md - Regenerate docs/README.md via npm run refresh-front-matter Related to T5 in Spec 04
Contributor
📝 WalkthroughWalkthroughDocumentation restructuring moves version control content (Version Control, Branching & Merging, Git pages) from Chapter 6 into Chapter 1, updating image asset paths, internal references, README outline entries, and sidebar navigation accordingly. Separately, the Chapter 2 GitHub overview page content is rewritten to cover pull requests, peer reviews, forks, and alternatives. ChangesVersion Control Section Relocation to Chapter 1
GitHub Overview Content Rewrite
Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
- Delete docs/1-introduction/1.5.3-github.md - Replace docs/2-Github/2.0-overview.md chapter-goals list with the version-control-context GitHub content (intro, Pull Requests, Peer Reviews, Forks, Alternatives, Deliverable) - Drop 'Exercise: Forks and PRs' section per feedback (unnecessary) - Remove 1.5.3 sidebar entry; regenerate docs/README.md Related to T5 in Spec 04
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/1-introduction/1.5-version-control.md`:
- Around line 3-4: Standardize every listed image reference: in
docs/1-introduction/1.5-version-control.md lines 3-4,
docs/1-introduction/1.5.1-branching-merging.md lines 11-12, 43-44, and 50-51,
and docs/1-introduction/1.5.2-git.md line 150, replace Markdown image syntax
with HTML img tags and update each asset path from img1/ to the root img/ folder
while preserving the existing dimensions, classes, and alt text.
In `@docs/2-Github/2.0-overview.md`:
- Line 7: Update the section headings in 2.0-overview.md, including “Pull
Requests” and the other referenced headings, from H2 (##) to H3 (###). Preserve
the navigation table-of-contents H2 headings and all heading text.
- Line 11: Update the pull-request review sentence in the overview documentation
by changing “comment on and requests changes” to “comment on and request
changes,” without altering the surrounding content.
- Line 17: Replace the Markdown image declarations in this overview section,
including the corresponding image at the referenced second location, with HTML
img tags using the existing root img paths and accurate alt text describing pull
requests rather than “Peer Previews.”
- Line 49: Clarify the first deliverable by replacing “source repository
solutions” with wording that explicitly requests examples of repository-hosting
solutions similar to GitHub, while retaining the requirement to discuss each
option’s pros and cons.
- Line 13: Update the pull request history statement in the overview
documentation to limit retention claims to the PR conversation and metadata,
such as reviewers, approvals, status changes, and comments; remove the
unqualified promise that all details or code changes are retained, while
preserving the existing branch deletion and commit squashing context.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 9b8c6f57-484b-4505-a365-90cb06c086c6
⛔ Files ignored due to path filters (9)
docs/1-introduction/img1/git-branches_dark.svgis excluded by!**/*.svgdocs/1-introduction/img1/git-branches_light.svgis excluded by!**/*.svgdocs/1-introduction/img1/git-icon-branch_dark.svgis excluded by!**/*.svgdocs/1-introduction/img1/git-icon-branch_light.svgis excluded by!**/*.svgdocs/1-introduction/img1/git-icon-merge_dark.svgis excluded by!**/*.svgdocs/1-introduction/img1/git-icon-merge_light.svgis excluded by!**/*.svgdocs/1-introduction/img1/git-lifecycle.svgis excluded by!**/*.svgdocs/1-introduction/img1/git_dark.svgis excluded by!**/*.svgdocs/1-introduction/img1/git_light.svgis excluded by!**/*.svg
📒 Files selected for processing (7)
docs/1-introduction/1.5-version-control.mddocs/1-introduction/1.5.1-branching-merging.mddocs/1-introduction/1.5.2-git.mddocs/2-Github/2.0-overview.mddocs/6-software-development-practices/6.3.3-github.mddocs/README.mddocs/_sidebar.md
💤 Files with no reviewable changes (1)
- docs/6-software-development-practices/6.3.3-github.md
Comment on lines
+3
to
+4
|  | ||
|  |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Standardize all relocated image references.
The changed documentation continues using Markdown image syntax and img1/..., contrary to the repository rule requiring HTML <img> tags and assets in the root img/ folder.
docs/1-introduction/1.5-version-control.md#L3-L4: convert both Git image references to HTML tags and rootimg/paths.docs/1-introduction/1.5.1-branching-merging.md#L11-L12,43-L44,50-L51: convert all six branch/merge image references likewise.docs/1-introduction/1.5.2-git.md#L150-L150: convert the Git lifecycle image reference likewise.
📍 Affects 3 files
docs/1-introduction/1.5-version-control.md#L3-L4(this comment)docs/1-introduction/1.5.1-branching-merging.md#L11-L12docs/1-introduction/1.5.2-git.md#L150-L150
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/1-introduction/1.5-version-control.md` around lines 3 - 4, Standardize
every listed image reference: in docs/1-introduction/1.5-version-control.md
lines 3-4, docs/1-introduction/1.5.1-branching-merging.md lines 11-12, 43-44,
and 50-51, and docs/1-introduction/1.5.2-git.md line 150, replace Markdown image
syntax with HTML img tags and update each asset path from img1/ to the root img/
folder while preserving the existing dimensions, classes, and alt text.
Source: Coding guidelines
|
|
||
| For the most part, GitHub repositories work just like normal Git repositories. You can clone them, create and merge branches, commit changes and push them back up to GitHub. GitHub also adds a few features which are not included in Git which are worth taking note of. | ||
|
|
||
| ## Pull Requests |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Use H3 headings for document sections.
Change these ## headings to ###; H2 headings are reserved for the navigation table of contents.
Proposed fix
-## Pull Requests
+### Pull Requests
-## Forks
+### Forks
-## GitHub Alternatives
+### GitHub Alternatives
-## Deliverable
+### DeliverableAs per coding guidelines, docs/**/*.md pages should use H3 headers by default, with H2 reserved for navigation table of contents.
Also applies to: 35-35, 41-41, 45-45
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/2-Github/2.0-overview.md` at line 7, Update the section headings in
2.0-overview.md, including “Pull Requests” and the other referenced headings,
from H2 (##) to H3 (###). Preserve the navigation table-of-contents H2 headings
and all heading text.
Source: Coding guidelines
|
|
||
| A pull request (PR) is a process to review and approve changes from one branch before they are merged into another. A pull request can be created from one branch to another (usually a main branch) in the same repository or from a forked repository (see below) to its source. | ||
|
|
||
| After a pull request is created in GitHub it can be reviewed by viewing a side-by-side comparison of code being added and removed. It allows for people to comment on and requests changes to specific sections of code. People can be requested to review changes or rules can be set up to require reviews from specific people or a minimum number of reviews before a pull request is approved. Once a pull request is approved it can be merged and closed. |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix the pull-request review grammar.
Change “comment on and requests changes” to “comment on and request changes.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/2-Github/2.0-overview.md` at line 11, Update the pull-request review
sentence in the overview documentation by changing “comment on and requests
changes” to “comment on and request changes,” without altering the surrounding
content.
|
|
||
| After a pull request is created in GitHub it can be reviewed by viewing a side-by-side comparison of code being added and removed. It allows for people to comment on and requests changes to specific sections of code. People can be requested to review changes or rules can be set up to require reviews from specific people or a minimum number of reviews before a pull request is approved. Once a pull request is approved it can be merged and closed. | ||
|
|
||
| ?> Pull request history persists on the Git server. Branches will be deleted and commits may be squashed, but the PR will persist to provide transparency on changes. All details will be retained, including code changes, reviewers and approvals, status changes, and comments. |
Contributor
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Qualify the “all details” retention claim.
The callout says all details are retained while also noting that branches can be deleted and commits squashed. Limit the guarantee to the pull request’s conversation and metadata instead of promising immutable commit history.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/2-Github/2.0-overview.md` at line 13, Update the pull request history
statement in the overview documentation to limit retention claims to the PR
conversation and metadata, such as reviewers, approvals, status changes, and
comments; remove the unqualified promise that all details or code changes are
retained, while preserving the existing branch deletion and commit squashing
context.
|
|
||
| ### Peer Reviews: A Sacred Space for Developers | ||
|
|
||
|  |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Use HTML images with accurate alternative text.
These Markdown image declarations violate the documentation convention, and the alt text is inaccurate (Peer Previews is a typo; the second image describes pull requests rather than peer reviews).
Proposed fix
-
+<img src="../../img/git-pr.webp" alt="Pull request review" class="img-center">
-
+<img src="../../img/git-peer-review.webp" alt="Peer review" class="img-shadow-center">As per coding guidelines, documentation images should use HTML <img> tags; these paths already point to the root img/ folder.
Also applies to: 23-23
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/2-Github/2.0-overview.md` at line 17, Replace the Markdown image
declarations in this overview section, including the corresponding image at the
referenced second location, with HTML img tags using the existing root img paths
and accurate alt text describing pull requests rather than “Peer Previews.”
Source: Coding guidelines
|
|
||
| Be familiar with GitHub's features. | ||
|
|
||
| Find additional examples to source repository solutions similar to GitHub and discuss the pros and cons of each. |
Contributor
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Clarify the first deliverable.
“Source repository solutions” is ambiguous. Consider “Find additional examples of repository-hosting solutions similar to GitHub and discuss the pros and cons of each.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/2-Github/2.0-overview.md` at line 49, Clarify the first deliverable by
replacing “source repository solutions” with wording that explicitly requests
examples of repository-hosting solutions similar to GitHub, while retaining the
requirement to discuss each option’s pros and cons.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What Changed
docs/6-software-development-practices/6.3-*→docs/1-introduction/1.5-*(3 markdown files, 9 SVG assets).1.5.3-github.mdcontent intodocs/2-Github/2.0-overview.md, replacing its Chapter Goals list. Dropped the "Exercise: Forks and PRs" section (unnecessary).docs/_sidebar.md: added1.5 Version Control+1.5.1 Branching & Merging+1.5.2 Gitto Chapter 1 tail; removed6.3block from Chapter 6.img6/git*.svg→img1/git*.svg) and front-matter path labels.docs/README.mdvianpm run refresh-front-matter.Why
Version control is foundational and belongs before learners hit chapters that assume Git literacy. Moving it to the end of Chapter 1 puts it in the intro block with CLI/env/networking basics.
The
1.5.3-github.md→ Chapter 2 merge collapses duplicated framing: Chapter 2 previously opened with a bare goals list; the moved content (intro paragraph, Pull Requests, Peer Reviews, Forks, Alternatives, Deliverable) now leads Chapter 2 directly, so learners get the "what is GitHub" narrative once, at the head of the deep-dive chapter.Closes #911.
Swap Decision
Kept lesson order (
Version Control → Branching & Merging → Git). Rationale: current order introduces the concept first, then branching/merging as abstract patterns, then the tool (Git). Swapping git↔branching would surface Git CLI mechanics before the reader has a mental model of what branching is for.GitHub-platform coverage now lives entirely in Chapter 2 (no
1.5.3— merged in).GitHub Chapter Overlap
Resolved by merge: the previous
1.5.3-github.mdcontent became the new head ofdocs/2-Github/2.0-overview.md, replacing the Chapter Goals list. No duplication remains — GitHub-as-platform is covered once.Fork exercise dropped per review feedback.
Verification
grep -rnE '6\.3-|6-software-development-practices/6\.3' docs/ --include='*.md'addendum/chef.mdfalse-positive (unrelated6.3-chef.mdstring)grep -rn '1\.5\.3|1.5.3-github' docs/ --include='*.md'refresh-front-mattersed -n '11,25p;83,100p' docs/_sidebar.md1.5,1.5.1,1.5.2in Ch1 tail;6.3.xabsent from Ch6npm run lintSummary: 0 issues in 0 files(172 files)npm run refresh-front-matterdocs/README.mdregenerated cleanlygit status -sR— history preservednpm start+ click-throughDocsify Click-Test Checklist (reviewer)
Please run
npm startand confirm:1.5 Version Controland its 2 sub-entries (1.5.1,1.5.2)1.5 Version Controlpage renders, both git SVGs load1.5.1 Branching & Mergingpage renders, all 3 branching SVGs load1.5.2 Gitpage renders,git-lifecycle.svgloads2.0 GitHubpage renders the new merged content (intro → PRs → Peer Reviews → Forks → Alternatives → Deliverable); peer-review WebP images load6.3— jumps from6.2 Jirato6.4 Pair ProgrammingSpec
docs/specs/04-spec-issues-and-deps-cleanup— Task 5.0