From 7cefad6e0542bedac5b43ba1b120fac2711798ad Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Mar 2026 15:06:59 +0000 Subject: [PATCH 01/17] Add CLAUDE.md with project guidance for Claude Code https://claude.ai/code/session_011MhF8iWLG3rS5jturtiTZ5 --- CLAUDE.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..e9da4ddd9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,49 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +This is the source repository for **Pro Git, Second Edition** — the official Git book published at https://git-scm.com/book. Content is written in AsciiDoc and built into HTML, PDF, EPUB, Mobi, and FB2 formats using Ruby-based tooling (Asciidoctor). + +## Build Commands + +Requires Ruby 3.1+ and Bundler. Install dependencies first with `bundle install`. + +```bash +bundle exec rake book:build # Build all formats (HTML, EPUB, FB2, Mobi, PDF) +bundle exec rake book:build_html # Build HTML only (fastest, outputs progit.html) +bundle exec rake book:build_epub # Build EPUB only (outputs progit.epub) +bundle exec rake book:build_pdf # Build PDF only (slow, outputs progit.pdf) +bundle exec rake book:build_mobi # Build Mobi/KF8 (outputs progit.mobi) +bundle exec rake book:build_fb2 # Build FB2 (outputs progit.fb2.zip) +bundle exec rake book:clean # Remove all generated files +``` + +## Validation / Testing + +There are no unit tests. Validation checks the generated output formats: + +```bash +bundle exec rake book:check # Builds HTML + EPUB, then runs htmlproofer and epubcheck +``` + +CI runs `bundle exec rake book:build` on pull requests to main. + +## Architecture + +**Entry point:** `progit.asc` — the master document that includes all chapters via AsciiDoc `include::` directives. + +**Content structure:** Each chapter lives in `book/NN-chapter-name/` with a main `.asc` file and a `sections/` subdirectory containing individual topic files. Chapter-level include files (`ch01-getting-started.asc`, etc.) sit at the root and bridge `progit.asc` to the `book/` subdirectories. + +**Themes:** Output format styling is in `theme/` with subdirectories per format (`html/`, `epub/`, `pdf/`, `mobi/`), each containing XSL and CSS files. + +**Images:** Diagrams are in `images/` (PNG/SVG). Source designs are in `diagram-source/progit.sketch`. New figures should be added as pages in the Sketch file, exported at 800w. + +**Build system:** `Rakefile` defines all build tasks. It auto-generates `book/contributors.txt` from git history and embeds version/date info from git tags into builds. + +## Content Guidelines + +- Content is licensed CC-BY-NC-SA-3.0. Contributors agree to this license via PR. +- Small corrections (errata, clarifications) are accepted directly. Large rewrites require an issue for discussion first — professional copy editors have already reviewed the content. +- The book has 10 chapters (01–10), plus 3 appendices (A, B, C). From 26d8cf65238fe6d3b669faed752cdb6bd2b9c65c Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Mar 2026 15:16:04 +0000 Subject: [PATCH 02/17] Add licensing and attribution notes for derivative work https://claude.ai/code/session_011MhF8iWLG3rS5jturtiTZ5 --- 00-notes/licensing-and-attribution.md | 40 +++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 00-notes/licensing-and-attribution.md diff --git a/00-notes/licensing-and-attribution.md b/00-notes/licensing-and-attribution.md new file mode 100644 index 000000000..8fae1cd9b --- /dev/null +++ b/00-notes/licensing-and-attribution.md @@ -0,0 +1,40 @@ +# Licensing & Attribution Notes + +## License: CC-BY-NC-SA-3.0 + +Pro Git, 2nd Edition is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported. This license explicitly allows derivative works under three conditions: + +### 1. Attribution (BY) + +- Credit Scott Chacon and Ben Straub as the original authors +- Link to the original: https://git-scm.com/book/en/v2 +- Indicate that changes were made (rewritten for UX designers, new sections added, etc.) + +### 2. NonCommercial (NC) + +- Cannot use the material for commercial purposes (no selling, no paid courses/products) +- Free distribution, personal use, and educational contexts are fine +- Contact the authors directly for any commercial arrangement + +### 3. ShareAlike (SA) + +- This derivative work must be released under the same license (CC-BY-NC-SA-3.0) or a compatible one +- Cannot make the adapted version more restrictive +- Others may in turn adapt this version under the same terms + +## No Permission Required + +- The CC license pre-authorizes derivative works; no need to ask permission +- The CONTRIBUTING.md rules (open an issue, PR grants rights to @ben and @schacon) apply to contributions back to the original repo, not to independent derivative works +- Letting the authors know is a courteous gesture but not a legal requirement + +## Suggested Attribution Block + +Include in the adapted book's front matter: + +> *Based on Pro Git, 2nd Edition by Scott Chacon and Ben Straub (https://git-scm.com/book/en/v2). Adapted with design-specific examples and content for UX designers. This adaptation is licensed under CC-BY-NC-SA-3.0. Changes were made from the original work.* + +## Original Author Contact (from CITATION.cff) + +- Scott Chacon — schacon@gmail.com +- Ben Straub — ben@straub.cc From 0b2a09287cbec8ad7fbfa76b9e9e64f1ed2e7e21 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Mar 2026 15:18:08 +0000 Subject: [PATCH 03/17] Add working directory convention to CLAUDE.md https://claude.ai/code/session_011MhF8iWLG3rS5jturtiTZ5 --- CLAUDE.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index e9da4ddd9..a09b359ff 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,6 +2,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. +## Working Directory + +All new files and notes go into the `00-notes/` directory unless explicitly told otherwise. + ## Project Overview This is the source repository for **Pro Git, Second Edition** — the official Git book published at https://git-scm.com/book. Content is written in AsciiDoc and built into HTML, PDF, EPUB, Mobi, and FB2 formats using Ruby-based tooling (Asciidoctor). From b552a96c9e62372da03dcb648932539fbffd1787 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Mar 2026 15:22:23 +0000 Subject: [PATCH 04/17] Add ASCII tree view of original Pro Git table of contents https://claude.ai/code/session_011MhF8iWLG3rS5jturtiTZ5 --- 00-notes/original-toc.md | 138 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 138 insertions(+) create mode 100644 00-notes/original-toc.md diff --git a/00-notes/original-toc.md b/00-notes/original-toc.md new file mode 100644 index 000000000..6d3d6455f --- /dev/null +++ b/00-notes/original-toc.md @@ -0,0 +1,138 @@ +# Pro Git, 2nd Edition — Original Table of Contents + +``` +Pro Git +├── License +├── Preface by Scott Chacon +├── Preface by Ben Straub +├── Dedication +├── Contributors +├── Introduction +│ +├── Ch 1: Getting Started +│ ├── About Version Control +│ ├── A Short History of Git +│ ├── What is Git? +│ ├── The Command Line +│ ├── Installing Git +│ ├── First-Time Git Setup +│ ├── Getting Help +│ └── Summary +│ +├── Ch 2: Git Basics +│ ├── Getting a Git Repository +│ ├── Recording Changes to the Repository +│ ├── Viewing the Commit History +│ ├── Undoing Things +│ ├── Working with Remotes +│ ├── Tagging +│ ├── Git Aliases +│ └── Summary +│ +├── Ch 3: Git Branching +│ ├── Branches in a Nutshell +│ ├── Basic Branching and Merging +│ ├── Branch Management +│ ├── Branching Workflows +│ ├── Remote Branches +│ ├── Rebasing +│ └── Summary +│ +├── Ch 4: Git on the Server +│ ├── The Protocols +│ ├── Getting Git on a Server +│ ├── Generating Your SSH Public Key +│ ├── Setting Up the Server +│ ├── Git Daemon +│ ├── Smart HTTP +│ ├── GitWeb +│ ├── GitLab +│ ├── Third Party Hosted Options +│ └── Summary +│ +├── Ch 5: Distributed Git +│ ├── Distributed Workflows +│ ├── Contributing to a Project +│ ├── Maintaining a Project +│ └── Summary +│ +├── Ch 6: GitHub +│ ├── Account Setup and Configuration +│ ├── Contributing to a Project +│ ├── Maintaining a Project +│ ├── Managing an Organization +│ ├── Scripting GitHub +│ └── Summary +│ +├── Ch 7: Git Tools +│ ├── Revision Selection +│ ├── Interactive Staging +│ ├── Stashing and Cleaning +│ ├── Signing Your Work +│ ├── Searching +│ ├── Rewriting History +│ ├── Reset Demystified +│ ├── Advanced Merging +│ ├── Rerere +│ ├── Debugging with Git +│ ├── Submodules +│ ├── Bundling +│ ├── Replace +│ ├── Credential Storage +│ └── Summary +│ +├── Ch 8: Customizing Git +│ ├── Git Configuration +│ ├── Git Attributes +│ ├── Git Hooks +│ ├── An Example Git-Enforced Policy +│ └── Summary +│ +├── Ch 9: Git and Other Systems +│ ├── Git as a Client +│ ├── Migrating to Git +│ └── Summary +│ +├── Ch 10: Git Internals +│ ├── Plumbing and Porcelain +│ ├── Git Objects +│ ├── Git References +│ ├── Packfiles +│ ├── The Refspec +│ ├── Transfer Protocols +│ ├── Maintenance and Data Recovery +│ ├── Environment Variables +│ └── Summary +│ +├── Appendix A: Git in Other Environments +│ ├── Graphical Interfaces +│ ├── Git in Visual Studio +│ ├── Git in Visual Studio Code +│ ├── Git in IntelliJ / PyCharm / WebStorm / PhpStorm / RubyMine +│ ├── Git in Sublime Text +│ ├── Git in Bash +│ ├── Git in Zsh +│ ├── Git in PowerShell +│ └── Summary +│ +├── Appendix B: Embedding Git in your Applications +│ ├── Command-line Git +│ ├── Libgit2 +│ ├── JGit +│ ├── go-git +│ └── Dulwich +│ +└── Appendix C: Git Commands + ├── Setup and Config + ├── Getting and Creating Projects + ├── Basic Snapshotting + ├── Branching and Merging + ├── Sharing and Updating Projects + ├── Inspection and Comparison + ├── Debugging + ├── Patching + ├── Email + ├── External Systems + ├── Administration + └── Plumbing Commands +``` From b48680746c0ae95df47e07090c0b611cb6b61c64 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 8 Mar 2026 17:32:00 +0000 Subject: [PATCH 05/17] Add per-chapter ASCII tree TOC files for all chapters and appendices 13 files covering Ch 1-10 and Appendices A-C, each with full section and sub-section hierarchy in tree format. https://claude.ai/code/session_011MhF8iWLG3rS5jturtiTZ5 --- ...oc-appendix-a-git-in-other-environments.md | 26 ++++++ 00-notes/toc-appendix-b-embedding-git.md | 24 ++++++ 00-notes/toc-appendix-c-git-commands.md | 76 ++++++++++++++++++ 00-notes/toc-ch01-getting-started.md | 36 +++++++++ 00-notes/toc-ch02-git-basics.md | 50 ++++++++++++ 00-notes/toc-ch03-git-branching.md | 35 ++++++++ 00-notes/toc-ch04-git-on-the-server.md | 34 ++++++++ 00-notes/toc-ch05-distributed-git.md | 32 ++++++++ 00-notes/toc-ch06-github.md | 42 ++++++++++ 00-notes/toc-ch07-git-tools.md | 79 +++++++++++++++++++ 00-notes/toc-ch08-customizing-git.md | 28 +++++++ 00-notes/toc-ch09-git-and-other-systems.md | 17 ++++ 00-notes/toc-ch10-git-internals.md | 44 +++++++++++ 13 files changed, 523 insertions(+) create mode 100644 00-notes/toc-appendix-a-git-in-other-environments.md create mode 100644 00-notes/toc-appendix-b-embedding-git.md create mode 100644 00-notes/toc-appendix-c-git-commands.md create mode 100644 00-notes/toc-ch01-getting-started.md create mode 100644 00-notes/toc-ch02-git-basics.md create mode 100644 00-notes/toc-ch03-git-branching.md create mode 100644 00-notes/toc-ch04-git-on-the-server.md create mode 100644 00-notes/toc-ch05-distributed-git.md create mode 100644 00-notes/toc-ch06-github.md create mode 100644 00-notes/toc-ch07-git-tools.md create mode 100644 00-notes/toc-ch08-customizing-git.md create mode 100644 00-notes/toc-ch09-git-and-other-systems.md create mode 100644 00-notes/toc-ch10-git-internals.md diff --git a/00-notes/toc-appendix-a-git-in-other-environments.md b/00-notes/toc-appendix-a-git-in-other-environments.md new file mode 100644 index 000000000..ad08e3ac6 --- /dev/null +++ b/00-notes/toc-appendix-a-git-in-other-environments.md @@ -0,0 +1,26 @@ +# Appendix A: Git in Other Environments + +``` +Git in Other Environments +├── Graphical Interfaces +│ ├── gitk and git-gui +│ ├── GitHub for macOS and Windows +│ └── Other GUIs +│ +├── Git in Visual Studio +│ +├── Git in Visual Studio Code +│ +├── Git in IntelliJ / PyCharm / WebStorm / PhpStorm / RubyMine +│ +├── Git in Sublime Text +│ +├── Git in Bash +│ +├── Git in Zsh +│ +├── Git in PowerShell +│ └── Installation +│ +└── Summary +``` diff --git a/00-notes/toc-appendix-b-embedding-git.md b/00-notes/toc-appendix-b-embedding-git.md new file mode 100644 index 000000000..14117c8f5 --- /dev/null +++ b/00-notes/toc-appendix-b-embedding-git.md @@ -0,0 +1,24 @@ +# Appendix B: Embedding Git in your Applications + +``` +Embedding Git in your Applications +├── Command-line Git +│ +├── Libgit2 +│ ├── Advanced Functionality +│ ├── Other Bindings +│ └── Further Reading +│ +├── JGit +│ ├── Getting Set Up +│ ├── Plumbing +│ ├── Porcelain +│ └── Further Reading +│ +├── go-git +│ ├── Advanced Functionality +│ └── Further Reading +│ +└── Dulwich + └── Further Reading +``` diff --git a/00-notes/toc-appendix-c-git-commands.md b/00-notes/toc-appendix-c-git-commands.md new file mode 100644 index 000000000..345584ccf --- /dev/null +++ b/00-notes/toc-appendix-c-git-commands.md @@ -0,0 +1,76 @@ +# Appendix C: Git Commands + +``` +Git Commands +├── Setup and Config +│ ├── git config +│ ├── git config core.editor commands +│ └── git help +│ +├── Getting and Creating Projects +│ ├── git init +│ └── git clone +│ +├── Basic Snapshotting +│ ├── git add +│ ├── git status +│ ├── git diff +│ ├── git difftool +│ ├── git commit +│ ├── git reset +│ ├── git rm +│ ├── git mv +│ └── git clean +│ +├── Branching and Merging +│ ├── git branch +│ ├── git checkout +│ ├── git merge +│ ├── git mergetool +│ ├── git log +│ ├── git stash +│ └── git tag +│ +├── Sharing and Updating Projects +│ ├── git fetch +│ ├── git pull +│ ├── git push +│ ├── git remote +│ ├── git archive +│ └── git submodule +│ +├── Inspection and Comparison +│ ├── git show +│ ├── git shortlog +│ └── git describe +│ +├── Debugging +│ ├── git bisect +│ ├── git blame +│ └── git grep +│ +├── Patching +│ ├── git cherry-pick +│ ├── git rebase +│ └── git revert +│ +├── Email +│ ├── git apply +│ ├── git am +│ ├── git format-patch +│ ├── git imap-send +│ ├── git send-email +│ └── git request-pull +│ +├── External Systems +│ ├── git svn +│ └── git fast-import +│ +├── Administration +│ ├── git gc +│ ├── git fsck +│ ├── git reflog +│ └── git filter-branch +│ +└── Plumbing Commands +``` diff --git a/00-notes/toc-ch01-getting-started.md b/00-notes/toc-ch01-getting-started.md new file mode 100644 index 000000000..f2ad59b76 --- /dev/null +++ b/00-notes/toc-ch01-getting-started.md @@ -0,0 +1,36 @@ +# Ch 1: Getting Started + +``` +Getting Started +├── About Version Control +│ ├── Local Version Control Systems +│ ├── Centralized Version Control Systems +│ └── Distributed Version Control Systems +│ +├── A Short History of Git +│ +├── What is Git? +│ ├── Snapshots, Not Differences +│ ├── Nearly Every Operation Is Local +│ ├── Git Has Integrity +│ ├── Git Generally Only Adds Data +│ └── The Three States +│ +├── The Command Line +│ +├── Installing Git +│ ├── Installing on Linux +│ ├── Installing on macOS +│ ├── Installing on Windows +│ └── Installing from Source +│ +├── First-Time Git Setup +│ ├── Your Identity +│ ├── Your Editor +│ ├── Your default branch name +│ └── Checking Your Settings +│ +├── Getting Help +│ +└── Summary +``` diff --git a/00-notes/toc-ch02-git-basics.md b/00-notes/toc-ch02-git-basics.md new file mode 100644 index 000000000..aafde7804 --- /dev/null +++ b/00-notes/toc-ch02-git-basics.md @@ -0,0 +1,50 @@ +# Ch 2: Git Basics + +``` +Git Basics +├── Getting a Git Repository +│ ├── Initializing a Repository in an Existing Directory +│ └── Cloning an Existing Repository +│ +├── Recording Changes to the Repository +│ ├── Checking the Status of Your Files +│ ├── Tracking New Files +│ ├── Staging Modified Files +│ ├── Short Status +│ ├── Ignoring Files +│ ├── Viewing Your Staged and Unstaged Changes +│ ├── Committing Your Changes +│ ├── Skipping the Staging Area +│ ├── Removing Files +│ └── Moving Files +│ +├── Viewing the Commit History +│ └── Limiting Log Output +│ +├── Undoing Things +│ ├── Unstaging a Staged File +│ ├── Unmodifying a Modified File +│ └── Undoing things with git restore +│ +├── Working with Remotes +│ ├── Showing Your Remotes +│ ├── Adding Remote Repositories +│ ├── Fetching and Pulling from Your Remotes +│ ├── Pushing to Your Remotes +│ ├── Inspecting a Remote +│ └── Renaming and Removing Remotes +│ +├── Tagging +│ ├── Listing Your Tags +│ ├── Creating Tags +│ ├── Annotated Tags +│ ├── Lightweight Tags +│ ├── Tagging Later +│ ├── Sharing Tags +│ ├── Deleting Tags +│ └── Checking out Tags +│ +├── Git Aliases +│ +└── Summary +``` diff --git a/00-notes/toc-ch03-git-branching.md b/00-notes/toc-ch03-git-branching.md new file mode 100644 index 000000000..3f5d1442a --- /dev/null +++ b/00-notes/toc-ch03-git-branching.md @@ -0,0 +1,35 @@ +# Ch 3: Git Branching + +``` +Git Branching +├── Branches in a Nutshell +│ ├── Creating a New Branch +│ └── Switching Branches +│ +├── Basic Branching and Merging +│ ├── Basic Branching +│ ├── Basic Merging +│ └── Basic Merge Conflicts +│ +├── Branch Management +│ └── Changing a branch name +│ +├── Branching Workflows +│ ├── Long-Running Branches +│ └── Topic Branches +│ +├── Remote Branches +│ ├── Pushing +│ ├── Tracking Branches +│ ├── Pulling +│ └── Deleting Remote Branches +│ +├── Rebasing +│ ├── The Basic Rebase +│ ├── More Interesting Rebases +│ ├── The Perils of Rebasing +│ ├── Rebase When You Rebase +│ └── Rebase vs. Merge +│ +└── Summary +``` diff --git a/00-notes/toc-ch04-git-on-the-server.md b/00-notes/toc-ch04-git-on-the-server.md new file mode 100644 index 000000000..ef6fecb64 --- /dev/null +++ b/00-notes/toc-ch04-git-on-the-server.md @@ -0,0 +1,34 @@ +# Ch 4: Git on the Server + +``` +Git on the Server +├── The Protocols +│ ├── Local Protocol +│ ├── The HTTP Protocols +│ ├── The SSH Protocol +│ └── The Git Protocol +│ +├── Getting Git on a Server +│ ├── Putting the Bare Repository on a Server +│ └── Small Setups +│ +├── Generating Your SSH Public Key +│ +├── Setting Up the Server +│ +├── Git Daemon +│ +├── Smart HTTP +│ +├── GitWeb +│ +├── GitLab +│ ├── Installation +│ ├── Administration +│ ├── Basic Usage +│ └── Working Together +│ +├── Third Party Hosted Options +│ +└── Summary +``` diff --git a/00-notes/toc-ch05-distributed-git.md b/00-notes/toc-ch05-distributed-git.md new file mode 100644 index 000000000..1a6432e26 --- /dev/null +++ b/00-notes/toc-ch05-distributed-git.md @@ -0,0 +1,32 @@ +# Ch 5: Distributed Git + +``` +Distributed Git +├── Distributed Workflows +│ ├── Centralized Workflow +│ ├── Integration-Manager Workflow +│ ├── Dictator and Lieutenants Workflow +│ ├── Patterns for Managing Source Code Branches +│ └── Workflows Summary +│ +├── Contributing to a Project +│ ├── Commit Guidelines +│ ├── Private Small Team +│ ├── Private Managed Team +│ ├── Forked Public Project +│ ├── Public Project over Email +│ └── Summary +│ +├── Maintaining a Project +│ ├── Working in Topic Branches +│ ├── Applying Patches from Email +│ ├── Checking Out Remote Branches +│ ├── Determining What Is Introduced +│ ├── Integrating Contributed Work +│ ├── Tagging Your Releases +│ ├── Generating a Build Number +│ ├── Preparing a Release +│ └── The Shortlog +│ +└── Summary +``` diff --git a/00-notes/toc-ch06-github.md b/00-notes/toc-ch06-github.md new file mode 100644 index 000000000..00a13bdda --- /dev/null +++ b/00-notes/toc-ch06-github.md @@ -0,0 +1,42 @@ +# Ch 6: GitHub + +``` +GitHub +├── Account Setup and Configuration +│ ├── SSH Access +│ ├── Your Avatar +│ ├── Your Email Addresses +│ └── Two Factor Authentication +│ +├── Contributing to a Project +│ ├── Forking Projects +│ ├── The GitHub Flow +│ ├── Advanced Pull Requests +│ ├── GitHub Flavored Markdown +│ └── Keep your GitHub public repository up-to-date +│ +├── Maintaining a Project +│ ├── Creating a New Repository +│ ├── Adding Collaborators +│ ├── Managing Pull Requests +│ ├── Mentions and Notifications +│ ├── Special Files +│ ├── README +│ ├── CONTRIBUTING +│ └── Project Administration +│ +├── Managing an Organization +│ ├── Organization Basics +│ ├── Teams +│ └── Audit Log +│ +├── Scripting GitHub +│ ├── Services and Hooks +│ ├── The GitHub API +│ ├── Basic Usage +│ ├── Commenting on an Issue +│ ├── Changing the Status of a Pull Request +│ └── Octokit +│ +└── Summary +``` diff --git a/00-notes/toc-ch07-git-tools.md b/00-notes/toc-ch07-git-tools.md new file mode 100644 index 000000000..27acf4564 --- /dev/null +++ b/00-notes/toc-ch07-git-tools.md @@ -0,0 +1,79 @@ +# Ch 7: Git Tools + +``` +Git Tools +├── Revision Selection +│ ├── Single Revisions +│ ├── Short SHA-1 +│ ├── Branch References +│ ├── RefLog Shortnames +│ ├── Ancestry References +│ └── Commit Ranges +│ +├── Interactive Staging +│ ├── Staging and Unstaging Files +│ └── Staging Patches +│ +├── Stashing and Cleaning +│ ├── Stashing Your Work +│ ├── Creative Stashing +│ ├── Creating a Branch from a Stash +│ └── Cleaning your Working Directory +│ +├── Signing Your Work +│ ├── GPG Introduction +│ ├── Signing Tags +│ ├── Verifying Tags +│ ├── Signing Commits +│ └── Everyone Must Sign +│ +├── Searching +│ ├── Git Grep +│ └── Git Log Searching +│ +├── Rewriting History +│ ├── Changing the Last Commit +│ ├── Changing Multiple Commit Messages +│ ├── Reordering Commits +│ ├── Squashing Commits +│ ├── Splitting a Commit +│ ├── Deleting a commit +│ └── The Nuclear Option: filter-branch +│ +├── Reset Demystified +│ ├── The Three Trees +│ ├── The Workflow +│ ├── The Role of Reset +│ ├── Reset With a Path +│ ├── Squashing +│ ├── Check It Out +│ └── Summary +│ +├── Advanced Merging +│ ├── Merge Conflicts +│ ├── Undoing Merges +│ └── Other Types of Merges +│ +├── Rerere +│ +├── Debugging with Git +│ ├── File Annotation +│ └── Binary Search +│ +├── Submodules +│ ├── Starting with Submodules +│ ├── Cloning a Project with Submodules +│ ├── Working on a Project with Submodules +│ ├── Submodule Tips +│ └── Issues with Submodules +│ +├── Bundling +│ +├── Replace +│ +├── Credential Storage +│ ├── Under the Hood +│ └── A Custom Credential Cache +│ +└── Summary +``` diff --git a/00-notes/toc-ch08-customizing-git.md b/00-notes/toc-ch08-customizing-git.md new file mode 100644 index 000000000..a94c75902 --- /dev/null +++ b/00-notes/toc-ch08-customizing-git.md @@ -0,0 +1,28 @@ +# Ch 8: Customizing Git + +``` +Customizing Git +├── Git Configuration +│ ├── Basic Client Configuration +│ ├── Colors in Git +│ ├── External Merge and Diff Tools +│ ├── Formatting and Whitespace +│ └── Server Configuration +│ +├── Git Attributes +│ ├── Binary Files +│ ├── Keyword Expansion +│ ├── Exporting Your Repository +│ └── Merge Strategies +│ +├── Git Hooks +│ ├── Installing a Hook +│ ├── Client-Side Hooks +│ └── Server-Side Hooks +│ +├── An Example Git-Enforced Policy +│ ├── Server-Side Hook +│ └── Client-Side Hooks +│ +└── Summary +``` diff --git a/00-notes/toc-ch09-git-and-other-systems.md b/00-notes/toc-ch09-git-and-other-systems.md new file mode 100644 index 000000000..8883c69a6 --- /dev/null +++ b/00-notes/toc-ch09-git-and-other-systems.md @@ -0,0 +1,17 @@ +# Ch 9: Git and Other Systems + +``` +Git and Other Systems +├── Git as a Client +│ ├── Git and Subversion +│ ├── Git and Mercurial +│ └── Git and Perforce +│ +├── Migrating to Git +│ ├── Subversion +│ ├── Mercurial +│ ├── Perforce +│ └── A Custom Importer +│ +└── Summary +``` diff --git a/00-notes/toc-ch10-git-internals.md b/00-notes/toc-ch10-git-internals.md new file mode 100644 index 000000000..6261cfb21 --- /dev/null +++ b/00-notes/toc-ch10-git-internals.md @@ -0,0 +1,44 @@ +# Ch 10: Git Internals + +``` +Git Internals +├── Plumbing and Porcelain +│ +├── Git Objects +│ ├── Tree Objects +│ ├── Commit Objects +│ └── Object Storage +│ +├── Git References +│ ├── The HEAD +│ ├── Tags +│ └── Remotes +│ +├── Packfiles +│ +├── The Refspec +│ ├── Pushing Refspecs +│ └── Deleting References +│ +├── Transfer Protocols +│ ├── The Dumb Protocol +│ ├── The Smart Protocol +│ └── Protocols Summary +│ +├── Maintenance and Data Recovery +│ ├── Maintenance +│ ├── Data Recovery +│ └── Removing Objects +│ +├── Environment Variables +│ ├── Global Behavior +│ ├── Repository Locations +│ ├── Pathspecs +│ ├── Committing +│ ├── Networking +│ ├── Diffing and Merging +│ ├── Debugging +│ └── Miscellaneous +│ +└── Summary +``` From 067d8a6b4ba1cc232e47b4d7fac976bd0aacd230 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 9 Mar 2026 05:33:20 +0000 Subject: [PATCH 06/17] Add content type annotations to all chapter TOC files Established a 12-type lexicon (concept, walkthrough, procedure, reference, history, comparison, diagram, recipe, config, internals, overview, integration) and applied it to every sub-section across all 13 chapter/appendix TOC files. Lexicon documented in content-type-lexicon.md. https://claude.ai/code/session_011MhF8iWLG3rS5jturtiTZ5 --- 00-notes/content-type-lexicon.md | 28 ++++++ ...oc-appendix-a-git-in-other-environments.md | 22 ++--- 00-notes/toc-appendix-b-embedding-git.md | 22 ++--- 00-notes/toc-appendix-c-git-commands.md | 98 +++++++++---------- 00-notes/toc-ch01-getting-started.md | 40 ++++---- 00-notes/toc-ch02-git-basics.md | 66 ++++++------- 00-notes/toc-ch03-git-branching.md | 38 +++---- 00-notes/toc-ch04-git-on-the-server.md | 34 +++---- 00-notes/toc-ch05-distributed-git.md | 42 ++++---- 00-notes/toc-ch06-github.md | 54 +++++----- 00-notes/toc-ch07-git-tools.md | 98 +++++++++---------- 00-notes/toc-ch08-customizing-git.md | 30 +++--- 00-notes/toc-ch09-git-and-other-systems.md | 16 +-- 00-notes/toc-ch10-git-internals.md | 52 +++++----- 14 files changed, 334 insertions(+), 306 deletions(-) create mode 100644 00-notes/content-type-lexicon.md diff --git a/00-notes/content-type-lexicon.md b/00-notes/content-type-lexicon.md new file mode 100644 index 000000000..046c4b203 --- /dev/null +++ b/00-notes/content-type-lexicon.md @@ -0,0 +1,28 @@ +# Content Type Lexicon + +This lexicon defines the content type tags used across all chapter TOC files. +Each sub-section is tagged to describe the **primary kind of content** it delivers. + +## Content Types + +| Tag | Meaning | +|--------------|---------------------------------------------------------------------------------------------| +| `concept` | Explains an idea, model, or theory. Answers "what is this?" or "how does this work?" | +| `walkthrough`| Step-by-step narrative that guides the reader through a realistic scenario or workflow | +| `procedure` | Task-oriented instructions: do X, then Y, then Z. Answers "how do I do this?" | +| `reference` | Lookup-oriented listing of options, flags, commands, or settings | +| `history` | Historical narrative or background context about origins and evolution | +| `comparison` | Evaluates alternatives side-by-side, including pros/cons and trade-offs | +| `diagram` | Primarily visual — uses diagrams or figures to explain a model or data structure | +| `recipe` | Short, self-contained example showing a specific technique or tip | +| `config` | Configuration-focused: editing config files, setting options, customizing behavior | +| `internals` | Deep dive into underlying mechanisms, data structures, or protocols | +| `overview` | Brief orientation or survey — introduces a topic area without going deep | +| `integration`| Covers connecting Git with external tools, services, or platforms | + +## Usage Rules + +1. Every sub-section (`====` level) and leaf section (`===` with no children) gets exactly one tag. +2. Parent sections (`===` with children) do **not** get tagged — the children carry the type. +3. When a section blends types, choose the **dominant** one (>50% of content). +4. `Summary` sections at chapter end are tagged `overview` (they recap, not introduce). diff --git a/00-notes/toc-appendix-a-git-in-other-environments.md b/00-notes/toc-appendix-a-git-in-other-environments.md index ad08e3ac6..c4ba189fe 100644 --- a/00-notes/toc-appendix-a-git-in-other-environments.md +++ b/00-notes/toc-appendix-a-git-in-other-environments.md @@ -3,24 +3,24 @@ ``` Git in Other Environments ├── Graphical Interfaces -│ ├── gitk and git-gui -│ ├── GitHub for macOS and Windows -│ └── Other GUIs +│ ├── gitk and git-gui ............................... [overview] +│ ├── GitHub for macOS and Windows ................... [overview] +│ └── Other GUIs ..................................... [overview] │ -├── Git in Visual Studio +├── Git in Visual Studio ............................... [integration] │ -├── Git in Visual Studio Code +├── Git in Visual Studio Code .......................... [integration] │ -├── Git in IntelliJ / PyCharm / WebStorm / PhpStorm / RubyMine +├── Git in IntelliJ / PyCharm / WebStorm / etc. ........ [integration] │ -├── Git in Sublime Text +├── Git in Sublime Text ................................ [integration] │ -├── Git in Bash +├── Git in Bash ........................................ [config] │ -├── Git in Zsh +├── Git in Zsh ......................................... [config] │ ├── Git in PowerShell -│ └── Installation +│ └── Installation ................................... [procedure] │ -└── Summary +└── Summary ............................................ [overview] ``` diff --git a/00-notes/toc-appendix-b-embedding-git.md b/00-notes/toc-appendix-b-embedding-git.md index 14117c8f5..e630cdfd9 100644 --- a/00-notes/toc-appendix-b-embedding-git.md +++ b/00-notes/toc-appendix-b-embedding-git.md @@ -2,23 +2,23 @@ ``` Embedding Git in your Applications -├── Command-line Git +├── Command-line Git ................................... [concept] │ ├── Libgit2 -│ ├── Advanced Functionality -│ ├── Other Bindings -│ └── Further Reading +│ ├── Advanced Functionality ......................... [walkthrough] +│ ├── Other Bindings ................................. [reference] +│ └── Further Reading ................................ [reference] │ ├── JGit -│ ├── Getting Set Up -│ ├── Plumbing -│ ├── Porcelain -│ └── Further Reading +│ ├── Getting Set Up ................................. [procedure] +│ ├── Plumbing ....................................... [walkthrough] +│ ├── Porcelain ...................................... [walkthrough] +│ └── Further Reading ................................ [reference] │ ├── go-git -│ ├── Advanced Functionality -│ └── Further Reading +│ ├── Advanced Functionality ......................... [walkthrough] +│ └── Further Reading ................................ [reference] │ └── Dulwich - └── Further Reading + └── Further Reading ................................ [reference] ``` diff --git a/00-notes/toc-appendix-c-git-commands.md b/00-notes/toc-appendix-c-git-commands.md index 345584ccf..266ecea54 100644 --- a/00-notes/toc-appendix-c-git-commands.md +++ b/00-notes/toc-appendix-c-git-commands.md @@ -3,74 +3,74 @@ ``` Git Commands ├── Setup and Config -│ ├── git config -│ ├── git config core.editor commands -│ └── git help +│ ├── git config ..................................... [reference] +│ ├── git config core.editor commands ................ [reference] +│ └── git help ....................................... [reference] │ ├── Getting and Creating Projects -│ ├── git init -│ └── git clone +│ ├── git init ....................................... [reference] +│ └── git clone ...................................... [reference] │ ├── Basic Snapshotting -│ ├── git add -│ ├── git status -│ ├── git diff -│ ├── git difftool -│ ├── git commit -│ ├── git reset -│ ├── git rm -│ ├── git mv -│ └── git clean +│ ├── git add ........................................ [reference] +│ ├── git status ..................................... [reference] +│ ├── git diff ....................................... [reference] +│ ├── git difftool ................................... [reference] +│ ├── git commit ..................................... [reference] +│ ├── git reset ...................................... [reference] +│ ├── git rm ......................................... [reference] +│ ├── git mv ......................................... [reference] +│ └── git clean ...................................... [reference] │ ├── Branching and Merging -│ ├── git branch -│ ├── git checkout -│ ├── git merge -│ ├── git mergetool -│ ├── git log -│ ├── git stash -│ └── git tag +│ ├── git branch ..................................... [reference] +│ ├── git checkout ................................... [reference] +│ ├── git merge ...................................... [reference] +│ ├── git mergetool .................................. [reference] +│ ├── git log ........................................ [reference] +│ ├── git stash ...................................... [reference] +│ └── git tag ........................................ [reference] │ ├── Sharing and Updating Projects -│ ├── git fetch -│ ├── git pull -│ ├── git push -│ ├── git remote -│ ├── git archive -│ └── git submodule +│ ├── git fetch ...................................... [reference] +│ ├── git pull ....................................... [reference] +│ ├── git push ....................................... [reference] +│ ├── git remote ..................................... [reference] +│ ├── git archive .................................... [reference] +│ └── git submodule .................................. [reference] │ ├── Inspection and Comparison -│ ├── git show -│ ├── git shortlog -│ └── git describe +│ ├── git show ....................................... [reference] +│ ├── git shortlog ................................... [reference] +│ └── git describe ................................... [reference] │ ├── Debugging -│ ├── git bisect -│ ├── git blame -│ └── git grep +│ ├── git bisect ..................................... [reference] +│ ├── git blame ...................................... [reference] +│ └── git grep ....................................... [reference] │ ├── Patching -│ ├── git cherry-pick -│ ├── git rebase -│ └── git revert +│ ├── git cherry-pick ................................ [reference] +│ ├── git rebase ..................................... [reference] +│ └── git revert ..................................... [reference] │ ├── Email -│ ├── git apply -│ ├── git am -│ ├── git format-patch -│ ├── git imap-send -│ ├── git send-email -│ └── git request-pull +│ ├── git apply ...................................... [reference] +│ ├── git am ......................................... [reference] +│ ├── git format-patch ............................... [reference] +│ ├── git imap-send .................................. [reference] +│ ├── git send-email ................................. [reference] +│ └── git request-pull ............................... [reference] │ ├── External Systems -│ ├── git svn -│ └── git fast-import +│ ├── git svn ........................................ [reference] +│ └── git fast-import ................................ [reference] │ ├── Administration -│ ├── git gc -│ ├── git fsck -│ ├── git reflog -│ └── git filter-branch +│ ├── git gc ......................................... [reference] +│ ├── git fsck ....................................... [reference] +│ ├── git reflog ..................................... [reference] +│ └── git filter-branch .............................. [reference] │ -└── Plumbing Commands +└── Plumbing Commands .................................. [reference] ``` diff --git a/00-notes/toc-ch01-getting-started.md b/00-notes/toc-ch01-getting-started.md index f2ad59b76..98f1d526d 100644 --- a/00-notes/toc-ch01-getting-started.md +++ b/00-notes/toc-ch01-getting-started.md @@ -3,34 +3,34 @@ ``` Getting Started ├── About Version Control -│ ├── Local Version Control Systems -│ ├── Centralized Version Control Systems -│ └── Distributed Version Control Systems +│ ├── Local Version Control Systems .................. [concept] +│ ├── Centralized Version Control Systems ............ [concept] +│ └── Distributed Version Control Systems ............ [concept] │ -├── A Short History of Git +├── A Short History of Git ............................. [history] │ ├── What is Git? -│ ├── Snapshots, Not Differences -│ ├── Nearly Every Operation Is Local -│ ├── Git Has Integrity -│ ├── Git Generally Only Adds Data -│ └── The Three States +│ ├── Snapshots, Not Differences ..................... [concept] +│ ├── Nearly Every Operation Is Local ................ [concept] +│ ├── Git Has Integrity .............................. [concept] +│ ├── Git Generally Only Adds Data ................... [concept] +│ └── The Three States ............................... [diagram] │ -├── The Command Line +├── The Command Line ................................... [overview] │ ├── Installing Git -│ ├── Installing on Linux -│ ├── Installing on macOS -│ ├── Installing on Windows -│ └── Installing from Source +│ ├── Installing on Linux ............................ [procedure] +│ ├── Installing on macOS ............................ [procedure] +│ ├── Installing on Windows .......................... [procedure] +│ └── Installing from Source ......................... [procedure] │ ├── First-Time Git Setup -│ ├── Your Identity -│ ├── Your Editor -│ ├── Your default branch name -│ └── Checking Your Settings +│ ├── Your Identity .................................. [config] +│ ├── Your Editor .................................... [config] +│ ├── Your default branch name ....................... [config] +│ └── Checking Your Settings ......................... [procedure] │ -├── Getting Help +├── Getting Help ....................................... [reference] │ -└── Summary +└── Summary ............................................ [overview] ``` diff --git a/00-notes/toc-ch02-git-basics.md b/00-notes/toc-ch02-git-basics.md index aafde7804..488d65815 100644 --- a/00-notes/toc-ch02-git-basics.md +++ b/00-notes/toc-ch02-git-basics.md @@ -3,48 +3,48 @@ ``` Git Basics ├── Getting a Git Repository -│ ├── Initializing a Repository in an Existing Directory -│ └── Cloning an Existing Repository +│ ├── Initializing a Repository in an Existing Directory [procedure] +│ └── Cloning an Existing Repository ................. [procedure] │ ├── Recording Changes to the Repository -│ ├── Checking the Status of Your Files -│ ├── Tracking New Files -│ ├── Staging Modified Files -│ ├── Short Status -│ ├── Ignoring Files -│ ├── Viewing Your Staged and Unstaged Changes -│ ├── Committing Your Changes -│ ├── Skipping the Staging Area -│ ├── Removing Files -│ └── Moving Files +│ ├── Checking the Status of Your Files .............. [walkthrough] +│ ├── Tracking New Files ............................. [walkthrough] +│ ├── Staging Modified Files ......................... [walkthrough] +│ ├── Short Status ................................... [reference] +│ ├── Ignoring Files ................................. [config] +│ ├── Viewing Your Staged and Unstaged Changes ....... [walkthrough] +│ ├── Committing Your Changes ........................ [procedure] +│ ├── Skipping the Staging Area ...................... [recipe] +│ ├── Removing Files ................................. [procedure] +│ └── Moving Files ................................... [procedure] │ -├── Viewing the Commit History -│ └── Limiting Log Output +├── Viewing the Commit History ......................... [walkthrough] +│ └── Limiting Log Output ............................ [reference] │ ├── Undoing Things -│ ├── Unstaging a Staged File -│ ├── Unmodifying a Modified File -│ └── Undoing things with git restore +│ ├── Unstaging a Staged File ........................ [procedure] +│ ├── Unmodifying a Modified File .................... [procedure] +│ └── Undoing things with git restore ................ [procedure] │ ├── Working with Remotes -│ ├── Showing Your Remotes -│ ├── Adding Remote Repositories -│ ├── Fetching and Pulling from Your Remotes -│ ├── Pushing to Your Remotes -│ ├── Inspecting a Remote -│ └── Renaming and Removing Remotes +│ ├── Showing Your Remotes ........................... [procedure] +│ ├── Adding Remote Repositories ..................... [procedure] +│ ├── Fetching and Pulling from Your Remotes ......... [concept] +│ ├── Pushing to Your Remotes ........................ [procedure] +│ ├── Inspecting a Remote ............................ [walkthrough] +│ └── Renaming and Removing Remotes .................. [procedure] │ ├── Tagging -│ ├── Listing Your Tags -│ ├── Creating Tags -│ ├── Annotated Tags -│ ├── Lightweight Tags -│ ├── Tagging Later -│ ├── Sharing Tags -│ ├── Deleting Tags -│ └── Checking out Tags +│ ├── Listing Your Tags .............................. [procedure] +│ ├── Creating Tags .................................. [overview] +│ ├── Annotated Tags ................................. [walkthrough] +│ ├── Lightweight Tags ............................... [walkthrough] +│ ├── Tagging Later .................................. [walkthrough] +│ ├── Sharing Tags ................................... [procedure] +│ ├── Deleting Tags .................................. [procedure] +│ └── Checking out Tags .............................. [procedure] │ -├── Git Aliases +├── Git Aliases ........................................ [recipe] │ -└── Summary +└── Summary ............................................ [overview] ``` diff --git a/00-notes/toc-ch03-git-branching.md b/00-notes/toc-ch03-git-branching.md index 3f5d1442a..7d0a5b1a1 100644 --- a/00-notes/toc-ch03-git-branching.md +++ b/00-notes/toc-ch03-git-branching.md @@ -3,33 +3,33 @@ ``` Git Branching ├── Branches in a Nutshell -│ ├── Creating a New Branch -│ └── Switching Branches +│ ├── Creating a New Branch .......................... [diagram] +│ └── Switching Branches ............................. [diagram] │ ├── Basic Branching and Merging -│ ├── Basic Branching -│ ├── Basic Merging -│ └── Basic Merge Conflicts +│ ├── Basic Branching ................................ [walkthrough] +│ ├── Basic Merging .................................. [walkthrough] +│ └── Basic Merge Conflicts .......................... [walkthrough] │ -├── Branch Management -│ └── Changing a branch name +├── Branch Management .................................. [procedure] +│ └── Changing a branch name ......................... [procedure] │ ├── Branching Workflows -│ ├── Long-Running Branches -│ └── Topic Branches +│ ├── Long-Running Branches .......................... [concept] +│ └── Topic Branches ................................. [concept] │ ├── Remote Branches -│ ├── Pushing -│ ├── Tracking Branches -│ ├── Pulling -│ └── Deleting Remote Branches +│ ├── Pushing ........................................ [procedure] +│ ├── Tracking Branches .............................. [procedure] +│ ├── Pulling ........................................ [concept] +│ └── Deleting Remote Branches ....................... [procedure] │ ├── Rebasing -│ ├── The Basic Rebase -│ ├── More Interesting Rebases -│ ├── The Perils of Rebasing -│ ├── Rebase When You Rebase -│ └── Rebase vs. Merge +│ ├── The Basic Rebase ............................... [walkthrough] +│ ├── More Interesting Rebases ....................... [walkthrough] +│ ├── The Perils of Rebasing ......................... [concept] +│ ├── Rebase When You Rebase ......................... [walkthrough] +│ └── Rebase vs. Merge ............................... [comparison] │ -└── Summary +└── Summary ............................................ [overview] ``` diff --git a/00-notes/toc-ch04-git-on-the-server.md b/00-notes/toc-ch04-git-on-the-server.md index ef6fecb64..161697bf1 100644 --- a/00-notes/toc-ch04-git-on-the-server.md +++ b/00-notes/toc-ch04-git-on-the-server.md @@ -3,32 +3,32 @@ ``` Git on the Server ├── The Protocols -│ ├── Local Protocol -│ ├── The HTTP Protocols -│ ├── The SSH Protocol -│ └── The Git Protocol +│ ├── Local Protocol ................................. [comparison] +│ ├── The HTTP Protocols ............................. [comparison] +│ ├── The SSH Protocol ............................... [comparison] +│ └── The Git Protocol ............................... [comparison] │ ├── Getting Git on a Server -│ ├── Putting the Bare Repository on a Server -│ └── Small Setups +│ ├── Putting the Bare Repository on a Server ........ [procedure] +│ └── Small Setups ................................... [concept] │ -├── Generating Your SSH Public Key +├── Generating Your SSH Public Key ..................... [procedure] │ -├── Setting Up the Server +├── Setting Up the Server .............................. [procedure] │ -├── Git Daemon +├── Git Daemon ......................................... [config] │ -├── Smart HTTP +├── Smart HTTP ......................................... [config] │ -├── GitWeb +├── GitWeb ............................................. [procedure] │ ├── GitLab -│ ├── Installation -│ ├── Administration -│ ├── Basic Usage -│ └── Working Together +│ ├── Installation ................................... [reference] +│ ├── Administration ................................. [overview] +│ ├── Basic Usage .................................... [walkthrough] +│ └── Working Together ............................... [concept] │ -├── Third Party Hosted Options +├── Third Party Hosted Options ......................... [overview] │ -└── Summary +└── Summary ............................................ [overview] ``` diff --git a/00-notes/toc-ch05-distributed-git.md b/00-notes/toc-ch05-distributed-git.md index 1a6432e26..3af2ab5ce 100644 --- a/00-notes/toc-ch05-distributed-git.md +++ b/00-notes/toc-ch05-distributed-git.md @@ -3,30 +3,30 @@ ``` Distributed Git ├── Distributed Workflows -│ ├── Centralized Workflow -│ ├── Integration-Manager Workflow -│ ├── Dictator and Lieutenants Workflow -│ ├── Patterns for Managing Source Code Branches -│ └── Workflows Summary +│ ├── Centralized Workflow ........................... [concept] +│ ├── Integration-Manager Workflow ................... [concept] +│ ├── Dictator and Lieutenants Workflow .............. [concept] +│ ├── Patterns for Managing Source Code Branches ..... [concept] +│ └── Workflows Summary .............................. [overview] │ ├── Contributing to a Project -│ ├── Commit Guidelines -│ ├── Private Small Team -│ ├── Private Managed Team -│ ├── Forked Public Project -│ ├── Public Project over Email -│ └── Summary +│ ├── Commit Guidelines .............................. [concept] +│ ├── Private Small Team ............................. [walkthrough] +│ ├── Private Managed Team ........................... [walkthrough] +│ ├── Forked Public Project .......................... [walkthrough] +│ ├── Public Project over Email ...................... [walkthrough] +│ └── Summary ........................................ [overview] │ ├── Maintaining a Project -│ ├── Working in Topic Branches -│ ├── Applying Patches from Email -│ ├── Checking Out Remote Branches -│ ├── Determining What Is Introduced -│ ├── Integrating Contributed Work -│ ├── Tagging Your Releases -│ ├── Generating a Build Number -│ ├── Preparing a Release -│ └── The Shortlog +│ ├── Working in Topic Branches ...................... [concept] +│ ├── Applying Patches from Email .................... [procedure] +│ ├── Checking Out Remote Branches ................... [procedure] +│ ├── Determining What Is Introduced ................. [procedure] +│ ├── Integrating Contributed Work ................... [walkthrough] +│ ├── Tagging Your Releases .......................... [procedure] +│ ├── Generating a Build Number ...................... [procedure] +│ ├── Preparing a Release ............................ [procedure] +│ └── The Shortlog ................................... [recipe] │ -└── Summary +└── Summary ............................................ [overview] ``` diff --git a/00-notes/toc-ch06-github.md b/00-notes/toc-ch06-github.md index 00a13bdda..976d519f1 100644 --- a/00-notes/toc-ch06-github.md +++ b/00-notes/toc-ch06-github.md @@ -3,40 +3,40 @@ ``` GitHub ├── Account Setup and Configuration -│ ├── SSH Access -│ ├── Your Avatar -│ ├── Your Email Addresses -│ └── Two Factor Authentication +│ ├── SSH Access ..................................... [config] +│ ├── Your Avatar .................................... [config] +│ ├── Your Email Addresses ........................... [config] +│ └── Two Factor Authentication ...................... [config] │ ├── Contributing to a Project -│ ├── Forking Projects -│ ├── The GitHub Flow -│ ├── Advanced Pull Requests -│ ├── GitHub Flavored Markdown -│ └── Keep your GitHub public repository up-to-date +│ ├── Forking Projects ............................... [concept] +│ ├── The GitHub Flow ................................ [walkthrough] +│ ├── Advanced Pull Requests ......................... [walkthrough] +│ ├── GitHub Flavored Markdown ....................... [reference] +│ └── Keep your GitHub public repository up-to-date .. [procedure] │ ├── Maintaining a Project -│ ├── Creating a New Repository -│ ├── Adding Collaborators -│ ├── Managing Pull Requests -│ ├── Mentions and Notifications -│ ├── Special Files -│ ├── README -│ ├── CONTRIBUTING -│ └── Project Administration +│ ├── Creating a New Repository ...................... [procedure] +│ ├── Adding Collaborators ........................... [procedure] +│ ├── Managing Pull Requests ......................... [walkthrough] +│ ├── Mentions and Notifications ..................... [concept] +│ ├── Special Files .................................. [overview] +│ ├── README ......................................... [concept] +│ ├── CONTRIBUTING ................................... [concept] +│ └── Project Administration ......................... [procedure] │ ├── Managing an Organization -│ ├── Organization Basics -│ ├── Teams -│ └── Audit Log +│ ├── Organization Basics ............................ [overview] +│ ├── Teams .......................................... [walkthrough] +│ └── Audit Log ...................................... [overview] │ ├── Scripting GitHub -│ ├── Services and Hooks -│ ├── The GitHub API -│ ├── Basic Usage -│ ├── Commenting on an Issue -│ ├── Changing the Status of a Pull Request -│ └── Octokit +│ ├── Services and Hooks ............................. [integration] +│ ├── The GitHub API ................................. [overview] +│ ├── Basic Usage .................................... [walkthrough] +│ ├── Commenting on an Issue ......................... [walkthrough] +│ ├── Changing the Status of a Pull Request .......... [walkthrough] +│ └── Octokit ........................................ [integration] │ -└── Summary +└── Summary ............................................ [overview] ``` diff --git a/00-notes/toc-ch07-git-tools.md b/00-notes/toc-ch07-git-tools.md index 27acf4564..9bd79746f 100644 --- a/00-notes/toc-ch07-git-tools.md +++ b/00-notes/toc-ch07-git-tools.md @@ -3,77 +3,77 @@ ``` Git Tools ├── Revision Selection -│ ├── Single Revisions -│ ├── Short SHA-1 -│ ├── Branch References -│ ├── RefLog Shortnames -│ ├── Ancestry References -│ └── Commit Ranges +│ ├── Single Revisions ............................... [concept] +│ ├── Short SHA-1 .................................... [concept] +│ ├── Branch References .............................. [concept] +│ ├── RefLog Shortnames .............................. [reference] +│ ├── Ancestry References ............................ [reference] +│ └── Commit Ranges .................................. [reference] │ ├── Interactive Staging -│ ├── Staging and Unstaging Files -│ └── Staging Patches +│ ├── Staging and Unstaging Files .................... [walkthrough] +│ └── Staging Patches ................................ [walkthrough] │ ├── Stashing and Cleaning -│ ├── Stashing Your Work -│ ├── Creative Stashing -│ ├── Creating a Branch from a Stash -│ └── Cleaning your Working Directory +│ ├── Stashing Your Work ............................. [walkthrough] +│ ├── Creative Stashing .............................. [recipe] +│ ├── Creating a Branch from a Stash ................. [recipe] +│ └── Cleaning your Working Directory ................ [procedure] │ ├── Signing Your Work -│ ├── GPG Introduction -│ ├── Signing Tags -│ ├── Verifying Tags -│ ├── Signing Commits -│ └── Everyone Must Sign +│ ├── GPG Introduction ............................... [concept] +│ ├── Signing Tags ................................... [procedure] +│ ├── Verifying Tags ................................. [procedure] +│ ├── Signing Commits ................................ [procedure] +│ └── Everyone Must Sign ............................. [concept] │ ├── Searching -│ ├── Git Grep -│ └── Git Log Searching +│ ├── Git Grep ....................................... [walkthrough] +│ └── Git Log Searching .............................. [walkthrough] │ ├── Rewriting History -│ ├── Changing the Last Commit -│ ├── Changing Multiple Commit Messages -│ ├── Reordering Commits -│ ├── Squashing Commits -│ ├── Splitting a Commit -│ ├── Deleting a commit -│ └── The Nuclear Option: filter-branch +│ ├── Changing the Last Commit ....................... [procedure] +│ ├── Changing Multiple Commit Messages .............. [walkthrough] +│ ├── Reordering Commits ............................. [procedure] +│ ├── Squashing Commits .............................. [walkthrough] +│ ├── Splitting a Commit ............................. [walkthrough] +│ ├── Deleting a commit .............................. [procedure] +│ └── The Nuclear Option: filter-branch .............. [procedure] │ ├── Reset Demystified -│ ├── The Three Trees -│ ├── The Workflow -│ ├── The Role of Reset -│ ├── Reset With a Path -│ ├── Squashing -│ ├── Check It Out -│ └── Summary +│ ├── The Three Trees ................................ [diagram] +│ ├── The Workflow ................................... [walkthrough] +│ ├── The Role of Reset .............................. [internals] +│ ├── Reset With a Path .............................. [internals] +│ ├── Squashing ...................................... [recipe] +│ ├── Check It Out ................................... [comparison] +│ └── Summary ........................................ [reference] │ ├── Advanced Merging -│ ├── Merge Conflicts -│ ├── Undoing Merges -│ └── Other Types of Merges +│ ├── Merge Conflicts ................................ [walkthrough] +│ ├── Undoing Merges ................................. [procedure] +│ └── Other Types of Merges .......................... [reference] │ -├── Rerere +├── Rerere ............................................. [walkthrough] │ ├── Debugging with Git -│ ├── File Annotation -│ └── Binary Search +│ ├── File Annotation ................................ [walkthrough] +│ └── Binary Search .................................. [walkthrough] │ ├── Submodules -│ ├── Starting with Submodules -│ ├── Cloning a Project with Submodules -│ ├── Working on a Project with Submodules -│ ├── Submodule Tips -│ └── Issues with Submodules +│ ├── Starting with Submodules ....................... [walkthrough] +│ ├── Cloning a Project with Submodules .............. [procedure] +│ ├── Working on a Project with Submodules ........... [walkthrough] +│ ├── Submodule Tips ................................. [recipe] +│ └── Issues with Submodules ......................... [concept] │ -├── Bundling +├── Bundling ........................................... [walkthrough] │ -├── Replace +├── Replace ............................................ [walkthrough] │ ├── Credential Storage -│ ├── Under the Hood -│ └── A Custom Credential Cache +│ ├── Under the Hood ................................. [internals] +│ └── A Custom Credential Cache ...................... [walkthrough] │ -└── Summary +└── Summary ............................................ [overview] ``` diff --git a/00-notes/toc-ch08-customizing-git.md b/00-notes/toc-ch08-customizing-git.md index a94c75902..42369fb86 100644 --- a/00-notes/toc-ch08-customizing-git.md +++ b/00-notes/toc-ch08-customizing-git.md @@ -3,26 +3,26 @@ ``` Customizing Git ├── Git Configuration -│ ├── Basic Client Configuration -│ ├── Colors in Git -│ ├── External Merge and Diff Tools -│ ├── Formatting and Whitespace -│ └── Server Configuration +│ ├── Basic Client Configuration ..................... [reference] +│ ├── Colors in Git .................................. [config] +│ ├── External Merge and Diff Tools .................. [walkthrough] +│ ├── Formatting and Whitespace ...................... [config] +│ └── Server Configuration ........................... [reference] │ ├── Git Attributes -│ ├── Binary Files -│ ├── Keyword Expansion -│ ├── Exporting Your Repository -│ └── Merge Strategies +│ ├── Binary Files ................................... [config] +│ ├── Keyword Expansion .............................. [walkthrough] +│ ├── Exporting Your Repository ...................... [config] +│ └── Merge Strategies ............................... [config] │ ├── Git Hooks -│ ├── Installing a Hook -│ ├── Client-Side Hooks -│ └── Server-Side Hooks +│ ├── Installing a Hook .............................. [procedure] +│ ├── Client-Side Hooks .............................. [reference] +│ └── Server-Side Hooks .............................. [reference] │ ├── An Example Git-Enforced Policy -│ ├── Server-Side Hook -│ └── Client-Side Hooks +│ ├── Server-Side Hook ............................... [walkthrough] +│ └── Client-Side Hooks .............................. [walkthrough] │ -└── Summary +└── Summary ............................................ [overview] ``` diff --git a/00-notes/toc-ch09-git-and-other-systems.md b/00-notes/toc-ch09-git-and-other-systems.md index 8883c69a6..41a404226 100644 --- a/00-notes/toc-ch09-git-and-other-systems.md +++ b/00-notes/toc-ch09-git-and-other-systems.md @@ -3,15 +3,15 @@ ``` Git and Other Systems ├── Git as a Client -│ ├── Git and Subversion -│ ├── Git and Mercurial -│ └── Git and Perforce +│ ├── Git and Subversion ............................. [integration] +│ ├── Git and Mercurial .............................. [integration] +│ └── Git and Perforce ............................... [integration] │ ├── Migrating to Git -│ ├── Subversion -│ ├── Mercurial -│ ├── Perforce -│ └── A Custom Importer +│ ├── Subversion ..................................... [procedure] +│ ├── Mercurial ...................................... [procedure] +│ ├── Perforce ....................................... [procedure] +│ └── A Custom Importer .............................. [walkthrough] │ -└── Summary +└── Summary ............................................ [overview] ``` diff --git a/00-notes/toc-ch10-git-internals.md b/00-notes/toc-ch10-git-internals.md index 6261cfb21..ec1d4869b 100644 --- a/00-notes/toc-ch10-git-internals.md +++ b/00-notes/toc-ch10-git-internals.md @@ -2,43 +2,43 @@ ``` Git Internals -├── Plumbing and Porcelain +├── Plumbing and Porcelain ............................. [concept] │ ├── Git Objects -│ ├── Tree Objects -│ ├── Commit Objects -│ └── Object Storage +│ ├── Tree Objects ................................... [internals] +│ ├── Commit Objects ................................. [internals] +│ └── Object Storage ................................. [internals] │ ├── Git References -│ ├── The HEAD -│ ├── Tags -│ └── Remotes +│ ├── The HEAD ....................................... [internals] +│ ├── Tags ........................................... [internals] +│ └── Remotes ........................................ [internals] │ -├── Packfiles +├── Packfiles .......................................... [internals] │ ├── The Refspec -│ ├── Pushing Refspecs -│ └── Deleting References +│ ├── Pushing Refspecs ............................... [reference] +│ └── Deleting References ............................ [reference] │ ├── Transfer Protocols -│ ├── The Dumb Protocol -│ ├── The Smart Protocol -│ └── Protocols Summary +│ ├── The Dumb Protocol .............................. [internals] +│ ├── The Smart Protocol ............................. [internals] +│ └── Protocols Summary .............................. [overview] │ ├── Maintenance and Data Recovery -│ ├── Maintenance -│ ├── Data Recovery -│ └── Removing Objects +│ ├── Maintenance .................................... [internals] +│ ├── Data Recovery .................................. [walkthrough] +│ └── Removing Objects ............................... [walkthrough] │ ├── Environment Variables -│ ├── Global Behavior -│ ├── Repository Locations -│ ├── Pathspecs -│ ├── Committing -│ ├── Networking -│ ├── Diffing and Merging -│ ├── Debugging -│ └── Miscellaneous -│ -└── Summary +│ ├── Global Behavior ................................ [reference] +│ ├── Repository Locations ........................... [reference] +│ ├── Pathspecs ...................................... [reference] +│ ├── Committing ..................................... [reference] +│ ├── Networking ..................................... [reference] +│ ├── Diffing and Merging ............................ [reference] +│ ├── Debugging ...................................... [reference] +│ └── Miscellaneous .................................. [reference] +│ +└── Summary ............................................ [overview] ``` From 75dc08db005dfb633fe789de24d5e5ef4b2a4218 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 18 Mar 2026 12:48:39 +0000 Subject: [PATCH 07/17] Add walkthroughs.md catalog for all chapters and appendices Create per-chapter directories in 00-notes/ with walkthroughs.md files documenting every walkthrough across the book. Each entry includes the section title, source file, topic, scenario description, and word count. https://claude.ai/code/session_011MhF8iWLG3rS5jturtiTZ5 --- 00-notes/01-introduction/walkthroughs.md | 49 ++++ 00-notes/02-git-basics/walkthroughs.md | 199 +++++++++++++++ 00-notes/03-git-branching/walkthroughs.md | 61 +++++ 00-notes/04-git-server/walkthroughs.md | 37 +++ 00-notes/05-distributed-git/walkthroughs.md | 73 ++++++ 00-notes/06-github/walkthroughs.md | 55 +++++ 00-notes/07-git-tools/walkthroughs.md | 229 ++++++++++++++++++ 00-notes/08-customizing-git/walkthroughs.md | 67 +++++ .../09-git-and-other-scms/walkthroughs.md | 133 ++++++++++ 00-notes/10-git-internals/walkthroughs.md | 103 ++++++++ .../walkthroughs.md | 49 ++++ 00-notes/B-embedding-git/walkthroughs.md | 25 ++ 00-notes/C-git-commands/walkthroughs.md | 3 + 13 files changed, 1083 insertions(+) create mode 100644 00-notes/01-introduction/walkthroughs.md create mode 100644 00-notes/02-git-basics/walkthroughs.md create mode 100644 00-notes/03-git-branching/walkthroughs.md create mode 100644 00-notes/04-git-server/walkthroughs.md create mode 100644 00-notes/05-distributed-git/walkthroughs.md create mode 100644 00-notes/06-github/walkthroughs.md create mode 100644 00-notes/07-git-tools/walkthroughs.md create mode 100644 00-notes/08-customizing-git/walkthroughs.md create mode 100644 00-notes/09-git-and-other-scms/walkthroughs.md create mode 100644 00-notes/10-git-internals/walkthroughs.md create mode 100644 00-notes/A-git-in-other-environments/walkthroughs.md create mode 100644 00-notes/B-embedding-git/walkthroughs.md create mode 100644 00-notes/C-git-commands/walkthroughs.md diff --git a/00-notes/01-introduction/walkthroughs.md b/00-notes/01-introduction/walkthroughs.md new file mode 100644 index 000000000..b6e65d369 --- /dev/null +++ b/00-notes/01-introduction/walkthroughs.md @@ -0,0 +1,49 @@ +# Chapter 1: Getting Started — Walkthroughs + +## 1. Your Identity +- **File:** `book/01-introduction/sections/first-time-setup.asc` +- **Topic:** Configuring Git user identity for the first time +- **Scenario:** Reader sets their name and email globally using `git config --global`, with a note on per-project overrides +- **Word Count:** 144 + +## 2. Your Editor +- **File:** `book/01-introduction/sections/first-time-setup.asc` +- **Topic:** Configuring a default text editor for Git +- **Scenario:** Reader configures Git to use their preferred editor (Emacs, Notepad++), with platform-specific command examples +- **Word Count:** 198 + +## 3. Your Default Branch Name +- **File:** `book/01-introduction/sections/first-time-setup.asc` +- **Topic:** Changing the default branch name from "master" to "main" +- **Scenario:** Reader runs `git config --global init.defaultBranch main` to change the default +- **Word Count:** 51 + +## 4. Installing on Linux +- **File:** `book/01-introduction/sections/installing.asc` +- **Topic:** Installing Git on Linux via package managers +- **Scenario:** Reader installs Git using `dnf` (Fedora/RHEL) or `apt` (Debian/Ubuntu) with the appropriate package manager commands +- **Word Count:** 92 + +## 5. Installing on macOS +- **File:** `book/01-introduction/sections/installing.asc` +- **Topic:** Installing Git on macOS +- **Scenario:** Reader triggers the Xcode Command Line Tools installer by running `git` from Terminal, with an alternative binary installer option +- **Word Count:** 107 + +## 6. Installing on Windows +- **File:** `book/01-introduction/sections/installing.asc` +- **Topic:** Installing Git on Windows +- **Scenario:** Reader downloads Git from the official website or installs via the Chocolatey package manager +- **Word Count:** 81 + +## 7. Installing from Source +- **File:** `book/01-introduction/sections/installing.asc` +- **Topic:** Compiling and installing Git from source code +- **Scenario:** Reader installs build dependencies for their distribution, downloads Git source, and compiles/installs with `make` and `make install` +- **Word Count:** 267 + +## 8. Getting Help +- **File:** `book/01-introduction/sections/help.asc` +- **Topic:** Accessing Git command documentation +- **Scenario:** Reader uses three equivalent methods (`git help `, `git --help`, `man git-`) to access help, with a concrete example using `git config` +- **Word Count:** 118 diff --git a/00-notes/02-git-basics/walkthroughs.md b/00-notes/02-git-basics/walkthroughs.md new file mode 100644 index 000000000..9c8223401 --- /dev/null +++ b/00-notes/02-git-basics/walkthroughs.md @@ -0,0 +1,199 @@ +# Chapter 2: Git Basics — Walkthroughs + +## 1. Initializing a Repository in an Existing Directory +- **File:** `book/02-git-basics/sections/getting-a-repository.asc` +- **Topic:** Creating a new Git repository from an existing project +- **Scenario:** Reader navigates to a project directory (with platform-specific paths for Linux, macOS, Windows), runs `git init`, then stages and commits initial files +- **Word Count:** 271 + +## 2. Cloning an Existing Repository +- **File:** `book/02-git-basics/sections/getting-a-repository.asc` +- **Topic:** Cloning a remote repository +- **Scenario:** Reader clones the libgit2 repository using `git clone`, then clones again into a custom-named directory +- **Word Count:** 207 + +## 3. Checking the Status of Your Files +- **File:** `book/02-git-basics/sections/recording-changes.asc` +- **Topic:** Tracking file status in a repository +- **Scenario:** Reader runs `git status` after a fresh clone, creates a README file, and observes the status change from clean to untracked +- **Word Count:** 169 + +## 4. Tracking New Files +- **File:** `book/02-git-basics/sections/recording-changes.asc` +- **Topic:** Adding untracked files to Git +- **Scenario:** Reader stages a new README file with `git add` and verifies the status change to staged +- **Word Count:** 121 + +## 5. Staging Modified Files +- **File:** `book/02-git-basics/sections/recording-changes.asc` +- **Topic:** Understanding the staging workflow for modified files +- **Scenario:** Reader modifies a tracked file, stages it with `git add`, makes further edits, and discovers that Git stages only the version at `git add` time — requiring re-staging +- **Word Count:** 326 + +## 6. Short Status +- **File:** `book/02-git-basics/sections/recording-changes.asc` +- **Topic:** Compact status output +- **Scenario:** Reader uses `git status -s` to view two-column status indicators for staging area and working directory +- **Word Count:** 76 + +## 7. Viewing Your Staged and Unstaged Changes +- **File:** `book/02-git-basics/sections/recording-changes.asc` +- **Topic:** Inspecting differences before committing +- **Scenario:** Reader uses `git diff` for unstaged changes and `git diff --staged` for staged changes, including a scenario with both staged and unstaged portions of the same file +- **Word Count:** 380 + +## 8. Committing Your Changes +- **File:** `book/02-git-basics/sections/recording-changes.asc` +- **Topic:** Creating commits +- **Scenario:** Reader commits using both the editor-based `git commit` and inline `git commit -m` workflows, seeing editor output and commit confirmation +- **Word Count:** 235 + +## 9. Skipping the Staging Area +- **File:** `book/02-git-basics/sections/recording-changes.asc` +- **Topic:** Committing without explicit staging +- **Scenario:** Reader uses `git commit -a` to bypass the staging area, automatically staging all tracked files before committing +- **Word Count:** 94 + +## 10. Removing Files +- **File:** `book/02-git-basics/sections/recording-changes.asc` +- **Topic:** Removing files from Git tracking +- **Scenario:** Reader manually deletes a file and observes the status, then uses `git rm` to stage the removal, and `git rm --cached` to keep the file locally while removing it from tracking +- **Word Count:** 256 + +## 11. Moving Files +- **File:** `book/02-git-basics/sections/recording-changes.asc` +- **Topic:** Renaming files in Git +- **Scenario:** Reader renames a file with `git mv`, observes the rename status, and learns it is equivalent to manual move + remove + add +- **Word Count:** 187 + +## 12. Adding Remote Repositories +- **File:** `book/02-git-basics/sections/remotes.asc` +- **Topic:** Configuring remote repositories +- **Scenario:** Reader adds a new remote shortname (`pb`) with `git remote add`, verifies with `git remote -v`, and fetches from it +- **Word Count:** 212 + +## 13. Pushing to Your Remotes +- **File:** `book/02-git-basics/sections/remotes.asc` +- **Topic:** Pushing commits to a remote server +- **Scenario:** Reader pushes to origin/master with `git push` and learns when pushes succeed or fail due to upstream changes +- **Word Count:** 126 + +## 14. Inspecting a Remote +- **File:** `book/02-git-basics/sections/remotes.asc` +- **Topic:** Viewing detailed remote information +- **Scenario:** Reader uses `git remote show ` on both a simple case and a complex multi-branch project with tracking configurations +- **Word Count:** 268 + +## 15. Renaming and Removing Remotes +- **File:** `book/02-git-basics/sections/remotes.asc` +- **Topic:** Managing remote shortnames +- **Scenario:** Reader renames a remote with `git remote rename` and deletes one with `git remote remove`, verifying status after each +- **Word Count:** 143 + +## 16. Annotated Tags +- **File:** `book/02-git-basics/sections/tagging.asc` +- **Topic:** Creating annotated tags +- **Scenario:** Reader creates an annotated tag with `git tag -a` and `-m`, then inspects metadata and commit info with `git show` +- **Word Count:** 178 + +## 17. Lightweight Tags +- **File:** `book/02-git-basics/sections/tagging.asc` +- **Topic:** Creating lightweight tags +- **Scenario:** Reader creates a lightweight tag (no `-a`, `-s`, or `-m`) and compares the `git show` output to annotated tags +- **Word Count:** 145 + +## 18. Tagging Later +- **File:** `book/02-git-basics/sections/tagging.asc` +- **Topic:** Retroactively tagging past commits +- **Scenario:** Reader views `git log` output, tags an old commit by hash, and verifies with `git tag` and `git show` +- **Word Count:** 223 + +## 19. Sharing Tags +- **File:** `book/02-git-basics/sections/tagging.asc` +- **Topic:** Pushing tags to remote servers +- **Scenario:** Reader pushes a single tag with `git push origin ` and all tags with `git push origin --tags` +- **Word Count:** 159 + +## 20. Deleting Tags +- **File:** `book/02-git-basics/sections/tagging.asc` +- **Topic:** Removing tags locally and remotely +- **Scenario:** Reader deletes a local tag with `git tag -d`, then removes a remote tag using both `git push :refs/tags/` and `git push --delete` syntax +- **Word Count:** 148 + +## 21. Checking out Tags +- **File:** `book/02-git-basics/sections/tagging.asc` +- **Topic:** Checking out code at a tag +- **Scenario:** Reader checks out a tag with `git checkout`, learns about detached HEAD state, and creates a branch from a tag with `git checkout -b` +- **Word Count:** 212 + +## 22. Undoing a Commit with --amend +- **File:** `book/02-git-basics/sections/undoing.asc` +- **Topic:** Amending the last commit +- **Scenario:** Reader commits too early, then stages forgotten files and uses `git commit --amend` to replace the previous commit +- **Word Count:** 189 + +## 23. Unstaging a Staged File (git reset) +- **File:** `book/02-git-basics/sections/undoing.asc` +- **Topic:** Unstaging files with git reset +- **Scenario:** Reader uses `git reset HEAD ` to unstage a file, with status output before and after +- **Word Count:** 142 + +## 24. Unmodifying a Modified File (git checkout) +- **File:** `book/02-git-basics/sections/undoing.asc` +- **Topic:** Discarding working directory changes +- **Scenario:** Reader uses `git checkout -- ` to revert a modified file, with status verification +- **Word Count:** 131 + +## 25. Unstaging a Staged File with git restore +- **File:** `book/02-git-basics/sections/undoing.asc` +- **Topic:** Unstaging files with the modern git restore command +- **Scenario:** Reader uses `git restore --staged ` as the modern alternative to `git reset` for unstaging +- **Word Count:** 139 + +## 26. Unmodifying a Modified File with git restore +- **File:** `book/02-git-basics/sections/undoing.asc` +- **Topic:** Discarding changes with git restore +- **Scenario:** Reader uses `git restore ` as the modern alternative to `git checkout --` for discarding changes +- **Word Count:** 124 + +## 27. Viewing the Commit History +- **File:** `book/02-git-basics/sections/viewing-history.asc` +- **Topic:** Basic commit history viewing +- **Scenario:** Reader clones a simple project and runs `git log` to view commit history with author, date, and message +- **Word Count:** 142 + +## 28. Using git log -p (Patch View) +- **File:** `book/02-git-basics/sections/viewing-history.asc` +- **Topic:** Viewing diffs in commit history +- **Scenario:** Reader uses `git log -p -2` to show the last two commits with full diffs for code review +- **Word Count:** 121 + +## 29. Using git log --stat +- **File:** `book/02-git-basics/sections/viewing-history.asc` +- **Topic:** Abbreviated change statistics per commit +- **Scenario:** Reader uses `git log --stat` to see file change counts and insertion/deletion summaries +- **Word Count:** 100 + +## 30. Using git log --pretty +- **File:** `book/02-git-basics/sections/viewing-history.asc` +- **Topic:** Custom log output formatting +- **Scenario:** Reader uses `--pretty=oneline` and `--pretty=format:` with custom format strings to tailor log output +- **Word Count:** 174 + +## 31. Using git log --graph +- **File:** `book/02-git-basics/sections/viewing-history.asc` +- **Topic:** Visualizing branch and merge history +- **Scenario:** Reader uses `--pretty=format` combined with `--graph` to display an ASCII graph of branch history +- **Word Count:** 90 + +## 32. Limiting Log Output with Time Filters +- **File:** `book/02-git-basics/sections/viewing-history.asc` +- **Topic:** Time-based commit filtering +- **Scenario:** Reader uses `git log --since` with various date formats to filter commits by time range +- **Word Count:** 93 + +## 33. Filtering Commits by Author and Content +- **File:** `book/02-git-basics/sections/viewing-history.asc` +- **Topic:** Advanced commit filtering with pickaxe and multi-filter queries +- **Scenario:** Reader uses `git log -S` to find commits changing a specific string, and combines author, date, and path filters +- **Word Count:** 208 diff --git a/00-notes/03-git-branching/walkthroughs.md b/00-notes/03-git-branching/walkthroughs.md new file mode 100644 index 000000000..ba4568536 --- /dev/null +++ b/00-notes/03-git-branching/walkthroughs.md @@ -0,0 +1,61 @@ +# Chapter 3: Git Branching — Walkthroughs + +## 1. Basic Branching +- **File:** `book/03-git-branching/sections/basic-branching-and-merging.asc` +- **Topic:** Creating and switching between feature and hotfix branches +- **Scenario:** Reader creates an `iss53` feature branch, receives an urgent bug report, switches to a `hotfix` branch on production, tests and merges the fix, then returns to the original feature work +- **Word Count:** 1,247 + +## 2. Basic Merging +- **File:** `book/03-git-branching/sections/basic-branching-and-merging.asc` +- **Topic:** Merging a completed feature branch with a three-way merge +- **Scenario:** Reader merges the completed `iss53` branch back into master, observing the three-way merge process, and cleans up the branch +- **Word Count:** 418 + +## 3. Basic Merge Conflicts +- **File:** `book/03-git-branching/sections/basic-branching-and-merging.asc` +- **Topic:** Resolving merge conflicts when two branches modify the same file +- **Scenario:** Reader encounters conflict markers after merging, uses `git mergetool` to resolve them, and finalizes with a commit +- **Word Count:** 1,036 + +## 4. The Basic Rebase +- **File:** `book/03-git-branching/sections/rebasing.asc` +- **Topic:** Rebasing a branch onto another +- **Scenario:** Reader rebases an `experiment` branch onto `master`, rewinding and replaying commits, then completes a fast-forward merge +- **Word Count:** 697 + +## 5. More Interesting Rebases +- **File:** `book/03-git-branching/sections/rebasing.asc` +- **Topic:** Selective rebasing with `--onto` +- **Scenario:** Reader selectively rebases `client` and `server` topic branches using `--onto`, integrating changes into mainline in stages +- **Word Count:** 1,123 + +## 6. Pushing Branches +- **File:** `book/03-git-branching/sections/remote-branches.asc` +- **Topic:** Pushing local branches to a remote repository +- **Scenario:** Reader pushes a local `serverfix` branch to a remote, and collaborators fetch and create tracking branches from it +- **Word Count:** 742 + +## 7. Tracking Branches +- **File:** `book/03-git-branching/sections/remote-branches.asc` +- **Topic:** Setting up and managing tracking branches +- **Scenario:** Reader sets up tracking branches using `-b`, `--track`, and implicit creation, checks tracking status with `-vv`, and sets upstream branches +- **Word Count:** 1,261 + +## 8. Deleting Remote Branches +- **File:** `book/03-git-branching/sections/remote-branches.asc` +- **Topic:** Removing branches from a remote server +- **Scenario:** Reader deletes the `serverfix` remote branch using `git push --delete` +- **Word Count:** 168 + +## 9. Changing a Branch Name +- **File:** `book/03-git-branching/sections/branch-management.asc` +- **Topic:** Renaming a local branch and updating the remote +- **Scenario:** Reader renames a local branch, pushes the renamed branch to the remote, and cleans up the old remote branch name +- **Word Count:** 465 + +## 10. Changing the Master Branch Name +- **File:** `book/03-git-branching/sections/branch-management.asc` +- **Topic:** Renaming the master branch to main +- **Scenario:** Reader renames master to main, pushes to remote, and handles follow-up tasks across dependent projects, CI configs, tests, and documentation +- **Word Count:** 837 diff --git a/00-notes/04-git-server/walkthroughs.md b/00-notes/04-git-server/walkthroughs.md new file mode 100644 index 000000000..f3a3d585f --- /dev/null +++ b/00-notes/04-git-server/walkthroughs.md @@ -0,0 +1,37 @@ +# Chapter 4: Git on the Server — Walkthroughs + +## 1. Generating Your SSH Public Key +- **File:** `book/04-git-server/sections/generating-ssh-key.asc` +- **Topic:** Creating SSH key pairs for Git server authentication +- **Scenario:** Reader checks for existing SSH keys in `~/.ssh`, generates a new RSA key pair using `ssh-keygen -o`, sets a passphrase, and learns about the resulting key files +- **Word Count:** 417 + +## 2. Putting the Bare Repository on a Server +- **File:** `book/04-git-server/sections/git-on-a-server.asc` +- **Topic:** Creating and deploying a bare repository for team collaboration +- **Scenario:** Reader clones a local repository with `--bare`, copies it to a server via SCP, and sets up shared access permissions with `git init --bare --shared` +- **Word Count:** 231 + +## 3. Setting Up the Server +- **File:** `book/04-git-server/sections/setting-up-server.asc` +- **Topic:** SSH-based Git server access using the authorized_keys method +- **Scenario:** Administrator creates a `git` user, sets up `.ssh` directory with proper permissions, adds developer public keys to `authorized_keys`, creates a bare repository, demonstrates developer push/clone workflows, and restricts shell access using `git-shell` +- **Word Count:** 855 + +## 4. Git Daemon +- **File:** `book/04-git-server/sections/git-daemon.asc` +- **Topic:** Serving repositories over the git:// protocol with unauthenticated access +- **Scenario:** Reader starts the git daemon with specific options, configures it using systemd on Linux, and marks repositories as exportable with the `git-daemon-export-ok` file +- **Word Count:** 457 + +## 5. GitWeb — Permanent Installation +- **File:** `book/04-git-server/sections/gitweb.asc` +- **Topic:** Building and deploying GitWeb CGI script for web-based repository viewing +- **Scenario:** Reader clones Git source, builds the GitWeb CGI script specifying the project root, copies it to a web server directory, and configures an Apache VirtualHost with CGI handler +- **Word Count:** 252 + +## 6. Smart HTTP +- **File:** `book/04-git-server/sections/smart-http.asc` +- **Topic:** Setting up Smart HTTP protocol with Apache for authenticated and unauthenticated access +- **Scenario:** Reader installs Apache with required modules, changes directory ownership to www-data, configures Apache with `git-http-backend` directives, creates `.htpasswd` authentication file, and sets up auth blocks +- **Word Count:** 312 diff --git a/00-notes/05-distributed-git/walkthroughs.md b/00-notes/05-distributed-git/walkthroughs.md new file mode 100644 index 000000000..409718a50 --- /dev/null +++ b/00-notes/05-distributed-git/walkthroughs.md @@ -0,0 +1,73 @@ +# Chapter 5: Distributed Git — Walkthroughs + +## 1. Private Small Team +- **File:** `book/05-distributed-git/sections/contributing.asc` +- **Topic:** Two-developer collaboration workflow on a shared repository +- **Scenario:** John and Jessica clone a shared repo, make changes, push, handle rejected pushes, fetch updates, merge, and push again through a full integration cycle +- **Word Count:** 2,159 + +## 2. Private Managed Team +- **File:** `book/05-distributed-git/sections/contributing.asc` +- **Topic:** Multi-developer workflow with parallel feature branches and an integration manager +- **Scenario:** Jessica works on two parallel features — featureA with John and featureB with Josie — creating branches, pushing, fetching, merging remote branches, and handling upstream configuration +- **Word Count:** 1,663 + +## 3. Forked Public Project +- **File:** `book/05-distributed-git/sections/contributing.asc` +- **Topic:** Contributing to a public project through forking +- **Scenario:** Reader clones the main repo, creates topic branches, forks the project, adds the fork as a remote, pushes, creates pull requests, rebases when needed, and handles multiple feature submissions +- **Word Count:** 2,129 + +## 4. Public Project over Email +- **File:** `book/05-distributed-git/sections/contributing.asc` +- **Topic:** Email-based patch contribution workflow +- **Scenario:** Reader creates topic branches, uses `git format-patch` to generate patch files, configures Git IMAP/SMTP settings in `~/.gitconfig`, and sends patches via `git imap-send` or `git send-email` +- **Word Count:** 1,651 + +## 5. Applying Patches with git apply +- **File:** `book/05-distributed-git/sections/maintaining.asc` +- **Topic:** Applying email patches using `git apply` +- **Scenario:** Maintainer applies patches received via email, checks patches before applying, understands differences from the `patch` command, and handles the manual staging/commit process +- **Word Count:** 471 + +## 6. Applying Patches with git am +- **File:** `book/05-distributed-git/sections/maintaining.asc` +- **Topic:** Applying format-patch generated patches with `git am` +- **Scenario:** Maintainer uses `git am` for clean applies, resolves conflicts with manual editing, uses the `-3` option for three-way merges, and handles interactive mode for multiple patches +- **Word Count:** 1,068 + +## 7. Checking Out Remote Branches +- **File:** `book/05-distributed-git/sections/maintaining.asc` +- **Topic:** Fetching and reviewing contributor branches +- **Scenario:** Maintainer adds a contributor's repository as a remote, fetches from it, and checks out remote branches to test contributed work, including one-time pulls without permanent remotes +- **Word Count:** 432 + +## 8. Determining What Is Introduced +- **File:** `book/05-distributed-git/sections/maintaining.asc` +- **Topic:** Reviewing contributed changes with diff and log analysis +- **Scenario:** Maintainer uses `git log`, `git diff`, and `git merge-base` with triple-dot syntax to understand what changes a topic branch will introduce when merged +- **Word Count:** 533 + +## 9. Tagging Your Releases +- **File:** `book/05-distributed-git/sections/maintaining.asc` +- **Topic:** Creating signed tags and distributing PGP keys +- **Scenario:** Maintainer creates signed tags for releases, distributes their PGP public key in the repository as a blob, and enables others to verify signed tags by importing keys +- **Word Count:** 393 + +## 10. Generating a Build Number +- **File:** `book/05-distributed-git/sections/maintaining.asc` +- **Topic:** Creating human-readable version identifiers with `git describe` +- **Scenario:** Maintainer uses `git describe` to generate version strings for builds, understanding the output format and its use in archiving +- **Word Count:** 279 + +## 11. Preparing a Release +- **File:** `book/05-distributed-git/sections/maintaining.asc` +- **Topic:** Creating distributable release archives +- **Scenario:** Maintainer uses `git archive` to generate tarball and zip formats with proper directory structure for distribution +- **Word Count:** 237 + +## 12. The Shortlog +- **File:** `book/05-distributed-git/sections/maintaining.asc` +- **Topic:** Generating a summary of commits for release announcements +- **Scenario:** Maintainer uses `git shortlog` to produce an author-grouped commit summary since the last release, suitable for mailing list announcements +- **Word Count:** 220 diff --git a/00-notes/06-github/walkthroughs.md b/00-notes/06-github/walkthroughs.md new file mode 100644 index 000000000..66e2d7537 --- /dev/null +++ b/00-notes/06-github/walkthroughs.md @@ -0,0 +1,55 @@ +# Chapter 6: GitHub — Walkthroughs + +## 1. SSH Access Configuration +- **File:** `book/06-github/sections/1-setting-up-account.asc` +- **Topic:** Adding SSH keys to a GitHub account +- **Scenario:** Reader navigates to GitHub account settings, opens the SSH keys section, and pastes their public key to enable SSH-based authentication +- **Word Count:** 181 + +## 2. Avatar Upload and Configuration +- **File:** `book/06-github/sections/1-setting-up-account.asc` +- **Topic:** Replacing the default GitHub avatar +- **Scenario:** Reader navigates to the Profile tab, uploads a custom image, and crops it for their profile picture +- **Word Count:** 128 + +## 3. Creating a Pull Request +- **File:** `book/06-github/sections/2-contributing.asc` +- **Topic:** Full fork-and-PR contribution workflow +- **Scenario:** Reader forks the Arduino "blink" project, clones it locally, creates a topic branch, modifies LED delay timing in the code, commits, pushes to their fork, and opens a Pull Request on GitHub +- **Word Count:** 715 + +## 4. Iterating on a Pull Request +- **File:** `book/06-github/sections/2-contributing.asc` +- **Topic:** Responding to reviewer feedback on a Pull Request +- **Scenario:** Reader receives review comments, makes additional commits to the topic branch, pushes updates, and observes the collaborative review cycle through GitHub's UI +- **Word Count:** 279 + +## 5. Keeping up with Upstream +- **File:** `book/06-github/sections/2-contributing.asc` +- **Topic:** Resolving merge conflicts in a Pull Request +- **Scenario:** Reader adds the original repository as a remote, fetches upstream changes, merges the upstream master branch, resolves conflicts, and pushes the updated branch +- **Word Count:** 392 + +## 6. Setting up and Testing GitHub Webhooks +- **File:** `book/06-github/sections/5-scripting.asc` +- **Topic:** Configuring webhooks with a Ruby Sinatra service +- **Scenario:** Reader builds a webhook handler that checks commit metadata (pusher, branch, files) and sends email notifications, then configures and tests the webhook through GitHub's settings +- **Word Count:** 366 + +## 7. Making API Calls to Comment on Issues +- **File:** `book/06-github/sections/5-scripting.asc` +- **Topic:** Authenticating and posting comments via the GitHub API +- **Scenario:** Reader generates a personal access token, constructs an authenticated `curl` POST request, and posts a comment on a GitHub issue +- **Word Count:** 272 + +## 8. Changing Pull Request Status via API +- **File:** `book/06-github/sections/5-scripting.asc` +- **Topic:** Automated commit validation using webhooks and the Status API +- **Scenario:** Reader builds a Ruby Sinatra webhook handler that checks commit messages for "Signed-off-by", parses webhook payloads, and posts commit status updates back to GitHub +- **Word Count:** 409 + +## 9. Keeping a GitHub Fork Up-to-Date +- **File:** `book/06-github/sections/2-contributing.asc` +- **Topic:** Syncing a forked repository with the original upstream +- **Scenario:** Reader syncs their fork using two approaches: a simple one-time `git pull` with a URL, and a more automated configuration using `git remote` setup +- **Word Count:** 359 diff --git a/00-notes/07-git-tools/walkthroughs.md b/00-notes/07-git-tools/walkthroughs.md new file mode 100644 index 000000000..076b7b6a2 --- /dev/null +++ b/00-notes/07-git-tools/walkthroughs.md @@ -0,0 +1,229 @@ +# Chapter 7: Git Tools — Walkthroughs + +## 1. Merge Conflicts +- **File:** `book/07-git-tools/sections/advanced-merging.asc` +- **Topic:** Resolving a merge conflict end-to-end +- **Scenario:** Two branches modify a Ruby `hello.rb` file (one changes line endings and text, another adds documentation); when merged, conflicts arise and are resolved using various Git tools +- **Word Count:** 1,471 + +## 2. Aborting a Merge +- **File:** `book/07-git-tools/sections/advanced-merging.asc` +- **Topic:** Escaping a merge conflict state +- **Scenario:** Reader uses `git merge --abort` and `git reset --hard HEAD` to abandon an in-progress merge +- **Word Count:** 207 + +## 3. Ignoring Whitespace +- **File:** `book/07-git-tools/sections/advanced-merging.asc` +- **Topic:** Resolving whitespace-related merge conflicts +- **Scenario:** Reader re-merges using `-Xignore-space-change` to bypass whitespace differences +- **Word Count:** 284 + +## 4. Manual File Re-merging +- **File:** `book/07-git-tools/sections/advanced-merging.asc` +- **Topic:** Manually resolving conflicts using low-level Git commands +- **Scenario:** Reader extracts conflicted file versions with `git show :1:/:2:/:3:`, processes them through `dos2unix`, and uses `git merge-file` to resolve conflicts +- **Word Count:** 531 + +## 5. Checking Out Conflicts +- **File:** `book/07-git-tools/sections/advanced-merging.asc` +- **Topic:** Viewing conflict markers with additional context +- **Scenario:** Reader uses `git checkout --conflict=diff3` for three-way conflict markers and diff comparison commands to understand merge changes +- **Word Count:** 718 + +## 6. Undoing Merges — Fix the References +- **File:** `book/07-git-tools/sections/advanced-merging.asc` +- **Topic:** Undoing an accidental merge by moving branch pointers +- **Scenario:** Reader uses `git reset --hard HEAD~` to undo an accidental merge by resetting the branch to its pre-merge state +- **Word Count:** 306 + +## 7. Undoing Merges — Reverse the Commit +- **File:** `book/07-git-tools/sections/advanced-merging.asc` +- **Topic:** Reverting a merge commit +- **Scenario:** Reader uses `git revert -m 1 HEAD` to create a new commit that undoes a merge, then navigates the complexity of re-merging after a revert +- **Word Count:** 409 + +## 8. Bundling +- **File:** `book/07-git-tools/sections/bundling.asc` +- **Topic:** Creating and using Git bundle files for offline transfer +- **Scenario:** Reader creates a bundle from a repository, sends it to another person, then clones and pulls updates from the bundle file +- **Word Count:** 1,127 + +## 9. File Annotation with Git Blame +- **File:** `book/07-git-tools/sections/debugging.asc` +- **Topic:** Identifying which commits modified specific lines +- **Scenario:** Reader uses `git blame -L 69,82 Makefile` to annotate lines and `-C` to track code movement across files +- **Word Count:** 407 + +## 10. Binary Search with Git Bisect +- **File:** `book/07-git-tools/sections/debugging.asc` +- **Topic:** Finding the commit that introduced a bug via binary search +- **Scenario:** Reader uses `git bisect` with manual good/bad testing steps, then automates bisect with a test script +- **Word Count:** 788 + +## 11. Staging and Unstaging Files (Interactive) +- **File:** `book/07-git-tools/sections/interactive-staging.asc` +- **Topic:** Selectively staging files using interactive mode +- **Scenario:** Reader uses `git add -i` to interactively stage and unstage files using the revert option +- **Word Count:** 479 + +## 12. Staging Patches +- **File:** `book/07-git-tools/sections/interactive-staging.asc` +- **Topic:** Partially staging a file using patch mode +- **Scenario:** Reader uses `git add -p` to respond to hunks interactively, staging only selected portions of a file +- **Word Count:** 328 + +## 13. Replace — Repository Splitting +- **File:** `book/07-git-tools/sections/replace.asc` +- **Topic:** Splitting and reconnecting repository history with `git replace` +- **Scenario:** Reader splits a repository history into two, creates a base commit with instructions, rebases history, and uses `git replace` to recombine the histories seamlessly +- **Word Count:** 2,118 + +## 14. Rerere — Merge Conflict Resolution Memory +- **File:** `book/07-git-tools/sections/rerere.asc` +- **Topic:** Recording and replaying merge conflict resolutions +- **Scenario:** Reader enables rerere, creates merge conflicts, records resolutions, and has Git automatically reapply those resolutions during a rebase +- **Word Count:** 1,849 + +## 15. Reset — The Three Trees Workflow +- **File:** `book/07-git-tools/sections/reset.asc` +- **Topic:** Understanding Git's three-tree model through the commit lifecycle +- **Scenario:** Reader walks through `git init`/`git add`/`git commit`/edit cycles, observing how HEAD, Index, and Working Directory change at each step via diagrams +- **Word Count:** 1,246 + +## 16. Squashing Commits with Reset +- **File:** `book/07-git-tools/sections/reset.asc` +- **Topic:** Squashing multiple commits into one using `git reset --soft` +- **Scenario:** Reader uses `git reset --soft HEAD~2` combined with `git commit` to collapse multiple commits into a single commit +- **Word Count:** 289 + +## 17. Changing Multiple Commit Messages +- **File:** `book/07-git-tools/sections/rewriting-history.asc` +- **Topic:** Editing commit messages with interactive rebase +- **Scenario:** Reader uses `git rebase -i HEAD~3`, changes `pick` to `edit`, and walks through the amend/continue cycle for each commit +- **Word Count:** 1,020 + +## 18. Squashing Commits (Interactive Rebase) +- **File:** `book/07-git-tools/sections/rewriting-history.asc` +- **Topic:** Combining commits into one using interactive rebase +- **Scenario:** Reader changes `pick` to `squash` in the rebase script, then edits the merged commit message +- **Word Count:** 432 + +## 19. Splitting a Commit +- **File:** `book/07-git-tools/sections/rewriting-history.asc` +- **Topic:** Breaking a single commit into multiple commits +- **Scenario:** Reader uses `edit` in interactive rebase, then `git reset HEAD^` to unstage, followed by multiple `git commit` commands to create separate commits +- **Word Count:** 460 + +## 20. Removing a File from Every Commit +- **File:** `book/07-git-tools/sections/rewriting-history.asc` +- **Topic:** Rewriting history to remove a file from all commits +- **Scenario:** Reader uses `git filter-branch --tree-filter` to remove a file across the entire commit history +- **Word Count:** 234 + +## 21. Git Grep +- **File:** `book/07-git-tools/sections/searching.asc` +- **Topic:** Searching code with Git's built-in grep +- **Scenario:** Reader searches through committed trees using `git grep` with flags (`-n`, `-c`, `-p`, `--and`) to locate patterns in source code +- **Word Count:** 460 + +## 22. Line Log Search +- **File:** `book/07-git-tools/sections/searching.asc` +- **Topic:** Tracking the history of a specific function +- **Scenario:** Reader uses `git log -L :function:file` to view how a specific function changed across commits +- **Word Count:** 294 + +## 23. Signing Tags +- **File:** `book/07-git-tools/sections/signing.asc` +- **Topic:** Creating GPG-signed tags +- **Scenario:** Reader signs a tag with `git tag -s` and views the GPG signature with `git show` +- **Word Count:** 244 + +## 24. Verifying Tags +- **File:** `book/07-git-tools/sections/signing.asc` +- **Topic:** Verifying GPG signatures on tags +- **Scenario:** Reader uses `git tag -v` to verify signed tags, with both success and failure cases shown +- **Word Count:** 234 + +## 25. Signing Commits +- **File:** `book/07-git-tools/sections/signing.asc` +- **Topic:** Creating and verifying GPG-signed commits +- **Scenario:** Reader signs commits with `git commit -S`, verifies signatures with `git log --show-signature` and `%G?` format, and uses `--verify-signatures` for merge/pull +- **Word Count:** 445 + +## 26. Stashing Your Work +- **File:** `book/07-git-tools/sections/stashing-cleaning.asc` +- **Topic:** Saving and restoring in-progress work with git stash +- **Scenario:** Reader saves work with `git stash`, lists stashes, and reapplies them with `--index` to restore staged status +- **Word Count:** 678 + +## 27. Creative Stashing +- **File:** `book/07-git-tools/sections/stashing-cleaning.asc` +- **Topic:** Advanced stash options +- **Scenario:** Reader uses `--keep-index`, `--include-untracked/-u`, and `--patch` for selective stashing of different file categories +- **Word Count:** 435 + +## 28. Creating a Branch from a Stash +- **File:** `book/07-git-tools/sections/stashing-cleaning.asc` +- **Topic:** Applying stashed changes to a new branch +- **Scenario:** Reader uses `git stash branch` to create a new branch with stashed changes cleanly applied +- **Word Count:** 187 + +## 29. Cleaning Your Working Directory +- **File:** `book/07-git-tools/sections/stashing-cleaning.asc` +- **Topic:** Removing untracked files from the working directory +- **Scenario:** Reader uses `git clean` with various flags (`-f -d`, `-n`, `-x`, `-i`) to safely remove untracked files, with a safety warning about data loss +- **Word Count:** 407 + +## 30. Starting with Submodules +- **File:** `book/07-git-tools/sections/submodules.asc` +- **Topic:** Adding a submodule to a project +- **Scenario:** Reader adds a submodule with `git submodule add`, examines `.gitmodules`, and commits the changes +- **Word Count:** 626 + +## 31. Cloning a Project with Submodules +- **File:** `book/07-git-tools/sections/submodules.asc` +- **Topic:** Cloning and initializing a project that contains submodules +- **Scenario:** Reader clones a project, initializes submodules with `git submodule init/update`, and uses `--recurse-submodules` as a shortcut +- **Word Count:** 744 + +## 32. Pulling in Upstream Changes from the Submodule Remote +- **File:** `book/07-git-tools/sections/submodules.asc` +- **Topic:** Updating submodules to the latest upstream version +- **Scenario:** Reader fetches and merges submodule updates, uses `git submodule update --remote`, and configures which branch to track +- **Word Count:** 921 + +## 33. Pulling Upstream Changes from the Project Remote +- **File:** `book/07-git-tools/sections/submodules.asc` +- **Topic:** Syncing superproject changes that update submodule references +- **Scenario:** Reader pulls superproject changes and synchronizes submodules with `git submodule update --init --recursive` and `git submodule sync` +- **Word Count:** 703 + +## 34. Working on a Submodule +- **File:** `book/07-git-tools/sections/submodules.asc` +- **Topic:** Making changes inside submodules +- **Scenario:** Reader checks out branches in submodules and uses `--merge` and `--rebase` options with `git submodule update --remote` for local changes +- **Word Count:** 1,122 + +## 35. Publishing Submodule Changes +- **File:** `book/07-git-tools/sections/submodules.asc` +- **Topic:** Pushing submodule changes before the superproject +- **Scenario:** Reader uses `git push --recurse-submodules=check` and `=on-demand` to ensure submodule changes are pushed before the superproject +- **Word Count:** 544 + +## 36. Merging Submodule Changes +- **File:** `book/07-git-tools/sections/submodules.asc` +- **Topic:** Resolving submodule merge conflicts +- **Scenario:** Reader examines divergent submodule commit SHA-1s, creates branches, and merges submodule changes manually to resolve conflicts +- **Word Count:** 893 + +## 37. Submodule Foreach +- **File:** `book/07-git-tools/sections/submodules.asc` +- **Topic:** Running commands across all submodules +- **Scenario:** Reader uses `git submodule foreach` to stash, create branches, and view diffs across all submodules at once +- **Word Count:** 521 + +## 38. Subtree Merging +- **File:** `book/07-git-tools/sections/subtree-merges.asc` +- **Topic:** Adding a separate project as a subdirectory using subtree merge +- **Scenario:** Reader adds a project via `git read-tree`, pulls upstream changes, and merges them back using the subtree merge strategy +- **Word Count:** 745 diff --git a/00-notes/08-customizing-git/walkthroughs.md b/00-notes/08-customizing-git/walkthroughs.md new file mode 100644 index 000000000..7e28b7197 --- /dev/null +++ b/00-notes/08-customizing-git/walkthroughs.md @@ -0,0 +1,67 @@ +# Chapter 8: Customizing Git — Walkthroughs + +## 1. Setting Up External Merge and Diff Tools with P4Merge +- **File:** `book/08-customizing-git/sections/config.asc` +- **Topic:** Configuring a visual merge/diff tool +- **Scenario:** Reader downloads P4Merge, creates wrapper scripts (`extMerge` and `extDiff`), makes them executable, configures Git to use them via `git config`, tests with `git diff`, and switches to KDiff3 as an alternative +- **Word Count:** 1,348 + +## 2. Diffing Word Documents Using Git Attributes +- **File:** `book/08-customizing-git/sections/attributes.asc` +- **Topic:** Converting binary Word documents to diffable text +- **Scenario:** Reader installs and configures `docx2txt`, creates a wrapper script, configures Git with `git config`, and demonstrates the actual diff output showing changes in a Word document +- **Word Count:** 1,166 + +## 3. Extracting EXIF Data from Images for Diffing +- **File:** `book/08-customizing-git/sections/attributes.asc` +- **Topic:** Diffing image files by extracting EXIF metadata +- **Scenario:** Reader installs `exiftool`, configures it in `.gitattributes` for `.png` files, replaces an image, and runs `git diff` to see textual EXIF metadata changes +- **Word Count:** 542 + +## 4. Implementing C Code Indentation Filter +- **File:** `book/08-customizing-git/sections/attributes.asc` +- **Topic:** Setting up clean/smudge filters for C source files +- **Scenario:** Reader configures `.gitattributes` rules for `*.c` files and sets up `git config` commands to run the `indent` program on commit and `cat` on checkout +- **Word Count:** 287 + +## 5. Setting Up Keyword Expansion with Custom Date Filter +- **File:** `book/08-customizing-git/sections/attributes.asc` +- **Topic:** Custom keyword expansion using clean/smudge filters +- **Scenario:** Reader writes a Ruby script to inject `$Date$` values into files, configures Git filters, creates a test file, commits, and verifies the date substitution on checkout +- **Word Count:** 762 + +## 6. Enforcing Commit Message Format via Server-Side Hooks +- **File:** `book/08-customizing-git/sections/policy.asc` +- **Topic:** Server-side update hook for commit message validation +- **Scenario:** Reader builds a Ruby script in the server-side `update` hook that uses `git rev-list` and `git cat-file` to extract commits, tests messages against a `[ref: XXXX]` regex pattern, and rejects non-compliant pushes +- **Word Count:** 1,115 + +## 7. Implementing User-Based ACL System via Hooks +- **File:** `book/08-customizing-git/sections/policy.asc` +- **Topic:** Path-based access control enforcement with server-side hooks +- **Scenario:** Reader creates an ACL file format, writes a Ruby method to parse ACL rules, uses `git rev-list` and `git log` to identify modified files, and checks user permissions against the ACL +- **Word Count:** 1,496 + +## 8. Testing the Server-Side Enforcement Policies +- **File:** `book/08-customizing-git/sections/policy.asc` +- **Topic:** Verifying server-side hook behavior +- **Scenario:** Reader runs `git push` with a non-compliant commit message to see hook rejection output, then tests a documentation writer attempting to modify files outside their ACL scope +- **Word Count:** 744 + +## 9. Setting Up Client-Side Commit Message Validation +- **File:** `book/08-customizing-git/sections/policy.asc` +- **Topic:** Client-side `commit-msg` hook for pre-push validation +- **Scenario:** Reader creates a Ruby `commit-msg` hook script that validates messages against the regex pattern, demonstrates both failed and successful commits +- **Word Count:** 558 + +## 10. Setting Up Client-Side ACL Permission Checking +- **File:** `book/08-customizing-git/sections/policy.asc` +- **Topic:** Client-side `pre-commit` hook for ACL enforcement +- **Scenario:** Reader creates a `pre-commit` hook that reads the ACL file, uses `git diff-index` to get staged changes, checks permissions, and exits non-zero if the user lacks access +- **Word Count:** 1,101 + +## 11. Setting Up Pre-Rebase Hook to Prevent Pushing Rebased Commits +- **File:** `book/08-customizing-git/sections/policy.asc` +- **Topic:** Pre-rebase hook to protect already-pushed commits +- **Scenario:** Reader creates a `pre-rebase` script using `git rev-list` and `git branch -r` to identify commits already pushed to remote branches, aborting the rebase if any match +- **Word Count:** 688 diff --git a/00-notes/09-git-and-other-scms/walkthroughs.md b/00-notes/09-git-and-other-scms/walkthroughs.md new file mode 100644 index 000000000..dcceb602a --- /dev/null +++ b/00-notes/09-git-and-other-scms/walkthroughs.md @@ -0,0 +1,133 @@ +# Chapter 9: Git and Other Systems — Walkthroughs + +## 1. Git-Mercurial Bridge — Installing git-remote-hg +- **File:** `book/09-git-and-other-scms/sections/client-hg.asc` +- **Topic:** Setting up the git-remote-hg bridge tool +- **Scenario:** Reader downloads the script, installs Python dependencies, and clones a Mercurial test repository +- **Word Count:** 142 + +## 2. Git-Mercurial Bridge — Getting Started +- **File:** `book/09-git-and-other-scms/sections/client-hg.asc` +- **Topic:** Exploring a cloned Mercurial repository from Git +- **Scenario:** Reader clones a Mercurial repository using Git, examines the resulting structure, explores git refs and notes mapping, and sets up `.gitignore` compatibility +- **Word Count:** 557 + +## 3. Git-Mercurial Bridge — Workflow +- **File:** `book/09-git-and-other-scms/sections/client-hg.asc` +- **Topic:** Full round-trip workflow between Git and Mercurial +- **Scenario:** Reader makes local commits, fetches from remote, merges changes, pushes back to Mercurial, and verifies changes on the Mercurial side +- **Word Count:** 476 + +## 4. Git-Mercurial Bridge — Branches and Bookmarks +- **File:** `book/09-git-and-other-scms/sections/client-hg.asc` +- **Topic:** Working with Mercurial bookmarks and branches from Git +- **Scenario:** Reader creates feature branches, pushes branches, handles permanent branches, and learns the differences between Git and Mercurial branching models +- **Word Count:** 782 + +## 5. Git Fusion — Setting Up +- **File:** `book/09-git-and-other-scms/sections/client-p4.asc` +- **Topic:** Setting up the Git Fusion virtual machine for Perforce +- **Scenario:** Reader imports the VM, customizes user passwords, creates a Perforce user, configures SSL verification, and tests the connection +- **Word Count:** 326 + +## 6. Git Fusion — Configuration +- **File:** `book/09-git-and-other-scms/sections/client-p4.asc` +- **Topic:** Understanding Git Fusion configuration files +- **Scenario:** Reader explores global and repository-specific configs, examines branch/view mappings, and reviews user mapping files for Git-Perforce interoperability +- **Word Count:** 660 + +## 7. Git Fusion — Workflow +- **File:** `book/09-git-and-other-scms/sections/client-p4.asc` +- **Topic:** Complete Git Fusion workflow between Git and Perforce +- **Scenario:** Reader clones a repository, makes commits, fetches changes from Perforce, merges conflicts, pushes back, and examines results in Perforce's revision graph +- **Word Count:** 1,009 + +## 8. Git-p4 — Setting Up +- **File:** `book/09-git-and-other-scms/sections/client-p4.asc` +- **Topic:** Configuring environment variables for git-p4 +- **Scenario:** Reader configures `P4PORT` and `P4USER` environment variables to connect to a Perforce server +- **Word Count:** 65 + +## 9. Git-p4 — Getting Started +- **File:** `book/09-git-and-other-scms/sections/client-p4.asc` +- **Topic:** Performing a shallow clone of a Perforce depot +- **Scenario:** Reader uses `git p4 clone` to import a depot, examines the resulting repository structure, and understands git-p4's remote refs +- **Word Count:** 208 + +## 10. Git-p4 — Workflow +- **File:** `book/09-git-and-other-scms/sections/client-p4.asc` +- **Topic:** Complete git-p4 workflow with Perforce +- **Scenario:** Reader makes commits, syncs with the Perforce server, rebases work, submits changes via interactive editor, and handles merge commits +- **Word Count:** 1,317 + +## 11. Git-p4 — Branching +- **File:** `book/09-git-and-other-scms/sections/client-p4.asc` +- **Topic:** Working with multiple Perforce branches in Git +- **Scenario:** Reader detects branches with `--detect-branches`, configures branch mappings, and syncs/submits to multiple branches +- **Word Count:** 445 + +## 12. Git-SVN — Setting Up +- **File:** `book/09-git-and-other-scms/sections/client-svn.asc` +- **Topic:** Creating a local Subversion repository for testing +- **Scenario:** Reader creates a local SVN repo, enables revprop changes, and syncs content from a remote SVN server using `svnsync` +- **Word Count:** 111 + +## 13. Git-SVN — Getting Started +- **File:** `book/09-git-and-other-scms/sections/client-svn.asc` +- **Topic:** Importing a Subversion repository with `git svn clone` +- **Scenario:** Reader clones with `--stdlayout` for trunk/branches/tags layout and examines the resulting Git repository structure and remote refs +- **Word Count:** 409 + +## 14. Git-SVN — Committing Back to Subversion +- **File:** `book/09-git-and-other-scms/sections/client-svn.asc` +- **Topic:** Pushing Git commits back to a Subversion server +- **Scenario:** Reader makes local Git commits and pushes back to SVN using `git svn dcommit`, observing how SVN commit IDs are embedded in commit messages +- **Word Count:** 325 + +## 15. Git-SVN — Pulling in New Changes +- **File:** `book/09-git-and-other-scms/sections/client-svn.asc` +- **Topic:** Syncing when the SVN repository has diverged +- **Scenario:** Reader handles conflicts when SVN diverges from local Git work, using `git svn rebase` to sync and rebase local commits +- **Word Count:** 654 + +## 16. Git-SVN — Creating a New SVN Branch +- **File:** `book/09-git-and-other-scms/sections/client-svn.asc` +- **Topic:** Creating branches in Subversion from Git +- **Scenario:** Reader uses `git svn branch` to create a new branch on the SVN server, understanding the server-side operations +- **Word Count:** 106 + +## 17. Git-SVN — Switching Active Branches +- **File:** `book/09-git-and-other-scms/sections/client-svn.asc` +- **Topic:** Tracking and switching between Subversion branches in Git +- **Scenario:** Reader sets up local Git branches to track SVN branches, merges branches while understanding SVN's linear history model limitations +- **Word Count:** 350 + +## 18. A Custom Importer +- **File:** `book/09-git-and-other-scms/sections/import-custom.asc` +- **Topic:** Building a custom import script using `git fast-import` +- **Scenario:** Reader writes a complete Ruby script that reads a custom source directory structure, generates marks, converts dates, handles files, and pipes everything through `git fast-import` to create a Git repository +- **Word Count:** 1,694 + +## 19. Importing from Mercurial +- **File:** `book/09-git-and-other-scms/sections/import-hg.asc` +- **Topic:** Converting a Mercurial repository to Git +- **Scenario:** Reader clones the source repo, creates author mapping files, runs the `hg-fast-export` tool, and verifies the import +- **Word Count:** 760 + +## 20. Importing from Perforce (Git Fusion) +- **File:** `book/09-git-and-other-scms/sections/import-p4.asc` +- **Topic:** Using Git Fusion for a one-time Perforce-to-Git migration +- **Scenario:** Reader configures project settings and user mappings to produce a native Git repository ready to push to a Git host +- **Word Count:** 70 + +## 21. Importing from Perforce (Git-p4) +- **File:** `book/09-git-and-other-scms/sections/import-p4.asc` +- **Topic:** Using `git p4 clone` for a one-time Perforce import +- **Scenario:** Reader imports a Perforce project with `git p4 clone` and uses `git filter-branch` to clean up git-p4 metadata from commit messages +- **Word Count:** 460 + +## 22. Importing from Subversion +- **File:** `book/09-git-and-other-scms/sections/import-svn.asc` +- **Topic:** Complete SVN-to-Git conversion with post-import cleanup +- **Scenario:** Reader creates author mapping files, uses `git svn clone` with various flags, performs post-import cleanup of branches/tags/refs, and pushes to a new Git server +- **Word Count:** 938 diff --git a/00-notes/10-git-internals/walkthroughs.md b/00-notes/10-git-internals/walkthroughs.md new file mode 100644 index 000000000..a1f4f81e5 --- /dev/null +++ b/00-notes/10-git-internals/walkthroughs.md @@ -0,0 +1,103 @@ +# Chapter 10: Git Internals — Walkthroughs + +## 1. Data Recovery via Reflog +- **File:** `book/10-git-internals/sections/maintenance.asc` +- **Topic:** Recovering lost commits using the reflog +- **Scenario:** Reader uses `git reset --hard` to move master to an older commit, then recovers the lost commits using `git reflog` and `git branch` to re-establish access +- **Word Count:** 445 + +## 2. Data Recovery via git fsck +- **File:** `book/10-git-internals/sections/maintenance.asc` +- **Topic:** Finding dangling commits when the reflog is unavailable +- **Scenario:** Reader deletes the reflog, then uses `git fsck --full` to locate dangling commits and recovers a lost commit via `git branch` +- **Word Count:** 186 + +## 3. Removing Large Objects from History +- **File:** `book/10-git-internals/sections/maintenance.asc` +- **Topic:** Purging accidentally committed large files from repository history +- **Scenario:** Reader adds a large tarball accidentally, removes it, discovers it still takes space, uses `git verify-pack` and `git rev-list` to locate the object, then uses `git filter-branch` to rewrite history, followed by `git gc` and `git prune` +- **Word Count:** 958 + +## 4. Creating and Manipulating Git Objects +- **File:** `book/10-git-internals/sections/objects.asc` +- **Topic:** Understanding Git's content-addressable filesystem via plumbing commands +- **Scenario:** Reader initializes a repo, uses `git hash-object` to store content, `git cat-file` to retrieve it, and stores multiple file versions to understand how blobs work +- **Word Count:** 622 + +## 5. Creating Tree Objects +- **File:** `book/10-git-internals/sections/objects.asc` +- **Topic:** Manually creating tree objects with low-level commands +- **Scenario:** Reader uses `git update-index`, `git write-tree`, and `git read-tree` to create staging areas, write tree snapshots, and combine trees into nested structures +- **Word Count:** 505 + +## 6. Creating Commit Objects +- **File:** `book/10-git-internals/sections/objects.asc` +- **Topic:** Manually creating commit objects +- **Scenario:** Reader creates three sequential commits by hand using `git commit-tree`, examines their structure with `git cat-file`, and views the resulting history with `git log` +- **Word Count:** 272 + +## 7. Object Storage via Ruby +- **File:** `book/10-git-internals/sections/objects.asc` +- **Topic:** Understanding Git's object storage format +- **Scenario:** Reader uses Ruby code to manually construct a header, calculate SHA-1, compress with zlib, write an object to disk, and verify with `git cat-file` +- **Word Count:** 428 + +## 8. Demonstrating Packfiles +- **File:** `book/10-git-internals/sections/packfiles.asc` +- **Topic:** Understanding Git's packfile and delta compression mechanism +- **Scenario:** Reader adds a large file and modifies it, runs `git gc` to trigger packing, then uses `git cat-file` and `git verify-pack` to examine delta compression +- **Word Count:** 583 + +## 9. Creating References Manually +- **File:** `book/10-git-internals/sections/refs.asc` +- **Topic:** Understanding Git references by creating them manually +- **Scenario:** Reader writes a SHA-1 directly to `.git/refs/heads/master`, then uses the safer `git update-ref` to create branches +- **Word Count:** 225 + +## 10. Working with HEAD and Symbolic References +- **File:** `book/10-git-internals/sections/refs.asc` +- **Topic:** Understanding the HEAD file and symbolic-ref mechanism +- **Scenario:** Reader inspects the HEAD file directly, uses `git checkout` and `git symbolic-ref` to manipulate and understand how HEAD tracks the current branch +- **Word Count:** 198 + +## 11. Creating Annotated Tags (Internals) +- **File:** `book/10-git-internals/sections/refs.asc` +- **Topic:** Understanding tag objects at the internals level +- **Scenario:** Reader creates lightweight tags with `git update-ref` and annotated tags with `git tag -a`, then inspects the tag object structure with `git cat-file` +- **Word Count:** 246 + +## 12. Working with Remote References +- **File:** `book/10-git-internals/sections/refs.asc` +- **Topic:** Understanding how Git stores remote-tracking references +- **Scenario:** Reader adds a remote, pushes commits, then inspects the stored reference in `.git/refs/remotes/origin/master` +- **Word Count:** 149 + +## 13. The Dumb Protocol +- **File:** `book/10-git-internals/sections/transfer-protocols.asc` +- **Topic:** Understanding the HTTP dumb protocol for fetching +- **Scenario:** Reader simulates the HTTP fetch process step by step: fetching `info/refs`, checking HEAD, fetching individual commit objects, discovering packfiles, downloading pack indexes, and extracting objects +- **Word Count:** 587 + +## 14. The Smart Protocol — SSH Upload +- **File:** `book/10-git-internals/sections/transfer-protocols.asc` +- **Topic:** Understanding the SSH handshake for pushing data +- **Scenario:** Reader observes how `git push` initiates `send-pack`, the server responds with references and capabilities, and the client transmits the packfile +- **Word Count:** 342 + +## 15. The Smart Protocol — HTTP(S) Upload +- **File:** `book/10-git-internals/sections/transfer-protocols.asc` +- **Topic:** Understanding the HTTP variant for pushing data +- **Scenario:** Reader observes the HTTP handshake (GET for initial info, POST for packfile) and how it differs from SSH +- **Word Count:** 189 + +## 16. The Smart Protocol — SSH Download +- **File:** `book/10-git-internals/sections/transfer-protocols.asc` +- **Topic:** Understanding the SSH handshake for fetching data +- **Scenario:** Reader observes how `fetch-pack` connects to `upload-pack`, the server sends references, and the client sends want/have/done commands to initiate packfile transmission +- **Word Count:** 292 + +## 17. The Smart Protocol — HTTP(S) Download +- **File:** `book/10-git-internals/sections/transfer-protocols.asc` +- **Topic:** Understanding the HTTP variant for fetching data +- **Scenario:** Reader observes the two-request pattern: GET for capabilities, POST with want/have commands to fetch the packfile +- **Word Count:** 129 diff --git a/00-notes/A-git-in-other-environments/walkthroughs.md b/00-notes/A-git-in-other-environments/walkthroughs.md new file mode 100644 index 000000000..cad2d150c --- /dev/null +++ b/00-notes/A-git-in-other-environments/walkthroughs.md @@ -0,0 +1,49 @@ +# Appendix A: Git in Other Environments — Walkthroughs + +## 1. Setting Up Git Bash Completion +- **File:** `book/A-git-in-other-environments/sections/bash.asc` +- **Topic:** Enabling Git tab completion in Bash +- **Scenario:** Reader checks their Git version, retrieves the completion file from Git source, copies it to their home directory, adds a source line to `.bashrc`, and tests with `git chec` +- **Word Count:** 133 + +## 2. Customizing Git Bash Prompt +- **File:** `book/A-git-in-other-environments/sections/bash.asc` +- **Topic:** Displaying Git branch and status in the Bash prompt +- **Scenario:** Reader copies `git-prompt.sh` from Git source, adds configuration lines to `.bashrc` with `GIT_PS1_SHOWDIRTYSTATE` and `PS1` exports, and sees branch/status info in their prompt +- **Word Count:** 132 + +## 3. Setting PowerShell ExecutionPolicy +- **File:** `book/A-git-in-other-environments/sections/powershell.asc` +- **Topic:** Configuring PowerShell script execution for posh-git +- **Scenario:** Reader sets the `ExecutionPolicy` to `RemoteSigned`, learning about scopes (LocalMachine vs CurrentUser) and signing requirements +- **Word Count:** 121 + +## 4. Installing posh-git via PowerShell Gallery +- **File:** `book/A-git-in-other-environments/sections/powershell.asc` +- **Topic:** Installing posh-git using the PowerShell package manager +- **Scenario:** Reader runs `Install-Module` commands, handles scope options (CurrentUser vs AllUsers), and resolves potential failures with PowerShellGet and certificates +- **Word Count:** 153 + +## 5. Updating PowerShell Prompt for Git +- **File:** `book/A-git-in-other-environments/sections/powershell.asc` +- **Topic:** Importing posh-git and configuring the prompt +- **Scenario:** Reader executes `Import-Module` and `Add-PoshGitToProfile` to display Git information in their PowerShell prompt on startup +- **Word Count:** 89 + +## 6. Installing posh-git from Source +- **File:** `book/A-git-in-other-environments/sections/powershell.asc` +- **Topic:** Manual posh-git installation from a downloaded release +- **Scenario:** Reader downloads a release, uncompresses it, imports the module using a full file path, and adds it to their profile for automatic loading +- **Word Count:** 73 + +## 7. Setting Up Zsh Git Tab Completion +- **File:** `book/A-git-in-other-environments/sections/zsh.asc` +- **Topic:** Enabling Git tab completion in Zsh +- **Scenario:** Reader adds a single command to `.zshrc` and learns about Zsh's richer completion interface with descriptions and graphical navigation +- **Word Count:** 90 + +## 8. Customizing Zsh Prompt with Git Branch Information +- **File:** `book/A-git-in-other-environments/sections/zsh.asc` +- **Topic:** Displaying Git branch in the Zsh prompt using vcs_info +- **Scenario:** Reader adds `vcs_info` configuration lines to `~/.zshrc`, chooses between right-side (RPROMPT) or left-side (PROMPT) display, and sees the result +- **Word Count:** 144 diff --git a/00-notes/B-embedding-git/walkthroughs.md b/00-notes/B-embedding-git/walkthroughs.md new file mode 100644 index 000000000..17842723e --- /dev/null +++ b/00-notes/B-embedding-git/walkthroughs.md @@ -0,0 +1,25 @@ +# Appendix B: Embedding Git in your Applications — Walkthroughs + +## 1. JGit — Getting Set Up +- **File:** `book/B-embedding-git/sections/jgit.asc` +- **Topic:** Configuring JGit as a dependency in a Java project +- **Scenario:** Reader adds JGit via Maven `pom.xml` dependency, with an alternative path for manually managing binary dependencies and compiling on the command line +- **Word Count:** 130 + +## 2. JGit — Plumbing API +- **File:** `book/B-embedding-git/sections/jgit.asc` +- **Topic:** Using JGit's low-level plumbing API for repository operations +- **Scenario:** Reader creates and opens repositories using `FileRepositoryBuilder`, retrieves references, gets object IDs, performs rev-parse operations, loads raw object contents, creates/deletes branches, and reads configuration values +- **Word Count:** 721 + +## 3. JGit — Porcelain API +- **File:** `book/B-embedding-git/sections/jgit.asc` +- **Topic:** Using JGit's high-level porcelain APIs with fluent builders +- **Scenario:** Reader performs a `git ls-remote`-like operation using the `Git` class, setting up credentials, chaining method calls, and iterating over results +- **Word Count:** 212 + +## 4. Libgit2 — Crafting a Commit (Ruby Bindings) +- **File:** `book/B-embedding-git/sections/libgit2.asc` +- **Topic:** Creating a commit programmatically using Rugged (Libgit2 Ruby bindings) +- **Scenario:** Reader follows 8 sequential steps: writing a blob, populating the index, creating a signature, crafting a commit object with tree/author/committer/message/parents/ref parameters, and looking up the resulting commit +- **Word Count:** 203 diff --git a/00-notes/C-git-commands/walkthroughs.md b/00-notes/C-git-commands/walkthroughs.md new file mode 100644 index 000000000..416a026d7 --- /dev/null +++ b/00-notes/C-git-commands/walkthroughs.md @@ -0,0 +1,3 @@ +# Appendix C: Git Commands — Walkthroughs + +This appendix is a reference listing of Git commands grouped by purpose. It contains no walkthroughs — each command entry is a brief description pointing to where the command is used elsewhere in the book. From ee324e06465a529d2e3df571b0210e2bb71108d4 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 20 Mar 2026 03:03:38 +0000 Subject: [PATCH 08/17] Add UX designer revision notes for all chapters and appendices Per-chapter analysis of how Pro Git content can be adapted for UX designers, including priority ratings, design tool analogies, content gaps, and structural recommendations. https://claude.ai/code/session_011MhF8iWLG3rS5jturtiTZ5 --- .../ux-designer-revision-notes.md | 137 ++++++++++++++++++ .../ux-designer-revision-notes.md | 110 ++++++++++++++ .../ux-designer-revision-notes.md | 121 ++++++++++++++++ .../ux-designer-revision-notes.md | 109 ++++++++++++++ .../ux-designer-revision-notes.md | 100 +++++++++++++ .../06-github/ux-designer-revision-notes.md | 85 +++++++++++ .../ux-designer-revision-notes.md | 131 +++++++++++++++++ .../ux-designer-revision-notes.md | 105 ++++++++++++++ .../ux-designer-revision-notes.md | 92 ++++++++++++ .../ux-designer-revision-notes.md | 110 ++++++++++++++ .../ux-designer-revision-notes.md | 96 ++++++++++++ .../ux-designer-revision-notes.md | 77 ++++++++++ .../ux-designer-revision-notes.md | 85 +++++++++++ 13 files changed, 1358 insertions(+) create mode 100644 00-notes/01-introduction/ux-designer-revision-notes.md create mode 100644 00-notes/02-git-basics/ux-designer-revision-notes.md create mode 100644 00-notes/03-git-branching/ux-designer-revision-notes.md create mode 100644 00-notes/04-git-server/ux-designer-revision-notes.md create mode 100644 00-notes/05-distributed-git/ux-designer-revision-notes.md create mode 100644 00-notes/06-github/ux-designer-revision-notes.md create mode 100644 00-notes/07-git-tools/ux-designer-revision-notes.md create mode 100644 00-notes/08-customizing-git/ux-designer-revision-notes.md create mode 100644 00-notes/09-git-and-other-scms/ux-designer-revision-notes.md create mode 100644 00-notes/10-git-internals/ux-designer-revision-notes.md create mode 100644 00-notes/A-git-in-other-environments/ux-designer-revision-notes.md create mode 100644 00-notes/B-embedding-git/ux-designer-revision-notes.md create mode 100644 00-notes/C-git-commands/ux-designer-revision-notes.md diff --git a/00-notes/01-introduction/ux-designer-revision-notes.md b/00-notes/01-introduction/ux-designer-revision-notes.md new file mode 100644 index 000000000..af905c459 --- /dev/null +++ b/00-notes/01-introduction/ux-designer-revision-notes.md @@ -0,0 +1,137 @@ +# Chapter 1: Getting Started — UX Designer Revision Notes + +## Overview +Chapter 1 introduces version control concepts, Git fundamentals, installation, and first-time setup. For UX designers, the chapter's strongest connection point is the designer mention in "About Version Control" (line 8), but most content uses programmer-centric examples and terminology. + +--- + +## Section: About Version Control (`about-version-control.asc`) + +### Priority: HIGH + +**What Resonates:** +- The concrete pain point of "reverting selected files back to a previous state" maps directly to design iteration +- The mention of keeping "every version of an image or layout" (line 8) validates designers' primary use case + +**What Confuses:** +- The local vs. centralized vs. distributed progression uses only programmer VCS tools (RCS, CVS, Subversion, Perforce) — designers don't know these systems +- "Single point of failure" (line 44) is abstract — needs a concrete design scenario + +**Suggested Analogies:** +- CVCS = Figma's single shared file (everyone connects to one server); DVCS = full local copy plus cloud sync +- Centralized VCS = one master design system file; Distributed VCS = each designer has full history locally + +**Revision Suggestions:** +- After line 8's designer mention, add a concrete scenario: "For example, if you're designing a button component and iterate through five visual treatments, version control lets you go back to any treatment without losing the others." +- In the CVCS section, add: "This is similar to a shared Figma file — if the server is unavailable, no one can work." +- In the DVCS section, add: "With Git, you have the entire project history on your laptop — like having Figma's version history downloaded locally." + +**Gaps:** +- No mention of design-specific workflows (branching for design exploration, merging variations) +- Missing context about binary file support — does Git handle `.sketch`, `.psd`, `.figma` files? + +--- + +## Section: What is Git? (`what-is-git.asc`) + +### Priority: HIGH + +**What Resonates:** +- "Every time you commit... Git takes a picture of what all your files look like" maps to design versioning +- The three states (modified/staged/committed) parallel design workflow: draft → ready for review → approved + +**What Confuses:** +- SHA-1 hash explanation is irrelevant to most designers +- "Stream of snapshots" is jargon — designers think "version history" +- Git directory/working tree/staging area uses file system terminology that doesn't map to design tools + +**Suggested Analogies:** +- Snapshots = Figma version history entries +- Staging area = selecting which components/artboards to include in this release +- Modified/Staged/Committed = tweaked but unsaved / marked ready for this update / officially part of design system v2.1 + +**Revision Suggestions:** +- Add after snapshot explanation: "In design terms, each commit is a snapshot of all your designs at a specific moment — identical to Figma's version history." +- Simplify SHA-1 section to: "Every commit is identified uniquely and permanently. You don't need to understand the technical detail." +- Rework three states with design workflow example + +**Gaps:** +- Binary file handling not mentioned — crucial for designers +- No preview of collaboration workflow (push/pull) + +--- + +## Section: A Short History of Git (`history.asc`) + +### Priority: LOW + +- Linux kernel / BitKeeper context doesn't resonate with designers +- Could add: "For design teams, these properties mean: Git handles hundreds of design files, supports non-linear workflows, and is fully decentralized." +- Low priority for revision — historical flavor, doesn't impact learning + +--- + +## Section: First-Time Git Setup (`first-time-setup.asc`) + +### Priority: MEDIUM + +**What Resonates:** +- Setting identity for attribution — designers understand this from design file history + +**What Confuses:** +- Three-level config hierarchy is overly technical for first interaction +- Editor setup (Vim/Emacs/Notepad++) doesn't reflect designer workflows — they typically use VS Code + +**Revision Suggestions:** +- After identity setup, add: "Just like Figma records who made each change, Git attributes every commit to you using this name and email." +- Add note: "If you're using a GUI client (GitHub Desktop, GitKraken), editor configuration is optional." +- Simplify config hierarchy explanation + +--- + +## Section: Installing Git (`installing.asc`) + +### Priority: MEDIUM + +**Revision Suggestions:** +- Add decision tree before platform sections: quick path per OS +- Cut or drastically shorten "Installing from Source" (irrelevant for 95% of designers) +- Add note about GUI clients as alternatives (GitHub Desktop, GitKraken) +- Add verification step (how to confirm installation worked) + +--- + +## Section: The Command Line (`command-line.asc`) + +### Priority: LOW-MEDIUM + +- Acknowledge GUI alternatives for design teams: "GitHub Desktop, GitKraken, or VS Code's built-in Git tools cover most design workflows." +- Soften the CLI-only stance — many designers work exclusively in GUIs + +--- + +## Section: Getting Help (`help.asc`) + +### Priority: LOW-MEDIUM + +- Replace IRC channel references with modern resources (Stack Overflow, Discord, Slack) +- Reorder help methods: put `-h` flag first (quicker, easier) before full manpage options + +--- + +## Cross-Cutting Gaps + +| Gap | Action | +|-----|--------| +| Binary file support | Flag early that `.sketch`, `.psd`, `.figma` files are binary; Git handles them but merging is difficult | +| GUI client recommendations | Name specific tools: GitHub Desktop (simple), GitKraken (visual), VS Code (integrated) | +| Design system collaboration | Frame a design system repository as a compelling use case | +| Branching for design iteration | Preview that branches let designers explore multiple directions simultaneously | + +## Key Analogies to Weave Throughout + +1. Figma version history = Git commits +2. Design tokens = Configuration files +3. Figma shared file = Centralized VCS vs. Git local+sync = Distributed +4. Component variants = Branches +5. Figma Teams library = Shared repository diff --git a/00-notes/02-git-basics/ux-designer-revision-notes.md b/00-notes/02-git-basics/ux-designer-revision-notes.md new file mode 100644 index 000000000..5c4f289b6 --- /dev/null +++ b/00-notes/02-git-basics/ux-designer-revision-notes.md @@ -0,0 +1,110 @@ +# Chapter 2: Git Basics — UX Designer Revision Notes + +## Overview +Chapter 2 is the most critical chapter for UX designer adaptation. It covers the daily Git workflow (init, clone, status, add, commit, diff, log, remotes, tags, undoing). All examples use generic code files — every walkthrough needs design-relevant replacements. + +--- + +## Section: Getting a Repository (`getting-a-repository.asc`) + +### Priority: MEDIUM + +**Issues:** +- Designers rarely init repos — they usually clone existing design system repos +- No mention of `.gitignore` for design tools or large binary design files + +**Revision Suggestions:** +- Add scenario: "Initializing a design system repository" with token files, component guidelines, color palettes +- Add example: `git clone https://github.com/company/design-system-tokens` +- Add sidebar: "Git clone is like downloading a shared Figma project — you get the full history and all branches" + +--- + +## Section: Recording Changes (`recording-changes.asc`) + +### Priority: CRITICAL + +**Issues:** +- Staging area concept is unfamiliar — designers think "save file" not "stage then commit" +- All examples use `.c` files, `README`, `Rakefile` — none resonate with designers +- `.gitignore` section doesn't mention design tool temp files + +**Suggested Analogies:** +- Staging = preparing assets for export; gathering related changes before finalizing +- File status = Figma draft vs. published states +- `git add` = selecting components in Sketch for export + +**Revision Suggestions:** +- Replace all generic examples with design files: `design-tokens.json`, `components-documentation.md`, exported assets +- Add `.gitignore` template for designers: `*.sketch~`, `*.figma_cache`, design software temp folders +- Add tip: "Commit design documentation (text files) separately from exported assets (binary files). Text merges; binary doesn't." +- Add "Commit Messages for Design Teams" subsection with examples: + - Good: "Add button component variants for mobile breakpoints" + - Good: "Update primary color from #1a73e8 to #1f71e8 (accessibility fix)" + - Good: "BREAKING: Rename spacing token `sm` to `small`" + +**New Content Needed:** +- Sidebar: "Git & Design Files Compatibility Matrix" (tokens JSON = mergeable, Figma source = don't commit, SVG exports = version-control friendly) +- Subsection: "Setting Up a Design System Repository" (init, .gitignore, add tokens, add docs, initial commit) + +--- + +## Section: Working with Remotes (`remotes.asc`) + +### Priority: LOW-MEDIUM + +- Add design team remote example: origin = team design system, secondary remote = design token library from another team +- Replace libgit2/grit examples with design system repos + +--- + +## Section: Tagging (`tagging.asc`) + +### Priority: MEDIUM + +- Tags map perfectly to design system releases — leverage this +- Replace generic `v1.4` with: `git tag -a design-system-v2.1.0 -m "Release: new button variants, updated tokens, accessibility audit pass"` +- Add: "For design systems, annotated tags are essential — document what changed so teams know which version they're using" + +--- + +## Section: Undoing Things (`undoing.asc`) + +### Priority: MEDIUM + +- Add design-focused amend scenario: committed button docs, forgot accessibility notes, amend to include them +- Add warning: "Avoid amending commits already shared with the team — it rewrites history" +- Add `git restore` scenario: "Accidentally staged a large Figma export; use `git restore --staged` to unstage without losing the file" + +--- + +## Section: Viewing History (`viewing-history.asc`) + +### Priority: MEDIUM + +- Add design-specific log examples: + - `git log -S "primary-blue" --oneline -- design-tokens.json` (find when a color changed) + - `git log --author="Sarah" --oneline -- components/` (see teammate's component updates) + - `git log --grep="BREAKING" --oneline` (find breaking changes) +- Add tip: "Use consistent commit message prefixes (FEATURE:, FIX:, BREAKING:, DOCS:) to make history searchable" + +--- + +## Section: Git Aliases (`aliases.asc`) + +### Priority: LOW + +- Add design-team sidebar with suggested aliases: + - `git config --global alias.design-changes 'log --oneline -- design-tokens.json components/'` + - `git config --global alias.design-releases 'log --grep="RELEASE" --oneline'` + +--- + +## Cross-Cutting Gaps + +| Gap | Severity | Action | +|-----|----------|--------| +| Binary vs. text files | CRITICAL | Add early subsection explaining what works in Git and what doesn't for design files | +| Design system workflows | HIGH | Thread design system collaboration throughout | +| Commit message standards | MEDIUM | Add guidelines specific to design changes | +| Collaboration context | MEDIUM | Preview branching early so staging/commit workflow doesn't feel isolated | diff --git a/00-notes/03-git-branching/ux-designer-revision-notes.md b/00-notes/03-git-branching/ux-designer-revision-notes.md new file mode 100644 index 000000000..bdf75d5ff --- /dev/null +++ b/00-notes/03-git-branching/ux-designer-revision-notes.md @@ -0,0 +1,121 @@ +# Chapter 3: Git Branching — UX Designer Revision Notes + +## Overview +Chapter 3 covers branching mechanics, merging, rebasing, remote branches, and branch management. The concepts map well to design workflows (parallel explorations, feature isolation), but all examples use generic developer scenarios. + +--- + +## Section: Branches in a Nutshell (`nutshell.asc`) + +### Priority: MEDIUM + +**What Resonates:** Snapshot concept is intuitive for designers (parallels design file versions) + +**What Confuses:** +- Pointer mechanics (SHA-1, HEAD) feel abstract +- "41 bytes" lightweight emphasis doesn't connect to designer workflows + +**Revision Suggestions:** +- Branch as design variant: "Like keeping a mobile-responsive version alongside desktop in Figma" +- HEAD as active artboard: "HEAD = the artboard you're currently editing; checkout = switching artboards" +- Replace generic "testing" branch with `design-tokens-dark-mode` +- Remove 41-byte technical detail — provides no actionable value + +--- + +## Section: Basic Branching and Merging (`basic-branching-and-merging.asc`) + +### Priority: HIGH + +**What Resonates:** The hotfix interruption scenario works for designers (they get interrupted too) + +**Revision Suggestions:** +- Reframe example: "Working on checkout flow redesign (iss53), urgent button color bug reported, create hotfix branch, fix, merge, return to redesign" +- Replace `index.html` conflicts with design token file conflicts (two teammates changed `$button-primary-color` differently) +- Add design system merge scenario: two designers — one added `disabled` state, other added `size` variant +- Mention `git merge --no-ff` as a design team best practice (preserves the record that a whole design system version was integrated) + +**Gaps:** +- No guidance on merge strategy choices for design teams +- No mention of conflict resolution for non-code files (design system JSON, Figma exports) + +--- + +## Section: Branching Workflows (`workflows.asc`) + +### Priority: HIGH + +**What Resonates:** Progressive-stability branching maps perfectly to design system maturity levels + +**Suggested Analogies:** +- `main` = Released design system (in production, stable) +- `develop` = Reviewed, approved designs (queued for next release) +- `feature/button-redesign` = Work-in-progress component (under review) + +**Revision Suggestions:** +- Replace "pu" (proposed updates) with design-relevant naming +- Add design system release workflow example +- Add branch naming conventions for design: `feature/`, `fix/`, `docs/`, `design-system/` +- Address: "Should I create a branch for every component change?" (guidelines on when to branch vs. not) + +--- + +## Section: Rebasing (`rebasing.asc`) + +### Priority: HIGH (conceptually difficult for designers) + +**What Confuses:** Most abstract operation — designers won't have a mental model for "rewinding and replaying commits" + +**Suggested Analogies:** +- Rebase as "replay edits on a cleaner foundation" — like moving a sketch to a different layer +- Merge vs. Rebase as documentation style: Merge = "both states valid"; Rebase = "cleaned-up final story" + +**Revision Suggestions:** +- Design example: "Rebase your new button style onto main to ensure it respects newly merged accessibility updates" +- Add clear guidance: "Should I rebase or merge?" — team culture decision for design teams +- De-emphasize "Rebase When You Rebase" subsection (advanced recovery) — move to troubleshooting +- Simplify patch-id explanation to: "Git can often detect if the same change was applied twice" + +--- + +## Section: Remote Branches (`remote-branches.asc`) + +### Priority: MEDIUM + +**Suggested Analogies:** +- Remote branches as "published" versions: local `button-component` = your draft; `origin/button-component` = published version +- Tracking branches as a "link": "whenever I pull, automatically merge from origin's version" + +**Revision Suggestions:** +- Replace `serverfix` with `design-system-tokens-v3` +- Add collaboration context: what happens when two designers push to the same branch? +- Add PR workflow mention — critical for design review before merging + +--- + +## Section: Branch Management (`branch-management.asc`) + +### Priority: LOW + +- Add branch naming conventions for design teams +- Rename example from generic to `fix/button-hover-state` +- Add guidance on cleanup cadence: how often should a design team prune old branches? + +--- + +## New Content Recommendations + +1. **Branch Naming for Design Teams** — `feature/component-name`, `fix/issue-type`, `docs/`, `design-system/version` +2. **Design System Branching Strategy** — main (released), develop (next release), feature branches for new components +3. **Collaborative Workflows for Design Teams** — multiple designers, PR/review process, managing tokens and component libraries +4. **Design-Specific Merge Conflicts** — JSON design token conflicts, Figma exports, how mergetool helps + +## Example Replacements Throughout + +| Current | Suggested | +|---------|-----------| +| `vim test.rb` | `tokens.json` | +| `index.html` | `button-component.tsx` | +| `email.support@github.com` | design token conflict | +| "issue-tracking system" | "design system version" | +| "deploy" | "release" | diff --git a/00-notes/04-git-server/ux-designer-revision-notes.md b/00-notes/04-git-server/ux-designer-revision-notes.md new file mode 100644 index 000000000..b82cf8d8e --- /dev/null +++ b/00-notes/04-git-server/ux-designer-revision-notes.md @@ -0,0 +1,109 @@ +# Chapter 4: Git on the Server — UX Designer Revision Notes + +## Overview +Chapter 4 covers collaborative Git setup through remote repositories. For UX designers, this chapter is moderately relevant but severely misaligned — most design teams use hosted platforms (GitHub, GitLab), not self-hosted servers. The heavy focus on server administration creates an accessibility barrier. + +**Key structural recommendation:** Reorder chapter to lead with hosted options (currently buried at the end), then present self-hosting as optional. + +--- + +## Section: The Protocols (`protocols.asc`) + +### Priority: MEDIUM + +- Local Protocol parallels shared design asset drives (Dropbox, Google Drive) — make this connection +- Add "Protocol Choice for Design Teams" matrix: small team → GitHub; medium team → GitLab; large org → self-hosted GitLab +- Simplify HTTP protocol cons — irrelevant if using GitHub/GitLab +- Replace security language with designer framing: "Unencrypted transfers — avoid if design files contain proprietary work" + +--- + +## Section: Getting Git on a Server (`git-on-a-server.asc`) + +### Priority: MEDIUM + +- Reframe bare repository: "A bare repository is like a server copy in Figma — not edited directly, only used as a central reference point" +- Replace generic "my_project" with "brand-system.git" or "component-library.git" +- Rename "Small Setups" to "Controlling Who Can Access What" — maps to design governance +- Add scenario: UI designers push, lead designers approve, QA/developers have read-only + +--- + +## Section: SSH Key Generation (`generating-ssh-key.asc`) + +### Priority: MEDIUM (major friction point for non-developers) + +- Lead with hosted alternatives: "Most teams use GitHub/GitLab, which handle SSH setup through their web interface" +- Simplify passphrase section — remove `ssh-agent` discussion +- Add context: "The `.pub` file is safe to share. The other file is secret — like a password." + +--- + +## Section: Setting Up the Server (`setting-up-server.asc`) + +### Priority: LOW (irrelevant for 95% of design teams) + +- Add prominent NOTE: "This section is for organizations with on-premises requirements. Most teams should use GitHub/GitLab instead." +- Replace chmod permission commands with conceptual explanation + +--- + +## Section: Git Daemon (`git-daemon.asc`) + +### Priority: VERY LOW + +- Move to "Advanced/Self-Hosted" appendix — designers almost never self-host public repos + +--- + +## Section: GitWeb (`gitweb.asc`) + +### Priority: LOW + +- Lead with: "If you're using GitHub/GitLab, they provide much better interfaces. Skip this." +- Keep `git instaweb` demo as quick preview option + +--- + +## Section: Smart HTTP (`smart-http.asc`) + +### Priority: LOW-MEDIUM + +- Frame as: "HTTP/HTTPS for teams more comfortable with passwords than SSH keys — but GitLab is easier" + +--- + +## Section: GitLab (`gitlab.asc`) + +### Priority: HIGH (most relevant section for modern design teams) + +- Reframe administration for designers: Users → "Team Members"; Groups → "Design System Teams"; Projects → "Each Git repository" +- Add design system governance: branch protection rules, merge request assignment to senior designers, labels (component update, breaking change) +- Add design artifacts context: GitLab can version design tokens JSON, exported SVGs, design documentation + +--- + +## Section: Third Party Hosted Options (`hosted.asc`) + +### Priority: HIGH (should be moved to position 2 in chapter) + +- Expand with GitHub vs. GitLab comparison table +- Add design-specific features comparison: branch protection, wikis/Pages for docs, integrations with Figma/Slack +- Note: "Works with design files? Yes. Built-in design collaboration? No — use Figma for that." + +--- + +## New Content Needed + +1. **Design System Governance with Git** — role mapping, branch protection, approval workflows, release tagging +2. **Quick Start: GitHub for Design Teams** — create repo, invite team, set protection, define roles (5-minute guide) +3. **Exporting Design Artifacts to Git** — Figma → JSON metadata, Sketch → SVG exports, design tokens → YAML/JSON + +## Tone Shifts + +| Current | Designer-Friendly | +|---------|-------------------| +| "Setting up a Git server" | "Choosing where to host your design system repository" | +| "SSH public key authentication" | "How to securely log in to your repository" | +| "Bare repository" | "Central repository that your team pushes to" | +| "Firewall/port configuration" | "Make sure your team can reach the server" | diff --git a/00-notes/05-distributed-git/ux-designer-revision-notes.md b/00-notes/05-distributed-git/ux-designer-revision-notes.md new file mode 100644 index 000000000..65f4bdfdc --- /dev/null +++ b/00-notes/05-distributed-git/ux-designer-revision-notes.md @@ -0,0 +1,100 @@ +# Chapter 5: Distributed Git — UX Designer Revision Notes + +## Overview +Chapter 5 covers distributed workflows, contributing to projects, and maintaining projects. The contributing section contains the book's most detailed walkthroughs. Most examples use generic code scenarios — all need design-specific rewrites. The email-based patch workflow is largely irrelevant to modern design teams. + +--- + +## Section: Distributed Workflows (`distributed-workflows.asc`) + +### Priority: MEDIUM + +**Revision Suggestions:** +- Add "Design-Specific Workflows" subsection comparing: single-designer projects, small design team (integration-manager), multi-team design system (larger branch structures) +- Rewrite Dictator/Lieutenants intro: "Rarely used by design teams, but appears in orgs like Material Design or Bootstrap where design system decisions go through governance layers." +- Add callout: "As a UX designer, you'll most likely use Integration-Manager (fork + PR) for open-source design projects, or Centralized Workflow for internal team projects." + +--- + +## Section: Contributing to a Project (`contributing.asc`) + +### Priority: HIGH + +**Commit Guidelines (lines 33-99):** +- Remove `git diff --check` for whitespace — irrelevant to designers +- Replace Tim Pope template with design-focused one: `[Component: Button] Updated hover state colors` +- Remove `git add --patch` reference or reframe: "For designers, it's usually easier to commit entire design files at once" + +**Private Small Team (lines 101-325):** +- Replace all file references (`lib/simplegit.rb`) with `design-tokens/colors.json`, `components/Button.sketch` +- Reframe scenario: Sarah redesigns checkout button, Marcus refines form layout, they coordinate pushes + +**Private Managed Team (lines 327-497):** +- Rename branches: `featureA` → `feature/checkout-redesign`, `featureB` → `feature/design-system-forms` +- Add side note: "Ideal when your team is split: one pair working on checkout experience, another improving the form component library." + +**Forked Public Project (lines 499-636):** +- Keep mostly as-is — fork model is intuitive for designers +- Reframe `--squash`: "Collapses all experimental changes into one commit, like flattening iteration layers into a single 'Final Design' layer before exporting" +- Add: "Many design projects (Design Systems, Icon Libraries) use this workflow." + +**Public Project over Email (lines 638-791):** +- Add prominent note: "This section describes an older contribution workflow. Most modern design projects use GitHub/GitLab pull requests instead. Skip unless contributing to a legacy project." +- Consider moving to appendix + +--- + +## Section: Maintaining a Project (`maintaining.asc`) + +### Priority: HIGH + +**Working in Topic Branches (lines 8-29):** +- Replace `sc/ruby_client` with design-relevant names: `sc/icon-overhaul`, `megan/color-palette-v2` +- Add note: "Unlike code, design changes often span multiple file types. Coordinate with your team to ensure changes are consistent." + +**Applying Patches from Email (lines 31-182):** +- Add intro: "Most design projects use GitHub/GitLab pull requests instead. This applies primarily to older or academic projects." + +**Checking Out Remote Branches (lines 184-218):** +- Good as-is — add designer example: "Aisha sends you a link to her design-tokens branch." + +**Determining What Is Introduced (lines 220-294):** +- Add design example: "You want to see exactly what icons Aisha designed that aren't in the main system yet." + +**Integrating Contributed Work (lines 296-402):** +- Add "Design System Release Cycle" example: master = v2.1 (published), develop = ongoing improvements, quarterly merge to master +- Label Large-Merging Workflows as "advanced — for massive projects, not typical design systems" + +**Tagging Releases (lines 428-482):** +- Add: "Include release notes listing new/updated components and token changes" +- Simplify PGP signing: "Optional for design systems. For open-source design systems, signed tags add credibility." + +**Preparing a Release (lines 505-528):** +- Add: `git archive develop --prefix='design-system-v2.1/' --format=zip` for distributing assets to teams without Git + +**The Shortlog (lines 531-557):** +- Add: "Sarah (3): Redesigned form inputs, Added checkbox variations, Updated form spacing." + +--- + +## New Content Needed + +1. **"Design Systems & Collaborative Design" subsection** — repo structure, when to use Git vs. native design tool collaboration, token versioning +2. **Design-Specific Gotchas callout** — binary file merges are impossible; naming conventions matter more in small teams; releases tied to tags +3. **Practical walkthrough scenarios:** + - "You're working on checkout redesign. Teammate is refining form components. How do you coordinate?" + - "You want to contribute icons to Material Design. How?" + - "You're releasing design system v2.0. What do you commit, tag, and archive?" + +## Walkthrough Relevance Summary + +| Walkthrough | Relevance | Action | +|-------------|-----------|--------| +| Private Small Team | High | Revise with design examples | +| Private Managed Team | High | Revise with design context | +| Forked Public Project | High | Keep mostly as-is, clarify for design | +| Public Project over Email | Low | Remove or archive as legacy | +| Applying Patches (git apply/am) | Low-Medium | Trim, recommend PRs instead | +| Checking Out Remote Branches | High | Keep, add design examples | +| Determining What Is Introduced | High | Enhance with asset review examples | +| Tagging/Release/Shortlog | High | Keep, add design system context | diff --git a/00-notes/06-github/ux-designer-revision-notes.md b/00-notes/06-github/ux-designer-revision-notes.md new file mode 100644 index 000000000..e48f07ce0 --- /dev/null +++ b/00-notes/06-github/ux-designer-revision-notes.md @@ -0,0 +1,85 @@ +# Chapter 6: GitHub — UX Designer Revision Notes + +## Overview +Chapter 6 covers GitHub account setup, contributing (forking, PRs), maintaining projects, organizations, and scripting/API. This is one of the most relevant chapters for designers since GitHub is their primary interaction point. However, examples use developer scenarios (Arduino blink project) and miss design-specific workflows. + +--- + +## Section: Account Setup (`1-setting-up-account.asc`) + +### Priority: MEDIUM + +- Add SSH analogy: "Like a trusted device in Figma — once registered, no re-authentication needed" +- Expand email linking: "If you use studio and personal accounts, link both emails so GitHub tracks your total contribution history" +- Add 2FA context for design teams: "Prevents a compromised password from putting all your team's collaborative work at risk" + +--- + +## Section: Contributing (`2-contributing.asc`) + +### Priority: HIGH + +**Forking (lines 5-26):** +- Replace historical baggage note with: "Forking is like duplicating a shared design file to your own workspace" + +**GitHub Flow / Creating a PR (lines 29-195):** +- Replace Arduino blink example with design system contribution: "Maria wants to add a Tooltip component — she forks, branches, adds component files (SVG, CSS, tokens), commits, pushes, opens PR with light/dark mode screenshots" + +**Iterating on a PR (lines 147-205):** +- Add: "You don't need changes to be 'perfect' before opening a PR. Opening early lets your team weigh in on direction." + +**Keeping up with Upstream (lines 224-296):** +- Add design token sync scenario: "If the original design system updates token values, how do I sync my fork?" + +**GitHub Flavored Markdown — Images (lines 476-486):** +- EXPAND this section: "Drag-and-drop images into PR comments for design reviews. Show before/after comparisons, highlight accessibility concerns with annotations, demonstrate responsive behavior." + +**Keeping Forks in Sync (lines 488-548):** +- Add design system context for syncing fork with upstream + +**Gaps:** +- No mention of GitHub's PR diff viewer limitations for binary files (PNGs, SVGs) — designers need to upload screenshots separately +- No guidance on branching strategy for design work +- Missing: how to link PRs to issues + +--- + +## Section: Maintaining a Project (`3-maintaining.asc`) + +### Priority: MEDIUM-HIGH + +- Add design-specific CONTRIBUTING example: icon grid size, accessibility standards, design token naming convention, review criteria, link to Figma +- Expand README for design projects: screenshot/GIF of key components, link to design file, component-to-file mapping, accessibility matrix +- Add new subsection: "Branch Protection for Design Systems" — require PR reviews before merging to main +- Add versioning guidance: use Git tags for design system releases, document changes in CHANGELOG + +--- + +## Section: Managing an Organization (`4-managing-organization.asc`) + +### Priority: MEDIUM + +- Add motivation: "If you're building a design system with 3+ contributors, an organization makes it easier to grant access to multiple repos and maintain consistent governance" +- Expand teams with design examples: `@core-designers` (read/write all), `@contributors` (specific repos), `@stakeholders` (read-only), `@a11y-reviewers` (mentioned for accessibility reviews) + +--- + +## Section: Scripting GitHub (`5-scripting.asc`) + +### Priority: MEDIUM + +- Add design-relevant webhook example: "When someone opens a PR on your design system, automatically post to #design-reviews Slack channel" +- Add GitHub Actions context (successor to Services): "Actions let you validate icon sizes, generate component previews, or deploy documentation" +- Add design-specific validation example: "Check committed SVG files for missing `` elements or poor contrast" +- Simplify API section for designers: "Most automation tasks are easier via GitHub Actions than manual API calls" + +--- + +## Cross-Cutting Themes + +1. **Design Tools Integration (missing entirely):** Storing design exports, linking to Figma, using GitHub Pages for design docs, automated sync +2. **Design Systems as Use Case:** Different workflows than software — visual review, asset naming, documentation priority, versioning +3. **Asynchronous Collaboration:** "Unlike Figma's real-time collaboration, GitHub is async. Write clear PR descriptions with context, include screenshots, expect 24-48 hours for feedback." +4. **Visual Workflows:** Current examples (Arduino blink) don't resonate — need design system PR with component screenshots +5. **GitHub Pages:** Not mentioned but critical for hosting design system documentation +6. **Access Control:** Need role-based explanation (viewer, contributor, maintainer) with design team mapping diff --git a/00-notes/07-git-tools/ux-designer-revision-notes.md b/00-notes/07-git-tools/ux-designer-revision-notes.md new file mode 100644 index 000000000..b60982705 --- /dev/null +++ b/00-notes/07-git-tools/ux-designer-revision-notes.md @@ -0,0 +1,131 @@ +# Chapter 7: Git Tools — UX Designer Revision Notes + +## Overview +Chapter 7 is the largest tools chapter with 38 walkthroughs. Relevance varies widely — stashing, reset, submodules, and interactive staging are highly relevant; bundling, signing, and advanced filter-branch are low relevance. All examples use code files and need design-specific replacements. + +--- + +## Section: Advanced Merging (`advanced-merging.asc`) + +### Priority: HIGH + +- Replace `hello.rb` with a realistic design scenario (design token JSON, component definitions) +- Add design system subsection: merge conflict resolution for `tokens.json` or `components.yaml` +- Introduce three-tree analogy: "component in your local artboard (working directory), version in shared library (HEAD), library version someone else committed (incoming branch)" +- De-emphasize manual `dos2unix` preprocessing (too code-specific) + +--- + +## Section: Stashing and Cleaning (`stashing-cleaning.asc`) + +### Priority: MEDIUM-HIGH + +- Replace `index.html`/`lib/simplegit.rb` with `design-tokens.json`, `icons/` directory, component metadata +- Add "Design Iteration Pausing" scenario: stash new icon set while shipping a production bug fix +- Expand branch-from-stash: "Perfect when you start design exploration on main and realize it should be a feature branch" +- Clarify `git clean` dangers: "If design exports were untracked, `git clean` removes them permanently" + +--- + +## Section: Reset Demystified (`reset.asc`) + +### Priority: MEDIUM + +- Redesign three-tree metaphor: HEAD = last published design system version, Index = staged for next release, Working Directory = current design canvas +- Replace `file.txt` with `design-system-v1.0.json` +- Add practical scenario: staged both `typography.tokens.json` and `colors.tokens.json`, want to commit only typography now +- Expand squashing: collapse "Add heading font size" + "Oops, wrong size" + "Fix heading size" into clean "Update heading typography" + +--- + +## Section: Rewriting History (`rewriting-history.asc`) + +### Priority: MEDIUM + +- Add prominent shared-history warning for designers on shared repos +- Design scenario for amend: "Committed 'Update button styles' but forgot focus state CSS" +- Design scenario for split: "One commit refactors spacing tokens AND updates button styles — split for separate review" +- De-emphasize filter-branch — move to appendix; frame as "if you accidentally committed large .psd files" + +--- + +## Section: Interactive Staging (`interactive-staging.asc`) + +### Priority: MEDIUM + +- Replace file names with design files: `design-system/colors.json`, `icons/icon-library.json` +- Add "Design Token Staging" use case: `tokens.json` has updates to both color and typography — stage only color changes for current PR + +--- + +## Section: Debugging (`debugging.asc`) + +### Priority: LOW-MEDIUM + +- Git blame: "A color value in your design tokens changed three commits ago and broke styles. Use `git blame colors.json` to find which commit introduced it." +- Git bisect: mark as optional/advanced — "If you're maintaining a large design system..." + +--- + +## Section: Searching (`searching.asc`) + +### Priority: LOW-MEDIUM + +- Reframe for design system maintenance: "Find all components using the old `primary-blue` token" +- Mark as "more relevant for design system maintainers than individual designers" + +--- + +## Section: Signing (`signing.asc`) + +### Priority: LOW + +- Add one line: "If your organization requires signed commits for compliance, configure GPG here. Most design teams don't use this." + +--- + +## Section: Bundling (`bundling.asc`) + +### Priority: VERY LOW + +- UX designers rarely transfer repos offline — remove or move to appendix + +--- + +## Section: Submodules (`submodules.asc`) + +### Priority: MEDIUM-HIGH + +- Keep and expand with design example: "Your main product repo includes a design system as a submodule. Update submodule pointers when the design system releases a new version." + +--- + +## Section: Replace / Subtree Merges + +### Priority: VERY LOW + +- Too advanced for most designers — mark as "For Repository Maintainers Only" + +--- + +## Revision Priority Summary + +| Section | Relevance | Priority | Action | +|---------|-----------|----------|--------| +| Advanced Merging | Low | HIGH | Replace code examples; add design system scenario | +| Stashing & Cleaning | Medium-High | MEDIUM-HIGH | Add design-specific examples | +| Reset | High | MEDIUM | Redesign metaphor with design vocabulary | +| Rewriting History | Medium | MEDIUM | Add caution; de-emphasize filter-branch | +| Interactive Staging | High | MEDIUM | Replace examples with design files | +| Debugging | Medium | LOW-MEDIUM | Keep blame; soften bisect | +| Searching | Medium | LOW-MEDIUM | Reframe for system maintainers | +| Signing & Bundling | Low | LOWEST | Remove or appendix | +| Submodules | Medium-High | MEDIUM-HIGH | Expand with design system use case | + +## New Walkthroughs to Create + +1. "Design System Version Management" — merge commits and submodules +2. "Resolving Design File Merge Conflicts" — practical token/component walkthrough +3. "Staging Design Changes Selectively" — `git add -p` for color vs. typography tokens +4. "Finding When a Design Token Changed" — `git blame` on tokens +5. "Undoing a Design System Release" — `git reset` or `git revert` for breaking changes diff --git a/00-notes/08-customizing-git/ux-designer-revision-notes.md b/00-notes/08-customizing-git/ux-designer-revision-notes.md new file mode 100644 index 000000000..99299a43b --- /dev/null +++ b/00-notes/08-customizing-git/ux-designer-revision-notes.md @@ -0,0 +1,105 @@ +# Chapter 8: Customizing Git — UX Designer Revision Notes + +## Overview +Chapter 8 covers Git configuration, attributes, hooks, and policy enforcement. Several sections have high relevance for design workflows (binary file handling, commit templates, hooks for validation) but are framed entirely for developers. + +--- + +## Section: Git Configuration (`config.asc`) + +### Priority: MEDIUM + +**Keep/Expand:** +- External merge/diff tools (P4Merge) — visual comparison is intuitive for designers +- Commit templates — reframe for design workflows +- Color configuration — designers naturally understand terminal colors + +**Cut/Minimize:** +- `core.autocrlf` and `core.whitespace` — irrelevant to designers shipping design files +- Server-side config — designers don't administer servers + +**Revision Suggestions:** +- Expand diff tools with design token file diffs (JSON/YAML with colors, typography) +- Replace commit template `[Ticket: X]` with: `[Component: Button/Primary]` or `[Design System: v2.1]` +- Add new subsection: "Git Config for Design Workflows" — aliases for design-file diffs, ignoring cache files + +--- + +## Section: Git Attributes (`attributes.asc`) + +### Priority: HIGH + +**High Relevance for Designers:** +- Binary file handling — designers work with binary files constantly (PNG, SVG, Sketch) +- Image diffing with EXIF — designers understand metadata +- Export-ignore — directly applicable: "Exclude design source files from exports but version them in Git" + +**Cut/Replace:** +- C code indentation filter — replace with design-relevant filter (SVG optimization or token transformation) +- Complex Ruby keyword expansion — simplify or replace with design metadata injection + +**Revision Suggestions:** +- Expand binary file identification with design-specific examples: `.sketch`, `.xd`, `.psd`, Figma JSON +- Include a `.gitattributes` template for design repos +- Replace C indent with: "Design token transformation filter — convert JSON to CSS variables on checkout" +- Emphasize export-ignore: "Keep .sketch files in Git but export clean SVG/PNG without source clutter" +- Add merge strategy note: "Design files should use `merge=ours` — each designer keeps their local version" + +--- + +## Section: Git Hooks (`hooks.asc`) + +### Priority: MEDIUM + +**Front-load useful hooks:** +- pre-commit, commit-msg, post-commit first +- De-emphasize email workflow hooks (applypatch-msg, etc.) — designers never use `git am` + +**Add hook use cases:** +- "Use pre-commit to lint design files before committing" +- "Use commit-msg to validate design update descriptions" +- "Use post-commit to trigger design system builds" + +**Provide copy-paste hook scripts** — designers can't write Ruby/Perl + +--- + +## Section: Policy Enforcement (`policy.asc`) + +### Priority: MEDIUM-HIGH + +**Simplify hook examples drastically:** +- Replace full Ruby scripts with pseudo-code or simpler shell scripts +- Add heavy comments explaining each line + +**Create design-specific examples:** +- Commit-msg hook: validate `[Component: ComponentName]` pattern instead of generic `[ref: XXXX]` +- ACL example: Admins = edit anything; Designers = edit screens not tokens; Docs = only edit docs +- Emphasize client-side hooks over server-side (designers care about local validation) + +**Testing section (lines 217-280):** +- Keep — demonstrates actual hook behavior with push attempts +- Add design example: documentation writer trying to modify files outside ACL scope + +**Cut/Simplify:** +- Pre-rebase hook — too complex for designers; present as "advanced tool for team leads" +- Dense Ruby ACL scripts — provide ready-made scripts designers can copy + +--- + +## Content Gaps + +| Gap | Action | +|-----|--------| +| Binary design file handling | Add subsection on storing .sketch, .xd, Figma exports; LFS considerations | +| Design system versioning | Using tags for releases, managing token versions alongside component code | +| Design token management | Storing tokens in Git, version-controlling JSON/YAML, syncing with design tools | +| Asset management | Storing icons, illustrations in Git; organizing and versioning asset libraries | +| Design documentation in Git | Keeping design docs in sync with component code | + +## New Content Needed + +1. `.gitattributes` template for design repos with comments explaining each rule +2. "Design Token Versioning with Git" subsection combining attributes and config +3. Ready-made hook scripts designers can use as-is +4. "Design System Collaboration with Git" walkthrough combining config, attributes, and hooks diff --git a/00-notes/09-git-and-other-scms/ux-designer-revision-notes.md b/00-notes/09-git-and-other-scms/ux-designer-revision-notes.md new file mode 100644 index 000000000..de8d2b7f7 --- /dev/null +++ b/00-notes/09-git-and-other-scms/ux-designer-revision-notes.md @@ -0,0 +1,92 @@ +# Chapter 9: Git and Other Systems — UX Designer Revision Notes + +## Overview +Chapter 9 covers using Git as a client for other VCS (Mercurial, Perforce, Subversion) and importing from those systems. For UX designers, this chapter has low-to-moderate relevance — only SVN migration is plausible in enterprise design contexts. All sections lack design tool analogies and binary asset handling guidance. + +--- + +## Section: Git and Mercurial (`client-hg.asc`) + +### Priority: VERY LOW + +- Mercurial is extremely rare in design team environments +- Consider moving to appendix or adding disclaimer: "Mercurial is rarely used in design workflows" +- If kept, add front-matter: "This section applies only if your organization uses Mercurial" + +--- + +## Section: Git and Perforce (`client-p4.asc`) + +### Priority: LOW-MEDIUM + +- Cut Git Fusion infrastructure details to 5 lines: "Git Fusion requires server-side setup. Contact your DevOps team." +- Add UX-specific note: "More common: your code is in Perforce, design tokens are in Git" +- Add "Working with Assets in Perforce" note about binary file sync differences +- git-p4 is slightly more relevant — add design token update example + +--- + +## Section: Git and Subversion (`client-svn.asc`) + +### Priority: MEDIUM (highest relevance of the three bridges) + +- SVN is the most likely legacy system for design team assets (enterprise archives) +- Add context upfront: "SVN is common in enterprise design environments" +- Create new subsection: "Working with Design Files in SVN" — binary handling, batch commits +- Reframe branching issues with design example: `redesign/components` branch +- Cut/collapse SVN Style History and SVN Annotation (rarely used by designers) + +--- + +## Section: Custom Importer (`import-custom.asc`) + +### Priority: LOW + +- Add intro note: "Applies if migrating from ad-hoc versioning (directory snapshots). Modern teams should use native design tool versioning." +- Add design example: "Your team stored versions as `backup_2023_01_15/components.sketch`" +- Simplify code walkthrough — keep structure, cut low-level fast-import explanation + +--- + +## Section: Importing from Mercurial (`import-hg.asc`) + +### Priority: VERY LOW + +- Reduce to 5-line pointer or remove entirely +- Add disclaimer: "Mercurial migrations are rare in design workflows" + +--- + +## Section: Importing from Perforce (`import-p4.asc`) + +### Priority: LOW-MEDIUM + +- Add "What to Migrate" subsection: full history vs. latest state only +- Add: "For design assets where old versions are less valuable, import only latest state" + +--- + +## Section: Importing from Subversion (`import-svn.asc`) + +### Priority: MEDIUM-HIGH + +- Add "Pre-Import Planning" subsection: check total size (>100MB → consider Git LFS), identify design files for special handling +- Replace "Peg-Revisions" with: "Delete branch names with `@` suffixes — they're SVN-specific" +- Add "Handling Large Design Files" post-cleanup: consider Git LFS for files >50MB + +--- + +## Cross-Cutting Gaps + +| Gap | Action | +|-----|--------| +| Design tool analogies absent | Add sidebar: "How Git Differs from Your Design Tools" | +| Binary asset handling never addressed | Add "Binary Assets" note: Git LFS often necessary for design files | +| Real UX scenarios missing | Add: "I need to version my design system repo" / "My tokens are in code" | +| Terminology barriers | Add glossary mapping SVN/Mercurial/Perforce terms to Git equivalents | + +## Recommended New Content + +1. **"Working with Design Files Across VCS Boundaries"** — when designers encounter legacy VCS, binary handling, decision tree for Git suitability +2. **VCS Terminology Glossary** — mapping terms across systems +3. **UX-Specific Workflow Examples** — SVN design archive migration, Perforce token sync diff --git a/00-notes/10-git-internals/ux-designer-revision-notes.md b/00-notes/10-git-internals/ux-designer-revision-notes.md new file mode 100644 index 000000000..3c4922f5b --- /dev/null +++ b/00-notes/10-git-internals/ux-designer-revision-notes.md @@ -0,0 +1,110 @@ +# Chapter 10: Git Internals — UX Designer Revision Notes + +## Overview +Chapter 10 introduces Git's internal architecture. Currently written for infrastructure engineers, not designers. The core insight: revision should reframe internals through data recovery, collaboration reliability, and practical troubleshooting — not cryptography and protocol mechanics. + +--- + +## Section: Plumbing and Porcelain + +### Priority: HIGH (reframe, don't cut) + +- Add designer-focused opening: "While designers use porcelain commands (commit, push, pull), understanding plumbing reveals how Git prevents data loss — critical when collaborating on high-stakes design assets." +- Reframe `.git` directory exploration: "When you accidentally delete a branch or overwrite changes, Git hasn't lost your work — it's just not visible through normal commands." + +--- + +## Section: Git Objects + +### Priority: HIGH (simplify heavily) + +- Replace "content-addressable filesystem" with design analogy: "Every component gets a unique fingerprint based on its exact appearance. If the button design is identical in two versions, Git recognizes it's the same object." +- Replace `test.txt` with design-specific examples (icon versions, token snapshots) +- Remove or drastically simplify Ruby SHA-1 object storage section (pure cryptography, zero design relevance) +- Expand tree objects with design context: trees represent complete file structure at a moment — "the folder structure in your project snapshot" + +--- + +## Section: Git References + +### Priority: HIGH + +- Reframe: "Branches are just labels — like naming layers in Figma" +- Simplify HEAD: "HEAD is 'where you are now.' When you switch branches, HEAD updates." +- Enhance tags with design example: "Tag your design system as `v2.0` when releasing updated component library" +- Add collaboration context to remotes: "When you push to GitHub, `origin/main` is your local tracking branch — fetch to sync" + +--- + +## Section: Packfiles + +### Priority: MEDIUM-HIGH + +- High relevance for designers with large files — connect to clone/push performance +- Add opening: "When you repeatedly modify a large design file, Git stores one complete version and compressed change records — keeping your repo lean" +- Replace `repo.rb` with `icon-set.svg` or `design-tokens.json` +- Clarify `git gc` is automatic — designers don't need to run it manually +- Add callout: "If your design repo becomes >500MB, consider Git LFS, splitting files, or archiving old versions" + +--- + +## Section: Maintenance and Data Recovery + +### Priority: MEDIUM-HIGH (highest practical relevance) + +- Add reassurance opening: "Accidentally deleted a design commit? Git typically preserves your work for weeks via the reflog." +- Keep reflog walkthrough mostly intact — add scenario header: "You force-reset master, losing recent design changes" +- Simplify fsck: "If reflog is deleted, `git fsck --full` finds dangling commits. Create a branch from one to recover." +- Restructure large object removal: move to "Advanced" section, explain alternatives first (`.gitignore`, Git LFS, delete-and-recreate branch) +- Add "Best Practices for Preventing Data Loss" subsection + +--- + +## Section: Transfer Protocols + +### Priority: LOW-MEDIUM + +- Make optional for designers: "This section is for advanced troubleshooting. Most designers can skip this." +- Replace protocol details with practical troubleshooting: "Why does `git clone` fail?", "Why does push hang?", "SSH vs. HTTPS?" +- Simplify dumb protocol: "Rarely used today; all modern hosting uses smart protocol" + +--- + +## Section: The Refspec + +### Priority: MEDIUM + +- Add designer-focused opening: "Refspecs define which branches you fetch. Useful for managing large multi-branch design systems." +- Add design example: "Your design system has 20 branches (one per component). Fetch only `main` and `buttons-v2`." + +--- + +## Section: Environment Variables + +### Priority: LOW + +- Keep only designer-relevant vars: `GIT_EDITOR`, `GIT_TRACE` (debugging), `GIT_SSH_COMMAND` +- Remove pathspecs, advanced networking, miscellaneous +- Add debugging scenarios: "My `git clone` hangs — use `GIT_TRACE=true`" + +--- + +## Revision Priority Summary + +| Section | Priority | Key Change | +|---------|----------|------------| +| Plumbing & Porcelain | HIGH | Add "why" context for data recovery | +| Objects | HIGH | Replace examples; cut Ruby SHA-1; emphasize immutability | +| References | HIGH | Clarify branches as pointers; design collaboration examples | +| Packfiles | MEDIUM-HIGH | Connect to performance; use design asset examples | +| Maintenance & Recovery | MEDIUM-HIGH | Expand reassurance; simplify walkthroughs | +| Transfer Protocols | LOW-MEDIUM | Make optional; add troubleshooting context | +| Environment Variables | LOW | Keep only designer-relevant vars | +| Refspec | MEDIUM | Add design system branch example | + +## Pedagogical Improvements + +1. Lead with "Why" not "What" — each section should open with why designers care +2. Use consistent design-focused examples throughout (Figma, Sketch, tokens, component libraries) +3. Add reassurance about Git's safety features (reflog, immutability) +4. Reduce cognitive load — cut or defer highly technical content diff --git a/00-notes/A-git-in-other-environments/ux-designer-revision-notes.md b/00-notes/A-git-in-other-environments/ux-designer-revision-notes.md new file mode 100644 index 000000000..c7a8e3b54 --- /dev/null +++ b/00-notes/A-git-in-other-environments/ux-designer-revision-notes.md @@ -0,0 +1,96 @@ +# Appendix A: Git in Other Environments — UX Designer Revision Notes + +## Overview +Appendix A covers terminal shells (Bash, Zsh, PowerShell) and IDE/editor integrations (VS Code, Sublime Text, JetBrains, GUIs). For designers, the IDE/GUI sections are most relevant. Shell configuration is intimidating and less applicable. A decision tree at the start would help designers choose the right section. + +--- + +## Structural Recommendation + +Add a **decision tree** at the beginning: +- "Are you on macOS?" → Zsh section +- "Are you on Windows?" → PowerShell section or GitHub Desktop +- "Are you using VS Code?" → VS Code section +- "Building a design system with React?" → WebStorm section + +--- + +## Section: Graphical Interfaces (`guis.asc`) + +### Priority: MEDIUM-HIGH + +- Add design system branching strategy context +- Clarify when to use Git vs. cloud design tools (Figma's built-in versioning) +- Add `.gitignore` guidance for design artifacts +- Mention design-specific hosting (GitHub vs. Figma version control vs. Abstract/Plant) + +--- + +## Section: VS Code (`visualstudiocode.asc`) + +### Priority: MEDIUM + +- Expand for design token workflows and design system documentation +- Add: "diff in gutter" is like Figma's "track changes" +- Add: when VS Code Git integration is insufficient (binary design files) +- Mention Pull Request extension for design reviews + +--- + +## Section: Sublime Text (`sublimetext.asc`) + +### Priority: LOW + +- Clarify Sublime Merge integration +- Consider recommending VS Code instead for designers + +--- + +## Section: JetBrains IDEs (`jetbrainsides.asc`) + +### Priority: MEDIUM + +- Focus on WebStorm (most relevant to designers building design systems) +- Explain Version Control ToolWindow +- Add design system component workflow example + +--- + +## Section: Bash (`bash.asc`) + +### Priority: LOW + +- Shell configuration is intimidating for designers +- Add context: "The prompt showing branch name prevents committing to the wrong branch — a safety check" +- Simplify technical explanations (`\w`, `\$`) + +--- + +## Section: Zsh (`zsh.asc`) + +### Priority: LOW + +- Note that Zsh is macOS default post-Catalina +- Reference oh-my-zsh as the beginner-friendly path (rather than manual vcs_info config) +- Zsh's graphical tab completion is like Figma's component picker — add this analogy + +--- + +## Section: PowerShell (`powershell.asc`) + +### Priority: LOW + +- Condense ExecutionPolicy to single command — don't explain scopes in detail +- Suggest GitHub Desktop for Windows designers as simpler alternative + +--- + +## Cross-Cutting Gaps + +| Gap | Action | +|-----|--------| +| Design file version control limitations | Git works best with text; design files are binary/proprietary | +| Collaborative design workflows | When to use Git vs. Figma real-time collaboration | +| Design system branching | Managing v1, v2, v3 with branches or tags | +| Asset management | Versioning icons, illustrations, fonts in Git (Git LFS, separate repos, CDN) | +| Tool decision guidance | No help choosing between shell vs. editor, or between editors | diff --git a/00-notes/B-embedding-git/ux-designer-revision-notes.md b/00-notes/B-embedding-git/ux-designer-revision-notes.md new file mode 100644 index 000000000..3fe81e93f --- /dev/null +++ b/00-notes/B-embedding-git/ux-designer-revision-notes.md @@ -0,0 +1,77 @@ +# Appendix B: Embedding Git — UX Designer Revision Notes + +## Overview +Appendix B covers Git libraries for embedding in applications (Libgit2, JGit, go-git, Dulwich, command-line). Currently targets developers building Git-integrated applications. For UX designers, this is relevant in two narrow scenarios: (1) designing applications that embed Git, or (2) understanding how design tools use Git internally. + +**Core recommendation:** Reframe from "how to code Git integration" to "where Git integration appears in design tools and how it affects UX." + +--- + +## Section: Command-Line Git (`command-line.asc`) + +### Priority: LOW (reframe entirely) + +- Replace technical constraints (text parsing, process management) with UX design patterns for Git integration +- Add: "If you're designing applications that integrate Git, expect these user needs: commit messages, branch switching, pull/push, conflict resolution" +- Reference existing products as design patterns: GitHub Desktop, GitKraken, Sublime Merge + +--- + +## Section: Libgit2 (`libgit2.asc`) + +### Priority: LOW-MEDIUM + +- Note it powers GitHub Desktop, GitKraken, Sublime Merge — tools designers actually use +- Add after Rugged example: "In a design tool, users would never see this code — they'd click 'Save Version'" +- Reduce "Other Bindings" subsection — move to reference page +- Cut advanced ODB backends detail or move to footnote + +--- + +## Section: JGit (`jgit.asc`) + +### Priority: LOW + +- Add callout: "plumbing = low-level UX (users handle Git details); porcelain = high-level UX (abstracted away)" +- Note for designers: "A tool using porcelain APIs could auto-merge compatible design token changes (simpler UX)" +- Keep Maven setup for developers; add note that designers can skip to concepts + +--- + +## Section: go-git (`go-git.asc`) + +### Priority: LOW + +- Add context: "Go powers CLI tools designers might use — design token generators, SVG optimization in CI" +- Condense "Advanced Functionality" to plain English: "The tool can optionally store design files in alternative locations" + +--- + +## Section: Dulwich (`dulwich.asc`) + +### Priority: LOW-MEDIUM (most designer-relevant due to Python) + +- Python is widely used in design automation tools and Figma plugins +- Reframe: "Dulwich enables Python-based design tools to add Git versioning" +- Add example: "A Python script that auto-commits design file changes when exporting SVGs" +- Add sidebar: "Common in: Figma plugins, design token scripts, automation tools" + +--- + +## Recommended Restructuring + +**New framing (replace intro):** +> "This appendix is relevant to UX designers in two scenarios: (1) if you're designing applications that embed Git version control, or (2) if you're using Git-aware design tools and want to understand how they work." + +**New section order:** +1. Overview: "Where Git Integration Appears in Design Tools" +2. Command-Line Git → rename to "Git UI Patterns in Applications" +3. Libgit2 → "The Most Popular Git Library" (powers GitHub Desktop) +4. Dulwich → "Git in Python-Based Design Tools" +5. JGit & go-git → consolidate as "Git in Backend Services" (less relevant) + +## Content Gaps + +- No mention of how Git-aware design tools handle version control UX +- No discussion of Git integration with Figma, Sketch, Adobe XD +- Missing: decision framework for when to advocate for Git integration in design tools diff --git a/00-notes/C-git-commands/ux-designer-revision-notes.md b/00-notes/C-git-commands/ux-designer-revision-notes.md new file mode 100644 index 000000000..26d854c65 --- /dev/null +++ b/00-notes/C-git-commands/ux-designer-revision-notes.md @@ -0,0 +1,85 @@ +# Appendix C: Git Commands — UX Designer Revision Notes + +## Overview +Appendix C is a reference listing of Git commands grouped by purpose. For designers, the key revision is to reorganize by workflow (not command taxonomy), highlight the ~15 essential commands, cut irrelevant sections (email workflows, plumbing), and add design-specific scenarios. + +--- + +## Command Relevance Tiers + +### CRITICAL (must understand) +`git init`, `clone`, `branch`, `checkout`, `add`, `commit`, `status`, `log`, `push`, `pull`, `merge`, `tag`, `stash` + +### IMPORTANT (should know) +`git diff`, `reset`, `rm`, `remote`, `fetch`, `show`, `revert`, `clean` + +### NICE-TO-HAVE (contextual) +`git cherry-pick`, `bisect`, `grep`, `blame`, `difftool`, `mergetool`, `config` + +### IRRELEVANT (remove for designer edition) +`git am`, `apply`, `format-patch`, `send-email`, `request-pull`, `imap-send` (email workflows — 48 lines to cut), `git svn`, `fast-import` (external VCS — 16 lines), `ls-files`, `ls-remote`, `rev-parse` (plumbing — 12 lines), `git fsck`, `reflog`, `filter-branch` (administrative) + +--- + +## Structural Recommendation + +Reorganize from command taxonomy to **workflow-based structure:** + +1. **Getting Started** (init, clone, config) +2. **Daily Design Work** (branch, checkout, add, commit, status, diff) +3. **Collaborating** (push, pull, fetch, merge, stash) +4. **Design System Releases** (tag, archive) +5. **Troubleshooting** (reset, revert, log, blame, show) +6. **Advanced** (rebase, cherry-pick, bisect, etc.) + +--- + +## Key Revisions by Section + +**Setup and Config (lines 19-88):** +- Cut massive editor config table (32 lines) — replace with one-liner linking to Chapter 1 + +**Basic Snapshotting (lines 123-222):** +- Reframe `git add`: "Select which artboards/components to include in your export — only staged changes get saved" +- Add design analogy for diff: "Side-by-side component comparison, like Figma's before/after" + +**Branching and Merging (lines 223-313):** +- Expand `git merge` to one paragraph: "When your design iteration is ready, `git merge` combines it back into main. Example: merge `feature/dark-mode` into production design." +- Add design review mention before merging + +**Sharing and Updating (lines 315-387):** +- Reframe `git pull`: "Download the latest design changes from the team repo and merge them into your local branch. Use every morning to stay synchronized." + +**Inspection and Comparison (lines 389-414):** +- Reframe `git log`: "See your design evolution — use `--oneline --graph` to visualize parallel designer work" +- Reframe `git blame`: "Find out who changed a specific design element" + +**Debugging (lines 416-438):** +- Reframe as "understanding your design history" not "debugging code" + +**Email Workflows (lines 472-519):** +- DELETE entirely — replace with: "Modern teams use GitHub/GitLab Pull Requests. See Chapter 6." + +**External Systems (lines 520-535):** +- DELETE — irrelevant unless migrating from SVN + +**Plumbing Commands (lines 570-581):** +- DELETE — add note: "For advanced internals, see Chapter 10" + +--- + +## Missing Content for Designers + +1. **`.gitignore` for design workflows** — exclude temp files, exports, dependencies +2. **Design file merge conflicts** — "Design files conflict differently than code. Merge tools struggle with binary formats." +3. **Commit message conventions** — design-specific examples and prefixes +4. **Branching strategy** — main (production), feature/ (WIP), experimental/ (exploration) +5. **Recovering accidentally deleted designs** — designer-friendly reflog guidance +6. **Quick reference table** — 10 essential commands mapped to designer use cases + +--- + +## Estimated Impact +- Cut ~80 lines of irrelevant content +- Reduce from ~582 lines to ~350 lines +- Significantly improve clarity and relevance for UX designers From a12780729b2855a0ccd7d77f02390be3a77aad72 Mon Sep 17 00:00:00 2001 From: Claude <noreply@anthropic.com> Date: Fri, 20 Mar 2026 15:02:31 +0000 Subject: [PATCH 09/17] Add unified storyline analysis for UX designer edition Proposes "Meadow" wellness app design system as a continuous narrative thread across all chapters. Maps four characters, a product timeline, and artifact continuity to every existing revision recommendation. https://claude.ai/code/session_011MhF8iWLG3rS5jturtiTZ5 --- 00-notes/storyline-analysis.md | 233 +++++++++++++++++++++++++++++++++ 1 file changed, 233 insertions(+) create mode 100644 00-notes/storyline-analysis.md diff --git a/00-notes/storyline-analysis.md b/00-notes/storyline-analysis.md new file mode 100644 index 000000000..e960aeb34 --- /dev/null +++ b/00-notes/storyline-analysis.md @@ -0,0 +1,233 @@ +# Common Storyline Analysis + +## Problem: Fragmented Examples Across Chapters + +The current revision notes propose disconnected examples across chapters: + +- **Inconsistent characters**: Sarah (Ch5), Marcus (Ch5), Aisha (Ch5), Maria (Ch6), Megan (Ch5 branch name only) — none carry between chapters +- **Disconnected artifacts**: button components, checkout flows, form components, icon sets, and design tokens appear repeatedly but without continuity +- **No progression**: each chapter reinvents its scenario from scratch, so readers never build on prior context + +A unified storyline solves all three problems. Readers follow one product, one team, and one set of artifacts from Chapter 1 through Chapter 10, with each chapter advancing the story naturally. + +--- + +## Proposed Storyline: "Meadow" — A Design System for a Wellness App + +### Why This Product +- A wellness/health app is visually rich (illustrations, icons, color palettes, typography) — maximizes design artifact variety +- Broad enough to require multiple component types (forms, cards, navigation, charts, onboarding flows) +- Relatable across industries — not tied to fintech, e-commerce, or gaming jargon +- Naturally involves accessibility concerns (contrast, screen readers, motion sensitivity) + +### The Team + +| Character | Role | Personality Trait | Introduced | +|-----------|------|-------------------|------------| +| **Nora** | Lead Designer / Design System Owner | Methodical, sets standards | Ch1 | +| **Sam** | UI Designer (components) | Moves fast, sometimes forgets to commit cleanly | Ch2 | +| **Priya** | Visual Designer (illustrations, icons) | Works with large binary files | Ch3 | +| **Dev (the developer)** | Frontend Engineer | Bridge between design and code — consumes tokens | Ch5 | + +Four characters are enough to demonstrate solo work, pair collaboration, team coordination, and cross-functional handoff. Each has a trait that naturally triggers specific Git scenarios. + +### The Product Timeline + +The storyline maps to a realistic product lifecycle. Each chapter picks up where the prior left off: + +| Chapter | Story Phase | What Happens | +|---------|-------------|--------------| +| **Ch1** | Discovery | Nora discovers version control after losing a week of work when her "final-v3-REAL" folder gets overwritten. She learns what Git is and installs it. | +| **Ch2** | Foundation | Nora creates the Meadow design system repo. Adds `design-tokens.json`, component documentation, and exported assets. Learns status, add, commit, diff, log. Her first `.gitignore` excludes `.sketch` temp files. | +| **Ch3** | Exploration | Sam joins. They use branches to explore a dark mode variant (`feature/dark-mode`) while Nora continues refining the light theme on `main`. Their first merge conflict: both edited `colors.json`. | +| **Ch4** | Infrastructure | The team picks GitHub to host the repo (not a bare server). Nora sets up branch protection so `main` requires a review before merge. | +| **Ch5** | Collaboration | Priya joins for an icon overhaul. Three designers coordinate: Nora on tokens, Sam on components, Priya on icons. They practice the integration-manager workflow. First design system release (`v1.0`). | +| **Ch6** | Open Source | Meadow's design system goes public on GitHub. An external contributor (Marcus) forks it and submits a PR adding a Tooltip component. Nora reviews, requests changes, merges. | +| **Ch7** | Maturity | The team handles real-world complexity: Sam stashes half-finished button states to fix a production color bug. Priya uses `git blame` to find when an icon color changed. Nora uses interactive rebase to clean up a messy token migration history. | +| **Ch8** | Customization | Nora configures `.gitattributes` for binary design files, sets up a commit message template (`[Component: X]`), and adds a pre-commit hook that validates token JSON syntax. | +| **Ch9** | Migration | The team migrates legacy brand assets from an SVN archive into the Git repo. They handle large binary files and history cleanup. | +| **Ch10** | Mastery | Sam accidentally force-resets `main`, losing recent commits. Nora uses reflog to recover. The chapter demystifies Git internals through the lens of "your work is never truly lost." | +| **App A** | Tooling | The team evaluates VS Code vs. GitHub Desktop vs. CLI for their workflow. Decision tree based on comfort level. | +| **App B** | Integration | The team considers how design tools (Figma plugins, token pipelines) integrate with Git under the hood. | +| **App C** | Reference | Quick-reference card organized by Meadow workflow phases, not command taxonomy. | + +--- + +## Artifact Continuity Map + +These artifacts appear and evolve across chapters, giving readers anchoring reference points: + +### Core Files (appear 5+ chapters) + +| Artifact | First Appears | Evolves Through | Purpose | +|----------|---------------|-----------------|---------| +| `design-tokens.json` | Ch2 (created) | Ch3 (dark mode added), Ch5 (v1.0 release), Ch7 (migration cleanup), Ch8 (validation hook) | The primary "code-like" design file — mergeable, diffable, central to the system | +| `colors.json` (subset of tokens) | Ch2 (initial palette) | Ch3 (merge conflict), Ch5 (coordinated update), Ch7 (blame for change), Ch8 (diff config) | Most relatable file for designers — color values changing | +| `components/button/` | Ch2 (first component) | Ch3 (dark mode variant), Ch5 (Sam's work), Ch7 (stash scenario), Ch8 (commit template) | The universal UI component — every designer understands buttons | +| `.gitignore` | Ch2 (created) | Ch8 (expanded for design tools) | Practical file designers need immediately | +| `README.md` | Ch2 (basic) | Ch6 (expanded for public repo) | Entry point for contributors | + +### Secondary Files (appear 2-3 chapters) + +| Artifact | Chapters | Purpose | +|----------|----------|---------| +| `icons/` directory | Ch5 (Priya creates), Ch7 (blame for color change), Ch10 (packfile performance) | Binary file handling, large asset management | +| `CONTRIBUTING.md` | Ch6 (created for open source), Ch8 (referenced in hooks) | Governance, standards | +| `CHANGELOG.md` | Ch5 (v1.0 release), Ch7 (rewriting history) | Release documentation | +| `typography.json` | Ch7 (selective staging), Ch8 (attributes config) | Second token file for staging/splitting scenarios | + +--- + +## Scene-by-Scene Storyline Mapping to Existing Recommendations + +### Chapter 1 — Discovery + +| Revision Note Recommendation | Storyline Scene | +|------------------------------|-----------------| +| Add concrete scenario after line 8's designer mention | Nora's "final-v3-REAL" folder disaster — she loses a week of button iterations | +| CVCS = Figma shared file analogy | Nora compares her Figma workflow (centralized) to Git (distributed) | +| Three states = draft/ready/approved | Nora maps modified/staged/committed to her existing review process | +| Binary file support flag | Nora asks: "Can I version my Sketch files?" — honest answer about binary limitations | + +### Chapter 2 — Foundation + +| Revision Note Recommendation | Storyline Scene | +|------------------------------|-----------------| +| "Initializing a design system repository" | Nora runs `git init` in the `meadow-design-system` directory | +| Replace `.c` file examples | All examples use `design-tokens.json`, `components/button/button.md`, exported PNGs | +| `.gitignore` template for designers | Nora creates `.gitignore` excluding `.sketch~`, `*.figma_cache`, `node_modules/` | +| Commit message conventions | Nora writes: `Add initial color palette and button component` | +| Design token search in log | Nora uses `git log -S "primary-blue"` to find when she changed the brand color | +| Tags for releases | Nora tags the repo's first stable state: `git tag -a v0.1 -m "Initial token set and button component"` | + +### Chapter 3 — Exploration + +| Revision Note Recommendation | Storyline Scene | +|------------------------------|-----------------| +| Branch as design variant | Sam creates `feature/dark-mode` to explore a dark palette without touching Nora's light theme | +| Hotfix interruption scenario | Sam is working on dark mode; urgent accessibility bug on `main` button contrast — creates `hotfix/button-contrast` | +| Merge conflict in token file | Both Nora and Sam edited `colors.json` — Nora updated `primary-blue`, Sam added `dark-bg`. They resolve together. | +| Branch naming conventions | Team establishes: `feature/`, `fix/`, `hotfix/`, `experiment/` | +| Rebasing as "replay on cleaner foundation" | Sam rebases dark mode onto main to pick up Nora's latest token structure | + +### Chapter 4 — Infrastructure + +| Revision Note Recommendation | Storyline Scene | +|------------------------------|-----------------| +| Lead with hosted options | Nora evaluates GitHub vs. GitLab — picks GitHub for simplicity | +| SSH key setup with context | Sam struggles with SSH keys — Nora walks him through it, comparing `.pub` file to a "trusted device" | +| Branch protection | Nora enables `main` branch protection: PRs required, one approval needed | +| Role mapping | Nora = admin, Sam = write, stakeholders = read-only | + +### Chapter 5 — Collaboration + +| Revision Note Recommendation | Storyline Scene | +|------------------------------|-----------------| +| Three-person coordination | Nora (tokens), Sam (components), Priya (icons) work in parallel on feature branches | +| Replace `lib/simplegit.rb` files | All file references: `design-tokens/colors.json`, `components/Button/`, `icons/navigation/` | +| Integration-manager workflow | Nora acts as integrator — reviews and merges Sam's and Priya's branches | +| Design system release cycle | Team releases Meadow v1.0: tag, archive, changelog | +| Email workflow → skip notice | "Meadow uses GitHub PRs, not email patches" | + +### Chapter 6 — Open Source + +| Revision Note Recommendation | Storyline Scene | +|------------------------------|-----------------| +| Replace Arduino blink with design system PR | Marcus forks Meadow, creates `feature/tooltip-component`, adds SVG + token + docs, opens PR with screenshots | +| Expand image embedding for reviews | Marcus includes light/dark mode screenshots in his PR; Nora annotates with feedback | +| CONTRIBUTING.md for design projects | Nora writes guidelines: icon grid (24x24), token naming (`category-property-variant`), accessibility requirements | +| GitHub Pages for documentation | Team deploys component documentation to `meadow-design-system.github.io` | +| Async collaboration norms | Marcus is in a different timezone — PR review takes 24 hours; Nora leaves detailed written feedback | + +### Chapter 7 — Maturity + +| Revision Note Recommendation | Storyline Scene | +|------------------------------|-----------------| +| Stashing scenario | Sam is halfway through new button states; production color bug reported; stashes work, fixes bug, pops stash | +| `git blame` for design files | Priya uses `git blame icons/navigation/home.svg` to find who changed the icon stroke width | +| Interactive staging | Nora's `design-tokens.json` has both color and typography updates; she stages only color changes for the current PR | +| Reset demystified | Sam accidentally commits to `main` instead of his feature branch — uses `git reset` to move the commit | +| Squashing messy history | Priya squashes "Add home icon" + "Fix home icon size" + "Adjust home icon padding" into clean "Add navigation home icon" | +| Submodules | The product app repo includes `meadow-design-system` as a submodule — Dev updates the pointer when v1.1 releases | + +### Chapter 8 — Customization + +| Revision Note Recommendation | Storyline Scene | +|------------------------------|-----------------| +| `.gitattributes` for binary files | Nora configures: `*.png binary`, `*.sketch binary`, `*.svg diff` | +| Commit message template | Team template: `[Component: Name] Description` — enforced by commit-msg hook | +| Pre-commit hook | Hook validates `design-tokens.json` is valid JSON before allowing commit | +| Image diffing | Nora sets up EXIF-based diffing so `git diff` shows metadata changes on PNG exports | +| Export-ignore | `.sketch` source files are versioned but excluded from release archives | + +### Chapter 9 — Migration + +| Revision Note Recommendation | Storyline Scene | +|------------------------------|-----------------| +| SVN design archive migration | The company's legacy brand assets (logos, illustrations) live in SVN. Nora migrates them into the Meadow repo. | +| Large binary file handling | Migration surfaces 200MB of PSDs — team decides to use Git LFS for files >10MB | +| Pre-import planning | Nora checks total size, identifies files for LFS, plans branch structure | + +### Chapter 10 — Mastery + +| Revision Note Recommendation | Storyline Scene | +|------------------------------|-----------------| +| Reflog for data recovery | Sam runs `git reset --hard` on `main` by accident, losing three commits. Nora uses reflog to recover. | +| Objects as "fingerprints" | Nora explains to Sam: "Every version of every file gets a unique ID. Even if you delete a branch, the data is still there." | +| Packfiles and performance | Priya notices `git push` is slow — learns Git packs similar icon files together | +| References as labels | "Branches are just sticky notes pointing to commits — moving them doesn't destroy anything" | + +### Appendix A — Tooling + +| Revision Note Recommendation | Storyline Scene | +|------------------------------|-----------------| +| Decision tree | Nora uses CLI, Sam prefers VS Code's Git panel, Priya uses GitHub Desktop for visual diffs of icons | +| VS Code for token workflows | Sam edits `design-tokens.json` with inline Git diff highlighting | + +### Appendix B — Integration + +| Revision Note Recommendation | Storyline Scene | +|------------------------------|-----------------| +| Design tool internals | Priya wonders how Figma plugins could auto-commit exported assets — learns about Dulwich (Python Git library) | +| UX patterns for Git integration | Nora sketches a "version control panel" for a design tool prototype | + +### Appendix C — Reference + +| Revision Note Recommendation | Storyline Scene | +|------------------------------|-----------------| +| Workflow-based organization | Commands grouped by Meadow workflow: "Starting your day" (pull, status), "Making changes" (add, commit), "Sharing work" (push, PR), "Releasing" (tag, archive) | + +--- + +## Key Benefits of the Unified Storyline + +1. **Progressive complexity**: readers learn Git operations in the order they'd encounter them on a real project +2. **Emotional investment**: readers care about Nora's team and their product — mistakes feel relatable, not abstract +3. **Artifact familiarity**: by Chapter 5, `design-tokens.json` and `colors.json` are old friends — readers focus on the Git concept, not parsing new file names +4. **Natural motivation**: each chapter answers "why do I need this?" through the story's progression (branching because Sam joined, GitHub because they went public, hooks because they need quality gates) +5. **Character-driven scenarios**: Sam's sloppiness triggers stash/reset/recovery lessons; Priya's binary files trigger LFS/attributes lessons; Nora's leadership triggers governance/hooks/release lessons + +--- + +## Risks and Mitigations + +| Risk | Mitigation | +|------|------------| +| Storyline feels forced in reference chapters (App C) | Use storyline as organizational principle, not narrative prose | +| Readers skip chapters and miss context | Each chapter opens with a 2-line "Previously in Meadow" recap | +| Product choice alienates some readers | "Wellness app" is generic enough; swap product name without breaking any examples | +| Characters feel contrived | Keep characterization minimal — traits emerge from actions, not descriptions | +| Chapters 9-10 have low design relevance | Migration and internals are naturally "advanced" — storyline justifies why the team encounters them | + +--- + +## Implementation Priority + +| Priority | Action | Impact | +|----------|--------|--------| +| 1 | Lock character names and roles across all chapters | Consistency foundation | +| 2 | Define the `meadow-design-system` repo file structure used in examples | Artifact continuity | +| 3 | Rewrite Ch1-3 examples with storyline (highest reader volume) | First impression | +| 4 | Rewrite Ch5-6 collaboration examples (most design-relevant) | Core value proposition | +| 5 | Update Ch7-8 tool examples with established artifacts | Builds on familiarity | +| 6 | Adapt Ch4, Ch9-10, appendices last (lowest impact) | Completeness | From 1f4a3811e64f88ec1ecb1f376640ad315d952841 Mon Sep 17 00:00:00 2001 From: Claude <noreply@anthropic.com> Date: Sun, 29 Mar 2026 03:27:17 +0000 Subject: [PATCH 10/17] Add task document for storyline rewrite to AI prototyping product Documents the pivot from design system to an AI-powered rapid prototyping product that generates 5 options from a single sketch, covering the full product lifecycle. https://claude.ai/code/session_011MhF8iWLG3rS5jturtiTZ5 --- 00-notes/storyline-rewrite-task.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 00-notes/storyline-rewrite-task.md diff --git a/00-notes/storyline-rewrite-task.md b/00-notes/storyline-rewrite-task.md new file mode 100644 index 000000000..9215601dd --- /dev/null +++ b/00-notes/storyline-rewrite-task.md @@ -0,0 +1,29 @@ +# Task: Rewrite Storyline Analysis + +## Status: In Progress + +## What Changed +The original `storyline-analysis.md` proposed "Meadow" — a design system for a wellness app — as the unifying storyline across all chapters. **A design system is not a product.** The storyline needs to follow a real product through a real design and development lifecycle. + +## New Direction +Replace the design system storyline with an **AI-powered rapid prototyping product** that: +- Generates up to **5 design options in parallel** from a single sketch +- Covers the **full product lifecycle**: research, concept design, UI design, visual design, development, testing, launch, iteration +- Gives readers a product they can follow from idea through shipping + +## Why This Product +- **Rich design artifact variety**: research docs, personas, journey maps, wireframes, mockups, prototypes, icons, illustrations, motion specs, design tokens, and production assets +- **Parallel generation is inherently visual**: 5 options from 1 sketch naturally produces branching/merging scenarios (each option is a branch; the chosen direction merges to main) +- **AI component adds modern relevance**: model configs, training data references, prompt templates — files that are text-based and Git-friendly alongside binary design files +- **Full lifecycle coverage**: unlike a design system (which is infrastructure), a product has research phases, concept phases, user testing, pivots, launches, and post-launch iteration — each mapping to different Git workflows + +## Requirements for the Rewrite +1. Replace all "Meadow design system" references with the new product concept +2. Redefine the team to reflect product roles (researcher, concept designer, UI/visual designer, engineer) +3. Remap the chapter timeline to product lifecycle phases (research → concept → design → build → test → launch → scale) +4. Update all artifact continuity maps to reflect product files (research briefs, personas, wireframes, screen mockups, prototype configs, AI model params) +5. Update all scene-by-scene mappings to use product scenarios +6. Preserve the structural framework (problem statement, benefits, risks, implementation priority) + +## File to Update +`00-notes/storyline-analysis.md` From bf97d6b61a65875b23d4c814b05493f5e5e6e1a5 Mon Sep 17 00:00:00 2001 From: Claude <noreply@anthropic.com> Date: Mon, 30 Mar 2026 12:55:33 +0000 Subject: [PATCH 11/17] Rewrite storyline around AI-powered rapid prototyping product MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace design system concept with "SketchSpark" — an AI tool that generates 5 UI options from a single sketch. Covers full product lifecycle: research, concept design, UI design, build, beta, launch. Product's parallel generation mirrors Git's branching model. https://claude.ai/code/session_011MhF8iWLG3rS5jturtiTZ5 --- 00-notes/storyline-analysis.md | 257 ++++++++++++++++++--------------- 1 file changed, 141 insertions(+), 116 deletions(-) diff --git a/00-notes/storyline-analysis.md b/00-notes/storyline-analysis.md index e960aeb34..cb63e31f1 100644 --- a/00-notes/storyline-analysis.md +++ b/00-notes/storyline-analysis.md @@ -12,200 +12,224 @@ A unified storyline solves all three problems. Readers follow one product, one t --- -## Proposed Storyline: "Meadow" — A Design System for a Wellness App +## Proposed Storyline: "SketchSpark" — AI-Powered Rapid Prototyping + +### The Product +SketchSpark is an AI-powered rapid prototyping application. A designer uploads or draws a rough sketch, and the system generates up to 5 polished UI options in parallel. The designer reviews, selects, and refines a direction — then iterates toward a shippable product. ### Why This Product -- A wellness/health app is visually rich (illustrations, icons, color palettes, typography) — maximizes design artifact variety -- Broad enough to require multiple component types (forms, cards, navigation, charts, onboarding flows) -- Relatable across industries — not tied to fintech, e-commerce, or gaming jargon -- Naturally involves accessibility concerns (contrast, screen readers, motion sensitivity) +- **Parallel generation mirrors Git branching**: 5 options from 1 sketch = 5 branches from 1 commit. The core metaphor is baked into the product itself. +- **Full design lifecycle**: research (user interviews, competitive analysis), concept design (sketches, information architecture), UI design (wireframes, mockups), visual design (high-fidelity screens, motion), development, testing, launch, iteration — every phase produces distinct artifacts that need version control. +- **Rich artifact variety**: research briefs, persona documents, journey maps, wireframes, AI model configuration files, prompt templates, training data manifests, screen mockups, icon sets, motion specs, design tokens, and production assets — a mix of text (Git-friendly) and binary (Git-challenged) files that naturally teaches both workflows. +- **AI component adds modern relevance**: model configs (`model-params.yaml`), prompt templates (`prompts/sketch-to-ui.txt`), and generation pipelines are text files that merge cleanly — contrasting with binary mockup files that don't. +- **Accessible domain**: every designer understands "sketch to prototype" — no industry-specific jargon required. ### The Team | Character | Role | Personality Trait | Introduced | |-----------|------|-------------------|------------| -| **Nora** | Lead Designer / Design System Owner | Methodical, sets standards | Ch1 | -| **Sam** | UI Designer (components) | Moves fast, sometimes forgets to commit cleanly | Ch2 | -| **Priya** | Visual Designer (illustrations, icons) | Works with large binary files | Ch3 | -| **Dev (the developer)** | Frontend Engineer | Bridge between design and code — consumes tokens | Ch5 | +| **Nora** | UX Lead / Product Owner | Methodical researcher, sets standards, writes the briefs | Ch1 | +| **Sam** | UI/Visual Designer | Fast mover, generates options quickly, sometimes commits messy | Ch2 | +| **Priya** | Concept Designer / Illustrator | Works with large binary files (sketches, illustrations, journey maps) | Ch3 | +| **Kai** | Frontend Engineer / ML Integration | Bridges design and code, maintains AI pipeline configs | Ch5 | -Four characters are enough to demonstrate solo work, pair collaboration, team coordination, and cross-functional handoff. Each has a trait that naturally triggers specific Git scenarios. +Each character's working style naturally triggers specific Git scenarios: +- **Nora's** research documents and briefs are text-heavy — perfect for diffs and merges +- **Sam's** speed creates stash/reset/amend situations — he commits too fast, forgets files, works on wrong branches +- **Priya's** illustrations and high-fidelity mockups are large binaries — triggers LFS, attributes, and binary merge challenges +- **Kai's** model configs and pipeline files are structured text — demonstrates cross-functional collaboration and submodules ### The Product Timeline -The storyline maps to a realistic product lifecycle. Each chapter picks up where the prior left off: - -| Chapter | Story Phase | What Happens | -|---------|-------------|--------------| -| **Ch1** | Discovery | Nora discovers version control after losing a week of work when her "final-v3-REAL" folder gets overwritten. She learns what Git is and installs it. | -| **Ch2** | Foundation | Nora creates the Meadow design system repo. Adds `design-tokens.json`, component documentation, and exported assets. Learns status, add, commit, diff, log. Her first `.gitignore` excludes `.sketch` temp files. | -| **Ch3** | Exploration | Sam joins. They use branches to explore a dark mode variant (`feature/dark-mode`) while Nora continues refining the light theme on `main`. Their first merge conflict: both edited `colors.json`. | -| **Ch4** | Infrastructure | The team picks GitHub to host the repo (not a bare server). Nora sets up branch protection so `main` requires a review before merge. | -| **Ch5** | Collaboration | Priya joins for an icon overhaul. Three designers coordinate: Nora on tokens, Sam on components, Priya on icons. They practice the integration-manager workflow. First design system release (`v1.0`). | -| **Ch6** | Open Source | Meadow's design system goes public on GitHub. An external contributor (Marcus) forks it and submits a PR adding a Tooltip component. Nora reviews, requests changes, merges. | -| **Ch7** | Maturity | The team handles real-world complexity: Sam stashes half-finished button states to fix a production color bug. Priya uses `git blame` to find when an icon color changed. Nora uses interactive rebase to clean up a messy token migration history. | -| **Ch8** | Customization | Nora configures `.gitattributes` for binary design files, sets up a commit message template (`[Component: X]`), and adds a pre-commit hook that validates token JSON syntax. | -| **Ch9** | Migration | The team migrates legacy brand assets from an SVN archive into the Git repo. They handle large binary files and history cleanup. | -| **Ch10** | Mastery | Sam accidentally force-resets `main`, losing recent commits. Nora uses reflog to recover. The chapter demystifies Git internals through the lens of "your work is never truly lost." | -| **App A** | Tooling | The team evaluates VS Code vs. GitHub Desktop vs. CLI for their workflow. Decision tree based on comfort level. | -| **App B** | Integration | The team considers how design tools (Figma plugins, token pipelines) integrate with Git under the hood. | -| **App C** | Reference | Quick-reference card organized by Meadow workflow phases, not command taxonomy. | +Each chapter picks up where the prior left off, following SketchSpark from idea to shipped product: + +| Chapter | Product Phase | What Happens | +|---------|---------------|--------------| +| **Ch1** | Research & Discovery | Nora loses a week of user research notes when her "interview-notes-FINAL-v3" folder gets overwritten by a sync conflict. She discovers Git. Installs it. Learns what version control means through the lens of protecting research artifacts. | +| **Ch2** | Concept Design | Nora creates the SketchSpark repo. Adds the product brief (`product-brief.md`), early wireframes, competitive analysis, and persona documents. Learns status, add, commit, diff, log. Creates `.gitignore` for design tool temp files. First tag: `v0.1-concept`. | +| **Ch3** | Parallel Exploration | Sam joins to explore UI directions. The core product idea — 5 options from 1 sketch — plays out in their workflow: Sam creates 3 branches (`option/card-layout`, `option/list-layout`, `option/canvas-freeform`) to explore different approaches to the results screen. Nora continues refining the input sketch flow on `main`. Their first merge conflict: both edited `user-flows.md`. | +| **Ch4** | Team Infrastructure | The team moves from local-only to GitHub. Nora sets up the org, branch protection (no direct pushes to `main`), and team roles. They evaluate hosting options — GitHub wins over self-hosted for a startup-stage product. | +| **Ch5** | Design & Build Sprint | Priya joins for illustration and high-fidelity mockups. Kai joins to build the AI generation pipeline. Four people coordinating: Nora on UX flows, Sam on UI screens, Priya on onboarding illustrations, Kai on model configs. Integration-manager workflow. First milestone release: `v0.5-alpha` — the sketch-to-options pipeline works end to end. | +| **Ch6** | Public Beta & Community | SketchSpark launches a public beta on GitHub. External contributor (Marcus) forks the repo and submits a PR improving the prompt template for better mobile layouts. Nora reviews with annotated screenshots, requests changes, merges. The team writes CONTRIBUTING.md with guidelines for prompt templates, asset specs, and accessibility requirements. | +| **Ch7** | Production Hardening | Real-world complexity hits: Sam stashes half-finished screen designs to hotfix a broken onboarding flow. Priya uses `git blame` to find when an illustration's color palette drifted from the brand guide. Nora uses interactive rebase to clean up a messy sprint of "fix layout" / "fix layout again" / "actually fix layout" commits. Kai's AI pipeline repo becomes a submodule. | +| **Ch8** | Process & Automation | Nora configures `.gitattributes` for Priya's binary illustration files, creates a commit message template (`[Phase: Component] Description`), and adds a pre-commit hook that validates `model-params.yaml` syntax and checks that prompt templates don't exceed token limits. | +| **Ch9** | Legacy Migration | The company acquires a competitor whose design assets live in SVN. The team migrates 3 years of mockups, illustrations, and research documents into the SketchSpark repo. They handle large binaries, history cleanup, and Git LFS setup. | +| **Ch10** | Scale & Recovery | Sam accidentally force-resets `main`, losing three days of work before a launch deadline. Nora uses reflog to recover every commit. The chapter demystifies Git internals through the lens of "your work is never truly lost" — critical when months of design research, illustrations, and AI configs are at stake. | +| **App A** | Tooling Choices | Each team member uses different tools: Nora uses CLI, Sam prefers VS Code's Git panel for visual diffs of screen designs, Priya uses GitHub Desktop for large file management, Kai uses JetBrains. Decision tree based on role and comfort. | +| **App B** | Tool Integration | Kai explains how SketchSpark's own AI pipeline uses libgit2 under the hood to version-control generated options. Priya explores how Figma plugins use Dulwich (Python) to auto-export assets to Git. | +| **App C** | Reference | Quick-reference card organized by SketchSpark workflow phases: "Starting research" (init, clone), "Daily design work" (branch, add, commit, status), "Reviewing options" (diff, log, show), "Shipping a release" (tag, merge, push). | --- ## Artifact Continuity Map -These artifacts appear and evolve across chapters, giving readers anchoring reference points: +These artifacts appear and evolve across chapters, giving readers anchoring reference points. ### Core Files (appear 5+ chapters) | Artifact | First Appears | Evolves Through | Purpose | |----------|---------------|-----------------|---------| -| `design-tokens.json` | Ch2 (created) | Ch3 (dark mode added), Ch5 (v1.0 release), Ch7 (migration cleanup), Ch8 (validation hook) | The primary "code-like" design file — mergeable, diffable, central to the system | -| `colors.json` (subset of tokens) | Ch2 (initial palette) | Ch3 (merge conflict), Ch5 (coordinated update), Ch7 (blame for change), Ch8 (diff config) | Most relatable file for designers — color values changing | -| `components/button/` | Ch2 (first component) | Ch3 (dark mode variant), Ch5 (Sam's work), Ch7 (stash scenario), Ch8 (commit template) | The universal UI component — every designer understands buttons | -| `.gitignore` | Ch2 (created) | Ch8 (expanded for design tools) | Practical file designers need immediately | -| `README.md` | Ch2 (basic) | Ch6 (expanded for public repo) | Entry point for contributors | +| `product-brief.md` | Ch2 (created) | Ch3 (updated with chosen direction), Ch5 (alpha scope), Ch6 (public beta scope), Ch8 (commit template references it) | The "source of truth" text file — mergeable, diffable, anchors every design decision | +| `user-flows.md` | Ch2 (initial sketch flow) | Ch3 (merge conflict — Nora and Sam both edited), Ch5 (expanded for full pipeline), Ch7 (blame to find when a flow changed) | Primary UX artifact — where merge conflicts feel real and relatable | +| `screens/results/` | Ch3 (3 layout options as branches) | Ch5 (Sam's production screens), Ch7 (stash scenario mid-redesign), Ch8 (commit template) | The heart of the product — where parallel options become parallel branches | +| `model-params.yaml` | Ch5 (Kai creates) | Ch7 (submodule), Ch8 (pre-commit validation hook), Ch10 (recovered via reflog) | Structured text config — demonstrates Git-friendly AI/ML files alongside binary design files | +| `.gitignore` | Ch2 (created) | Ch5 (expanded for build artifacts), Ch8 (expanded for design tools and model caches) | Practical file designers need immediately | ### Secondary Files (appear 2-3 chapters) | Artifact | Chapters | Purpose | |----------|----------|---------| -| `icons/` directory | Ch5 (Priya creates), Ch7 (blame for color change), Ch10 (packfile performance) | Binary file handling, large asset management | -| `CONTRIBUTING.md` | Ch6 (created for open source), Ch8 (referenced in hooks) | Governance, standards | -| `CHANGELOG.md` | Ch5 (v1.0 release), Ch7 (rewriting history) | Release documentation | -| `typography.json` | Ch7 (selective staging), Ch8 (attributes config) | Second token file for staging/splitting scenarios | +| `research/personas/` | Ch2 (Nora creates), Ch5 (referenced in sprint planning), Ch9 (migrated from legacy) | Text-heavy research artifacts — ideal for diffs | +| `research/competitive-analysis.md` | Ch2 (created), Ch6 (updated when going public) | Shows how research docs evolve alongside product | +| `illustrations/onboarding/` | Ch5 (Priya creates), Ch7 (blame for color drift), Ch10 (packfile performance with large PNGs) | Binary file handling — large asset management | +| `prompts/sketch-to-ui.txt` | Ch5 (Kai creates), Ch6 (Marcus improves via PR), Ch8 (token-limit validation hook) | AI prompt templates — text files that external contributors can improve | +| `CONTRIBUTING.md` | Ch6 (created for public beta), Ch8 (referenced in hooks) | Governance and standards for open contribution | +| `CHANGELOG.md` | Ch5 (v0.5-alpha), Ch7 (rewriting history to clean up entries) | Release documentation | +| `design-tokens.json` | Ch5 (Sam creates for handoff to Kai), Ch7 (selective staging — color vs. typography), Ch8 (attributes config) | Bridge between design and code — the handoff file | + +### Lifecycle Phase Artifacts + +| Product Phase | Key Artifacts | File Types | Git Behavior | +|---------------|---------------|------------|--------------| +| Research | `product-brief.md`, `personas/*.md`, `competitive-analysis.md`, `interview-notes/*.md` | Markdown, text | Fully mergeable, excellent diffs | +| Concept Design | `user-flows.md`, `information-architecture.md`, `sketches/*.png` | Mixed | Text merges cleanly; sketch PNGs are binary | +| UI Design | `screens/**/*.fig`, `screens/**/*.png`, `wireframes/*.md` | Mostly binary | Binary conflicts require manual resolution | +| Visual Design | `illustrations/**/*.png`, `icons/**/*.svg`, `design-tokens.json` | Binary + JSON | SVGs diff as text; PNGs don't; tokens merge | +| AI Pipeline | `model-params.yaml`, `prompts/*.txt`, `training-data-manifest.json` | Structured text | Fully mergeable, hookable, validatable | +| Production | `assets/exported/**`, `docs/`, `CHANGELOG.md` | Mixed | Export-ignore for source files; archive for releases | --- ## Scene-by-Scene Storyline Mapping to Existing Recommendations -### Chapter 1 — Discovery +### Chapter 1 — Research & Discovery | Revision Note Recommendation | Storyline Scene | |------------------------------|-----------------| -| Add concrete scenario after line 8's designer mention | Nora's "final-v3-REAL" folder disaster — she loses a week of button iterations | -| CVCS = Figma shared file analogy | Nora compares her Figma workflow (centralized) to Git (distributed) | -| Three states = draft/ready/approved | Nora maps modified/staged/committed to her existing review process | -| Binary file support flag | Nora asks: "Can I version my Sketch files?" — honest answer about binary limitations | +| Add concrete scenario after line 8's designer mention | Nora's "interview-notes-FINAL-v3" folder disaster — a cloud sync conflict overwrites a week of user research for the SketchSpark concept | +| CVCS = Figma shared file analogy | Nora compares her team's shared Google Drive (centralized, single point of failure) to Git (full local copy of all research history) | +| Three states = draft/ready/approved | Nora maps modified/staged/committed to her research workflow: draft notes → reviewed findings → published insight | +| Binary file support flag | Nora asks: "Can I version my sketch mockups and interview recordings?" — honest answer about binary limitations sets up a theme that runs through every chapter | -### Chapter 2 — Foundation +### Chapter 2 — Concept Design | Revision Note Recommendation | Storyline Scene | |------------------------------|-----------------| -| "Initializing a design system repository" | Nora runs `git init` in the `meadow-design-system` directory | -| Replace `.c` file examples | All examples use `design-tokens.json`, `components/button/button.md`, exported PNGs | -| `.gitignore` template for designers | Nora creates `.gitignore` excluding `.sketch~`, `*.figma_cache`, `node_modules/` | -| Commit message conventions | Nora writes: `Add initial color palette and button component` | -| Design token search in log | Nora uses `git log -S "primary-blue"` to find when she changed the brand color | -| Tags for releases | Nora tags the repo's first stable state: `git tag -a v0.1 -m "Initial token set and button component"` | +| "Initializing a design system repository" | Nora runs `git init` in the `sketchspark/` directory after completing the concept phase | +| Replace `.c` file examples | All examples use `product-brief.md`, `research/personas/early-adopter.md`, `wireframes/sketch-input-flow.png` | +| `.gitignore` template for designers | Nora creates `.gitignore` excluding `.sketch~`, `*.figma_cache`, `__MACOSX/`, `.DS_Store`, `node_modules/` | +| Commit message conventions | Nora writes: `Add product brief and initial user flow wireframes` | +| Design token search in log | Nora uses `git log -S "single sketch"` to find when the core product concept changed from "3 options" to "5 options" in the brief | +| Tags for releases | Nora tags the concept milestone: `git tag -a v0.1-concept -m "Research complete, concept approved, entering UI exploration"` | -### Chapter 3 — Exploration +### Chapter 3 — Parallel Exploration | Revision Note Recommendation | Storyline Scene | |------------------------------|-----------------| -| Branch as design variant | Sam creates `feature/dark-mode` to explore a dark palette without touching Nora's light theme | -| Hotfix interruption scenario | Sam is working on dark mode; urgent accessibility bug on `main` button contrast — creates `hotfix/button-contrast` | -| Merge conflict in token file | Both Nora and Sam edited `colors.json` — Nora updated `primary-blue`, Sam added `dark-bg`. They resolve together. | -| Branch naming conventions | Team establishes: `feature/`, `fix/`, `hotfix/`, `experiment/` | -| Rebasing as "replay on cleaner foundation" | Sam rebases dark mode onto main to pick up Nora's latest token structure | +| Branch as design variant | Sam creates `option/card-layout`, `option/list-layout`, `option/canvas-freeform` — three parallel UI directions for the results screen, mirroring SketchSpark's own "5 options from 1 sketch" philosophy | +| Hotfix interruption scenario | Sam is deep in `option/card-layout`; Nora discovers a critical user flow gap in the sketch input screen on `main` — Sam creates `fix/sketch-input-upload-error` | +| Merge conflict in token file | Both Nora and Sam edited `user-flows.md` — Nora refined the upload step, Sam added a "compare options" step. They resolve together, learning that text files merge but require coordination. | +| Branch naming conventions | Team establishes: `option/` (design explorations), `feature/` (approved work), `fix/` (corrections), `research/` (investigation branches) | +| Rebasing as "replay on cleaner foundation" | Sam rebases `option/card-layout` onto main to pick up Nora's updated user flow before the team reviews all three options side by side | -### Chapter 4 — Infrastructure +### Chapter 4 — Team Infrastructure | Revision Note Recommendation | Storyline Scene | |------------------------------|-----------------| -| Lead with hosted options | Nora evaluates GitHub vs. GitLab — picks GitHub for simplicity | -| SSH key setup with context | Sam struggles with SSH keys — Nora walks him through it, comparing `.pub` file to a "trusted device" | -| Branch protection | Nora enables `main` branch protection: PRs required, one approval needed | -| Role mapping | Nora = admin, Sam = write, stakeholders = read-only | +| Lead with hosted options | Nora evaluates GitHub vs. GitLab for the growing team — picks GitHub for its PR review workflow and project boards | +| SSH key setup with context | Sam struggles with SSH keys — Nora walks him through it: "The `.pub` file is like a badge that proves who you are. The private file is your ID — never share it." | +| Branch protection | Nora enables `main` branch protection: PRs required, one design review approval needed before merge. No direct commits to `main`. | +| Role mapping | Nora = admin (merges to main, manages releases), Sam = write (creates branches, opens PRs), stakeholders = read-only (view progress, leave comments) | -### Chapter 5 — Collaboration +### Chapter 5 — Design & Build Sprint | Revision Note Recommendation | Storyline Scene | |------------------------------|-----------------| -| Three-person coordination | Nora (tokens), Sam (components), Priya (icons) work in parallel on feature branches | -| Replace `lib/simplegit.rb` files | All file references: `design-tokens/colors.json`, `components/Button/`, `icons/navigation/` | -| Integration-manager workflow | Nora acts as integrator — reviews and merges Sam's and Priya's branches | -| Design system release cycle | Team releases Meadow v1.0: tag, archive, changelog | -| Email workflow → skip notice | "Meadow uses GitHub PRs, not email patches" | +| Three-person coordination | Nora (UX flows and research updates), Sam (production UI screens), Priya (onboarding illustrations), Kai (AI pipeline configs) — four parallel workstreams | +| Replace `lib/simplegit.rb` files | All file references: `screens/results/card-layout.fig`, `illustrations/onboarding/step-1.png`, `model-params.yaml`, `prompts/sketch-to-ui.txt` | +| Integration-manager workflow | Nora acts as integrator — reviews Sam's screen PRs, Priya's illustration PRs, and Kai's pipeline PRs before merging to `main` | +| Design system release cycle | Team releases SketchSpark `v0.5-alpha`: the sketch-to-options pipeline works end to end. Tag, archive, changelog. Sam creates `design-tokens.json` for handoff to Kai's frontend. | +| Email workflow → skip notice | "The SketchSpark team uses GitHub PRs for all collaboration. Email-based patches are a legacy workflow — skip unless contributing to projects that require them." | -### Chapter 6 — Open Source +### Chapter 6 — Public Beta & Community | Revision Note Recommendation | Storyline Scene | |------------------------------|-----------------| -| Replace Arduino blink with design system PR | Marcus forks Meadow, creates `feature/tooltip-component`, adds SVG + token + docs, opens PR with screenshots | -| Expand image embedding for reviews | Marcus includes light/dark mode screenshots in his PR; Nora annotates with feedback | -| CONTRIBUTING.md for design projects | Nora writes guidelines: icon grid (24x24), token naming (`category-property-variant`), accessibility requirements | -| GitHub Pages for documentation | Team deploys component documentation to `meadow-design-system.github.io` | -| Async collaboration norms | Marcus is in a different timezone — PR review takes 24 hours; Nora leaves detailed written feedback | +| Replace Arduino blink with design system PR | Marcus forks SketchSpark, creates `feature/mobile-prompt-template`, improves `prompts/sketch-to-ui.txt` for better mobile layout generation, opens PR with before/after screenshots of generated options | +| Expand image embedding for reviews | Marcus includes side-by-side screenshots: "Current mobile output" vs. "Improved mobile output" with 5 generated options each. Nora annotates with feedback directly in the PR. | +| CONTRIBUTING.md for design projects | Nora writes guidelines: prompt template format, illustration specs (2x resolution, brand palette), screen mockup naming conventions, accessibility requirements for generated UI | +| GitHub Pages for documentation | Team deploys SketchSpark user docs and API reference to `sketchspark.github.io` | +| Async collaboration norms | Marcus is in a different timezone — PR review takes 24 hours. Nora leaves detailed written feedback with annotated screenshots rather than expecting a synchronous call. | -### Chapter 7 — Maturity +### Chapter 7 — Production Hardening | Revision Note Recommendation | Storyline Scene | |------------------------------|-----------------| -| Stashing scenario | Sam is halfway through new button states; production color bug reported; stashes work, fixes bug, pops stash | -| `git blame` for design files | Priya uses `git blame icons/navigation/home.svg` to find who changed the icon stroke width | -| Interactive staging | Nora's `design-tokens.json` has both color and typography updates; she stages only color changes for the current PR | -| Reset demystified | Sam accidentally commits to `main` instead of his feature branch — uses `git reset` to move the commit | -| Squashing messy history | Priya squashes "Add home icon" + "Fix home icon size" + "Adjust home icon padding" into clean "Add navigation home icon" | -| Submodules | The product app repo includes `meadow-design-system` as a submodule — Dev updates the pointer when v1.1 releases | +| Stashing scenario | Sam is redesigning the results comparison screen; urgent bug report — the onboarding flow crashes on tablet. Sam stashes his half-finished screens, switches to `fix/onboarding-tablet`, fixes the layout, merges, pops his stash, and continues. | +| `git blame` for design files | Priya uses `git blame illustrations/onboarding/step-2.png` to find who changed the illustration's color palette — it drifted from the brand guide three commits ago during a rushed sprint. | +| Interactive staging | Nora's `product-brief.md` has both a scope change (adding tablet support) and a research update (new user interview findings). She stages only the research update for the current PR, saving the scope change for a separate review. | +| Reset demystified | Sam accidentally commits directly to `main` instead of his feature branch — uses `git reset --soft HEAD~1` to move the commit back to staging, then creates the correct branch. | +| Squashing messy history | Sam squashes "Update results layout" + "Fix results layout spacing" + "Actually fix the spacing this time" + "Tweak padding" into clean "Redesign results comparison screen for card layout" | +| Submodules | Kai's AI pipeline repo (`sketchspark-ml`) becomes a submodule of the main product repo. When the model improves option generation quality, Kai updates the submodule pointer and the team pulls the new version. | -### Chapter 8 — Customization +### Chapter 8 — Process & Automation | Revision Note Recommendation | Storyline Scene | |------------------------------|-----------------| -| `.gitattributes` for binary files | Nora configures: `*.png binary`, `*.sketch binary`, `*.svg diff` | -| Commit message template | Team template: `[Component: Name] Description` — enforced by commit-msg hook | -| Pre-commit hook | Hook validates `design-tokens.json` is valid JSON before allowing commit | -| Image diffing | Nora sets up EXIF-based diffing so `git diff` shows metadata changes on PNG exports | -| Export-ignore | `.sketch` source files are versioned but excluded from release archives | +| `.gitattributes` for binary files | Nora configures: `*.png binary`, `*.fig binary`, `*.svg diff`, `*.md diff`, `*.yaml diff` — so Git knows which files can be meaningfully diffed | +| Commit message template | Team template enforced by hook: `[Phase: Component] Description` — e.g., `[Design: Results Screen] Add tablet breakpoint layout` or `[Research: Persona] Update early-adopter goals after round 2 interviews` | +| Pre-commit hook | Hook validates that `model-params.yaml` is valid YAML, checks that prompt templates in `prompts/` don't exceed 4096 tokens, and warns if PNG files exceed 5MB | +| Image diffing | Nora sets up EXIF-based diffing so `git diff` shows metadata changes on exported screen mockups — dimensions, color profile, export date | +| Export-ignore | `.fig` source files and `research/raw-interviews/` are versioned in Git but excluded from release archives via `.gitattributes export-ignore` | -### Chapter 9 — Migration +### Chapter 9 — Legacy Migration | Revision Note Recommendation | Storyline Scene | |------------------------------|-----------------| -| SVN design archive migration | The company's legacy brand assets (logos, illustrations) live in SVN. Nora migrates them into the Meadow repo. | -| Large binary file handling | Migration surfaces 200MB of PSDs — team decides to use Git LFS for files >10MB | -| Pre-import planning | Nora checks total size, identifies files for LFS, plans branch structure | +| SVN design archive migration | SketchSpark acquires a competitor ("QuickMock") whose 3 years of mockups, user research, and design assets live in SVN. Nora leads the migration into the SketchSpark repo. | +| Large binary file handling | Migration surfaces 400MB of PSD source files and high-res mockups — team configures Git LFS for files >10MB | +| Pre-import planning | Nora audits total size, identifies files for LFS, maps QuickMock's flat folder structure to SketchSpark's organized directory hierarchy, and plans which history to preserve vs. squash | -### Chapter 10 — Mastery +### Chapter 10 — Scale & Recovery | Revision Note Recommendation | Storyline Scene | |------------------------------|-----------------| -| Reflog for data recovery | Sam runs `git reset --hard` on `main` by accident, losing three commits. Nora uses reflog to recover. | -| Objects as "fingerprints" | Nora explains to Sam: "Every version of every file gets a unique ID. Even if you delete a branch, the data is still there." | -| Packfiles and performance | Priya notices `git push` is slow — learns Git packs similar icon files together | -| References as labels | "Branches are just sticky notes pointing to commits — moving them doesn't destroy anything" | +| Reflog for data recovery | Two days before the v1.0 launch, Sam runs `git reset --hard` on `main` by accident, losing three days of final polish commits. Nora uses `git reflog` to find the lost HEAD, creates a recovery branch, and restores everything. | +| Objects as "fingerprints" | Nora explains to Sam: "Every version of every file — every screen mockup, every prompt template, every research note — gets a unique ID. Even if you delete a branch, the data is still in Git's object store." | +| Packfiles and performance | Priya notices `git push` takes 90 seconds — learns that Git packs similar illustration files together using delta compression, but her 50MB PSD additions bypass efficient packing. The team moves large files to LFS. | +| References as labels | "Branches are just labels pointing to commits — like sticky notes on a timeline. Moving them doesn't destroy anything. That's why Sam's 'lost' work was still there." | -### Appendix A — Tooling +### Appendix A — Tooling Choices | Revision Note Recommendation | Storyline Scene | |------------------------------|-----------------| -| Decision tree | Nora uses CLI, Sam prefers VS Code's Git panel, Priya uses GitHub Desktop for visual diffs of icons | -| VS Code for token workflows | Sam edits `design-tokens.json` with inline Git diff highlighting | +| Decision tree | Nora uses CLI (fastest for research doc workflows), Sam prefers VS Code's Git panel (inline diffs of screen designs and tokens), Priya uses GitHub Desktop (visual staging of large illustration files), Kai uses JetBrains (integrated with Python ML pipeline) | +| VS Code for token workflows | Sam edits `design-tokens.json` and `user-flows.md` with inline Git gutter indicators showing what changed since last commit | -### Appendix B — Integration +### Appendix B — Tool Integration | Revision Note Recommendation | Storyline Scene | |------------------------------|-----------------| -| Design tool internals | Priya wonders how Figma plugins could auto-commit exported assets — learns about Dulwich (Python Git library) | -| UX patterns for Git integration | Nora sketches a "version control panel" for a design tool prototype | +| Design tool internals | Kai explains how SketchSpark's own generation pipeline uses libgit2 to version-control each of the 5 generated options as lightweight branches — the product's architecture mirrors Git's branching model | +| UX patterns for Git integration | Nora designs SketchSpark's "version history" panel — translating Git concepts (commits, branches, diffs) into a visual interface that non-technical designers can use | +| Dulwich / Python integration | Priya's export script uses Dulwich to auto-commit illustration assets to Git whenever she exports from her design tool — removing manual `git add` from her workflow | ### Appendix C — Reference | Revision Note Recommendation | Storyline Scene | |------------------------------|-----------------| -| Workflow-based organization | Commands grouped by Meadow workflow: "Starting your day" (pull, status), "Making changes" (add, commit), "Sharing work" (push, PR), "Releasing" (tag, archive) | +| Workflow-based organization | Commands grouped by SketchSpark workflow: "Starting a research phase" (init, clone, branch), "Daily design work" (status, add, commit, diff), "Reviewing options" (log, show, diff between branches), "Collaborating" (push, pull, fetch, merge), "Shipping a release" (tag, archive, merge to main) | --- ## Key Benefits of the Unified Storyline -1. **Progressive complexity**: readers learn Git operations in the order they'd encounter them on a real project -2. **Emotional investment**: readers care about Nora's team and their product — mistakes feel relatable, not abstract -3. **Artifact familiarity**: by Chapter 5, `design-tokens.json` and `colors.json` are old friends — readers focus on the Git concept, not parsing new file names -4. **Natural motivation**: each chapter answers "why do I need this?" through the story's progression (branching because Sam joined, GitHub because they went public, hooks because they need quality gates) -5. **Character-driven scenarios**: Sam's sloppiness triggers stash/reset/recovery lessons; Priya's binary files trigger LFS/attributes lessons; Nora's leadership triggers governance/hooks/release lessons +1. **Progressive complexity**: readers learn Git operations in the order they'd encounter them building a real product — research notes before merge conflicts, branching before rebasing +2. **Product mirrors Git**: SketchSpark generates 5 parallel options from 1 sketch; Git creates parallel branches from 1 commit. The product's core concept reinforces the most important Git mental model. +3. **Artifact familiarity**: by Chapter 5, `product-brief.md`, `user-flows.md`, and `screens/results/` are familiar landmarks — readers focus on the Git concept, not parsing new file names +4. **Full lifecycle coverage**: research, concept, design, build, test, launch, scale — every phase produces different artifacts (text vs. binary, solo vs. collaborative) that naturally teach different Git workflows +5. **Natural motivation**: each chapter answers "why do I need this?" through the product's progression — branching because the team explores 3 UI options, GitHub because they launched a beta, hooks because they need quality gates before shipping +6. **Character-driven scenarios**: Sam's speed creates stash/reset/recovery lessons; Priya's binary files trigger LFS/attributes lessons; Nora's leadership triggers governance/review/release lessons; Kai's ML pipeline triggers submodule/cross-functional lessons --- @@ -214,10 +238,11 @@ These artifacts appear and evolve across chapters, giving readers anchoring refe | Risk | Mitigation | |------|------------| | Storyline feels forced in reference chapters (App C) | Use storyline as organizational principle, not narrative prose | -| Readers skip chapters and miss context | Each chapter opens with a 2-line "Previously in Meadow" recap | -| Product choice alienates some readers | "Wellness app" is generic enough; swap product name without breaking any examples | -| Characters feel contrived | Keep characterization minimal — traits emerge from actions, not descriptions | -| Chapters 9-10 have low design relevance | Migration and internals are naturally "advanced" — storyline justifies why the team encounters them | +| Readers skip chapters and miss context | Each chapter opens with a 2-line "Previously on SketchSpark" recap | +| AI product concept feels niche | The design workflow (research → concept → UI → ship) is universal; the AI generation is flavor, not prerequisite | +| Characters feel contrived | Keep characterization minimal — traits emerge from actions (Sam's messy commits, Priya's large files), not backstory | +| Chapters 9-10 have lower design relevance | Migration and internals are naturally "advanced" — the storyline (acquiring a competitor, recovering before launch) justifies why the team encounters them | +| Binary file challenges recur without resolution | Thread Git LFS as a progressive solution: mentioned Ch1, explained Ch5, configured Ch8, essential in Ch9 | --- @@ -225,9 +250,9 @@ These artifacts appear and evolve across chapters, giving readers anchoring refe | Priority | Action | Impact | |----------|--------|--------| -| 1 | Lock character names and roles across all chapters | Consistency foundation | -| 2 | Define the `meadow-design-system` repo file structure used in examples | Artifact continuity | -| 3 | Rewrite Ch1-3 examples with storyline (highest reader volume) | First impression | -| 4 | Rewrite Ch5-6 collaboration examples (most design-relevant) | Core value proposition | -| 5 | Update Ch7-8 tool examples with established artifacts | Builds on familiarity | -| 6 | Adapt Ch4, Ch9-10, appendices last (lowest impact) | Completeness | +| 1 | Lock character names, roles, and traits across all chapters | Consistency foundation | +| 2 | Define the `sketchspark/` repo file structure used in examples | Artifact continuity | +| 3 | Rewrite Ch1-3 examples with storyline (highest reader volume, establishes the product) | First impression — readers decide here whether to continue | +| 4 | Rewrite Ch5-6 collaboration examples (most design-relevant, introduces full team) | Core value proposition — collaboration is why designers need Git | +| 5 | Update Ch7-8 tool examples with established artifacts and characters | Builds on familiarity — advanced tools feel less intimidating | +| 6 | Adapt Ch4, Ch9-10, appendices last (infrastructure and advanced topics) | Completeness — important but lower reader volume | From d0ee6b6e9af61974f80874cbbc00e0e10b591117 Mon Sep 17 00:00:00 2001 From: Claude <noreply@anthropic.com> Date: Tue, 31 Mar 2026 15:55:12 +0000 Subject: [PATCH 12/17] Add complete SketchSpark storyline for UX designer edition Self-contained narrative following an AI-powered rapid prototyping product from research through launch. Covers all 10 chapters and 3 appendices with consistent characters, artifacts, and themes. https://claude.ai/code/session_011MhF8iWLG3rS5jturtiTZ5 --- 00-notes/storyline.md | 682 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 682 insertions(+) create mode 100644 00-notes/storyline.md diff --git a/00-notes/storyline.md b/00-notes/storyline.md new file mode 100644 index 000000000..23215cf51 --- /dev/null +++ b/00-notes/storyline.md @@ -0,0 +1,682 @@ +# The SketchSpark Storyline + +## The Product + +**SketchSpark** is an AI-powered rapid prototyping application. A designer uploads or draws a rough sketch — a napkin wireframe, a whiteboard photo, a tablet drawing — and SketchSpark generates up to five polished UI options in parallel. The designer reviews, compares, selects a direction, refines it, and iterates toward a shippable product. + +The product serves a gap in the design-to-development pipeline: the jump from rough idea to testable prototype is slow. SketchSpark collapses it from days to minutes. + +--- + +## The Team + +**Nora** — UX Lead and Product Owner. She came from agency work where she managed design research across dozens of client projects, all versioned as "final_v3_REAL_USE-THIS.pdf" on shared drives. She's methodical, writes thorough briefs, and sets process standards. She's the one who brings Git to the team after a catastrophic file loss. She uses the CLI. + +**Sam** — UI and Visual Designer. He's fast. He generates screen layouts the way a jazz musician improvises — quickly, instinctively, and sometimes messily. He commits too often with vague messages, works on the wrong branch, and forgets to pull before pushing. Every Git mistake a designer can make, Sam makes first. He uses VS Code. + +**Priya** — Concept Designer and Illustrator. She creates the product's visual identity: onboarding illustrations, marketing assets, icon sets, and high-fidelity mockups. Her files are large — 30MB PSDs, layered Sketch files, high-resolution PNGs. She's the team member who stress-tests Git's handling of binary files. She uses GitHub Desktop. + +**Kai** — Frontend Engineer and ML Integration Lead. He joins when the product moves from concept to build. He maintains the AI generation pipeline: model parameters, prompt templates, training data manifests. His files are structured text (YAML, JSON, plain text) that merge cleanly — the opposite of Priya's binaries. He bridges design and engineering. He uses JetBrains. + +**Marcus** — External Contributor. He appears in Chapter 6 when SketchSpark goes public beta. He's a designer in another timezone who forks the repo, improves a prompt template for mobile layouts, and submits a pull request. He represents the open-source contribution experience. + +--- + +## The Repository + +``` +sketchspark/ +├── product-brief.md # The source of truth — what are we building and why +├── research/ +│ ├── personas/ +│ │ ├── early-adopter.md # Primary persona: freelance UI designer +│ │ └── team-lead.md # Secondary persona: design team manager +│ ├── competitive-analysis.md # Landscape of existing prototyping tools +│ ├── interview-notes/ +│ │ ├── round-1-findings.md # Initial discovery interviews +│ │ └── round-2-findings.md # Post-alpha validation interviews +│ └── journey-maps/ +│ └── sketch-to-prototype.png # Current-state journey map (binary) +├── concept/ +│ ├── information-architecture.md # App structure and navigation model +│ ├── user-flows.md # Step-by-step task flows +│ └── wireframes/ +│ ├── sketch-input.png # Upload/draw screen (binary) +│ └── results-comparison.png # Side-by-side options screen (binary) +├── screens/ +│ ├── onboarding/ +│ │ ├── welcome.fig # Figma source (binary, large) +│ │ └── welcome.png # Exported preview +│ ├── sketch-input/ +│ │ ├── upload-flow.fig +│ │ └── upload-flow.png +│ └── results/ +│ ├── card-layout.fig +│ ├── card-layout.png +│ ├── list-layout.fig +│ ├── list-layout.png +│ ├── canvas-freeform.fig +│ └── canvas-freeform.png +├── illustrations/ +│ ├── onboarding/ +│ │ ├── step-1-upload.png # Large illustrated graphics (binary) +│ │ ├── step-2-generate.png +│ │ └── step-3-refine.png +│ └── marketing/ +│ └── hero-image.psd # Very large source file (binary, LFS) +├── icons/ +│ ├── navigation/ +│ │ ├── home.svg # SVG diffs as text +│ │ ├── settings.svg +│ │ └── history.svg +│ └── actions/ +│ ├── upload.svg +│ ├── generate.svg +│ └── compare.svg +├── design-tokens.json # Colors, typography, spacing — handoff to engineering +├── pipeline/ # AI generation pipeline (Kai's domain) +│ ├── model-params.yaml # Model configuration +│ ├── prompts/ +│ │ ├── sketch-to-ui.txt # Core generation prompt +│ │ ├── mobile-layout.txt # Mobile-specific prompt +│ │ └── accessibility-check.txt # Post-generation a11y validation prompt +│ └── training-data-manifest.json # References to training datasets +├── docs/ +│ ├── setup-guide.md +│ └── api-reference.md +├── CONTRIBUTING.md +├── CHANGELOG.md +├── .gitignore +└── .gitattributes +``` + +This structure ensures every chapter has realistic files to reference. Research artifacts are text-heavy (merge-friendly). Screen mockups and illustrations are binary (merge-hostile). Pipeline configs are structured text (hookable, validatable). The variety is intentional — it teaches Git's strengths and limitations simultaneously. + +--- + +## Chapter 1 — Research & Discovery + +Nora is a UX lead at a small startup. She's been running user research for a new product idea — an AI tool that turns rough sketches into polished prototypes. She has three weeks of interview notes, a competitive analysis, two persona documents, and a journey map. They live in a folder on her laptop called `sketchspark-research/`. + +One morning, her cloud sync overwrites the folder with a week-old version. Her latest interview findings, the revised competitive analysis, and the updated journey map are gone. She spends two days reconstructing what she can from memory and Slack messages. She never fully recovers the competitive analysis. + +A developer friend tells her: "This is exactly what Git solves." + +Nora installs Git. She learns what version control is — not through the history of Linux and BitKeeper, but through the pain of losing irreplaceable research. She learns that **centralized version control** is like her shared Google Drive: everyone connects to one place, and if it goes down or conflicts, work is lost. **Distributed version control** means every team member has the full history locally. If the cloud disappears tomorrow, her laptop still has everything. + +She learns the three states — modified, staged, committed — and maps them to her own workflow: +- **Modified**: she's updated the interview notes but hasn't marked them as ready +- **Staged**: she's selected which updates to bundle into a checkpoint +- **Committed**: the checkpoint is permanent — she can always come back to it + +She sets up her identity (`git config`) so her name appears on every checkpoint she creates. She asks: "Can I version my journey map PNGs and Sketch files?" The honest answer: Git handles them, but it can't show you what changed inside them the way it can with text. This limitation — binary vs. text — becomes a thread that runs through every chapter. + +--- + +## Chapter 2 — Concept Design + +Nora creates the SketchSpark repository. + +``` +cd sketchspark +git init +``` + +She adds the product brief, her persona documents, the competitive analysis, and the initial user flow. Each one is a markdown file — Git can track every word that changes. + +``` +git add product-brief.md research/personas/ research/competitive-analysis.md concept/user-flows.md +git commit -m "Add product brief, personas, competitive analysis, and initial user flows" +``` + +She learns the daily rhythm: check status, stage changes, write a commit message that explains *why* (not just *what*), review the log to see her project's history. She creates a `.gitignore` to exclude temp files her design tools generate: + +``` +.DS_Store +__MACOSX/ +*.sketch~ +*.figma_cache +Thumbs.db +``` + +She adds wireframe exports — PNGs of the sketch input screen and the results comparison screen. These are binary files. Git accepts them, but `git diff` shows nothing useful. She notes this and keeps going. + +She commits the wireframes separately from the text files — a habit she develops because text and binary changes serve different review purposes: + +``` +git add concept/wireframes/ +git commit -m "Add wireframes for sketch input and results comparison screens" +``` + +She explores the log. She uses `git log -S "5 options"` to find when she changed the product brief from "3 options" to "5 options" — tracing a design decision through history. + +She tags the milestone: + +``` +git tag -a v0.1-concept -m "Research complete, concept approved, entering UI exploration" +``` + +The concept phase is over. The product has a brief, personas, a competitive landscape, user flows, and wireframes — all versioned, all recoverable. + +--- + +## Chapter 3 — Parallel Exploration + +Sam joins the project. He's a UI designer who works fast. Nora brings him up to speed on the product brief and user flows, then asks him to explore layout directions for the results screen — the screen where users see their 5 generated options side by side. + +Sam's assignment mirrors the product itself: generate multiple options in parallel, then choose the best direction. + +He creates three branches: + +``` +git checkout -b option/card-layout +git checkout -b option/list-layout +git checkout -b option/canvas-freeform +``` + +Each branch contains a different approach to the same screen. On `option/card-layout`, the 5 options appear as cards in a grid. On `option/list-layout`, they stack vertically with detail panels. On `option/canvas-freeform`, they float on an infinite canvas the user can pan and zoom. + +While Sam explores, Nora continues refining the sketch input flow on `main`. She updates `concept/user-flows.md` to clarify the upload step. + +Sam, on `option/card-layout`, also edits `concept/user-flows.md` — he adds a "compare options" step that doesn't exist yet. Neither knows the other has touched the same file. + +Sam finishes the card layout and switches back to main: + +``` +git checkout main +git merge option/card-layout +``` + +**Conflict.** Both edited `concept/user-flows.md`. Git can't automatically reconcile Nora's upload clarification with Sam's new comparison step. They sit together, open the file, and see Git's conflict markers. They keep both changes — Nora's refined upload step *and* Sam's comparison step — in the right order. They commit the resolution. + +This is the team's first merge conflict. It's a text file, so the markers make sense. Nora notes: "If this had been a Figma file or a PSD, Git couldn't show us the conflict at all. We'd have to open both versions and manually compare." + +They establish branch naming conventions: +- `option/` — design explorations (may be discarded) +- `feature/` — approved work heading to production +- `fix/` — corrections to existing work +- `research/` — investigation branches (new interviews, usability tests) + +Mid-exploration, Nora discovers a critical flaw in the sketch input screen on `main` — the upload error state is missing. Sam is deep in `option/list-layout`. He creates a hotfix: + +``` +git stash +git checkout main +git checkout -b fix/sketch-input-upload-error +``` + +He designs the error state, commits, merges to main, then returns to his exploration: + +``` +git checkout option/list-layout +git stash pop +``` + +The team reviews all three options. They choose the card layout. Sam rebases the other two branches onto the latest main (which now includes the card layout merge) to see if any ideas from `list-layout` or `canvas-freeform` are worth carrying forward. They cherry-pick the "pinch-to-zoom on selected option" interaction from `canvas-freeform` into a new `feature/zoom-on-selection` branch. + +The exploration phase ends. One direction chosen, two archived, one idea salvaged. + +--- + +## Chapter 4 — Team Infrastructure + +The project has outgrown Nora's laptop. Sam needs access. They're about to bring on an illustrator. The repo needs a home. + +Nora evaluates options. Self-hosted Git servers are overkill for a three-person startup. GitHub offers pull request reviews, branch protection, project boards, and free private repos. GitLab has similar features but the team already has GitHub accounts. They go with GitHub. + +Nora creates the `sketchspark` organization and pushes the repo: + +``` +git remote add origin git@github.com:sketchspark/sketchspark.git +git push -u origin main +``` + +Sam needs SSH access. Nora walks him through key generation: "The `.pub` file is a badge — you give it to GitHub to prove who you are. The other file is your secret key. Never share it, never commit it." + +Nora configures branch protection on `main`: +- Pull requests required — no direct pushes +- At least one approval before merge +- Status checks must pass (they'll add these later) + +She sets up team roles: +- Nora: admin (manages settings, merges to main, handles releases) +- Sam: write (creates branches, opens PRs, pushes to feature branches) +- Stakeholders (the CEO, the lead engineer): read-only (view progress, leave comments on PRs) + +Sam opens his first pull request — the zoom-on-selection feature from the previous chapter. Nora reviews it on GitHub, leaves a comment asking for a loading state, Sam adds it, and Nora approves and merges. + +The team has infrastructure. Every change goes through review before reaching `main`. + +--- + +## Chapter 5 — Design & Build Sprint + +Two new people join. **Priya** is a concept designer and illustrator — she'll create SketchSpark's onboarding illustrations, the icon set, and high-fidelity marketing mockups. **Kai** is a frontend engineer who will build the AI generation pipeline, connecting the design work to the model that turns sketches into UI options. + +Four people. Four parallel workstreams: +- **Nora**: UX flows and research updates (text files) +- **Sam**: production UI screens for all core flows (Figma source + PNG exports) +- **Priya**: onboarding illustrations and icon set (large PNGs, SVGs, PSDs) +- **Kai**: AI pipeline configuration (YAML, prompt templates, JSON manifests) + +Each works on a feature branch: + +``` +nora: feature/ux-flows-v2 +sam: feature/production-screens +priya: feature/onboarding-illustrations +kai: feature/ai-pipeline-setup +``` + +Nora acts as integration manager. She reviews each PR before merging to `main`. The workflow: + +1. Designer creates branch, does work, pushes +2. Designer opens PR with description and screenshots +3. Nora reviews — for design work, this means checking screenshots, verifying flows, confirming token consistency +4. If approved, Nora merges to `main` + +Priya's first push takes three minutes. Her onboarding illustrations are 15-30MB each. The team discusses Git LFS but decides to revisit it later — for now, the repo is manageable. + +Sam creates `design-tokens.json` — the bridge between design and engineering. It contains colors, typography scales, spacing values, and border radii. Kai consumes these tokens in the frontend build. This file becomes one of the most frequently committed files in the repo, and the source of the most merge conflicts (everyone touches it). + +Kai sets up the `pipeline/` directory: `model-params.yaml` defines the AI model configuration, `prompts/sketch-to-ui.txt` is the core generation prompt, and `training-data-manifest.json` references the datasets. These are all text files — they diff cleanly, merge predictably, and can be validated with hooks. + +The sprint converges. The sketch-to-options pipeline works end to end for the first time: a user draws something, the model generates 5 UI options, and they appear in Sam's card layout. + +Nora tags the milestone: + +``` +git tag -a v0.5-alpha -m "Alpha: end-to-end sketch-to-options pipeline working" +``` + +She writes the first `CHANGELOG.md` entry and creates a release archive: + +``` +git archive main --prefix='sketchspark-v0.5-alpha/' --format=zip > sketchspark-v0.5-alpha.zip +``` + +The archive goes to the CEO for demo day. The alpha is alive. + +--- + +## Chapter 6 — Public Beta & Community + +The alpha demo goes well. The CEO wants a public beta. The repo goes from private to public on GitHub. + +Going public changes everything. Strangers will see the code, the prompts, the design files. Nora writes `CONTRIBUTING.md` — not for engineers, but for designers: + +- Prompt templates must follow the existing format (system context, then user instruction, then constraints) +- Illustrations must be 2x resolution, brand palette only, PNG export with transparent background +- Icons must sit on a 24x24 grid, 2px stroke, SVG format +- Screen mockups must include both light and dark mode +- All UI contributions must pass WCAG AA contrast requirements + +She expands `README.md` with screenshots of the product, a GIF showing the sketch-to-options flow, a component map, and links to the Figma source files. + +Then Marcus appears. He's a designer in Melbourne — 16 hours ahead of the team. He's been using the beta and thinks the mobile layout generation is weak. He forks the repo, creates `feature/mobile-prompt-template`, and edits `prompts/sketch-to-ui.txt` to add mobile-specific layout constraints. He also adds a new file: `prompts/mobile-layout.txt`. + +He opens a pull request. In the description, he includes before/after screenshots: five generated options from the same sketch, current vs. his improved prompt. The mobile options are noticeably better — less cramped, better touch target sizing. + +Nora reviews the PR the next morning. She's never met Marcus. She leaves feedback: +- The prompt improvement is strong, but the constraint format doesn't match the existing template +- The mobile-layout file needs a header comment explaining when the system uses it vs. the main prompt +- She suggests splitting the touch-target constraint into its own line for readability + +Marcus pushes updates. Nora approves and merges. The whole interaction happens asynchronously over 48 hours, entirely through GitHub comments and annotated screenshots. + +The team sets up GitHub Pages to host product documentation at `sketchspark.github.io` — setup guide, API reference, and contribution guidelines. + +Nora configures the GitHub organization: +- `@core-team`: Nora, Sam, Priya, Kai (write access to all repos) +- `@contributors`: Marcus and other external designers (fork-and-PR workflow) +- `@stakeholders`: CEO, investors (read-only, can comment on PRs) + +The product is no longer just theirs. + +--- + +## Chapter 7 — Production Hardening + +The beta has users. Bugs arrive. Complexity compounds. + +**Sam's stash.** Sam is midway through redesigning the results comparison screen — he's added a new "overlay diff" mode that lets users superimpose two generated options. Half the screens are done, half are placeholders. Then a bug report: the onboarding flow crashes on tablets. The layout breaks at 768px. + +Sam can't commit half-finished work to his branch (the placeholders would confuse reviewers). He stashes: + +``` +git stash push -m "WIP: overlay diff mode for results comparison" +``` + +He switches to `main`, creates `fix/onboarding-tablet-layout`, fixes the responsive breakpoint in the onboarding screens, commits, opens a PR, gets it reviewed, and merges. Then he returns: + +``` +git checkout feature/overlay-diff +git stash pop +``` + +His work-in-progress is exactly where he left it. + +**Priya's blame.** A stakeholder notices that the onboarding illustrations look "off" — the blue tones don't match the brand. Priya uses blame to trace the change: + +``` +git blame illustrations/onboarding/step-2-generate.png +``` + +The file is binary, so blame shows commit metadata but not visual content. She checks the log: + +``` +git log --oneline -- illustrations/onboarding/step-2-generate.png +``` + +Three commits ago, she exported from a file with the wrong color profile. She fixes the source, re-exports, and commits: `Fix color profile on onboarding illustrations (sRGB, not Display P3)`. + +**Nora's interactive staging.** Nora has been updating `product-brief.md` with two unrelated changes: a scope expansion (adding tablet support) and updated user interview findings from round 2. She wants to commit them separately — the scope change needs its own PR and approval, but the research update can merge immediately. + +``` +git add -p product-brief.md +``` + +She stages only the hunks related to interview findings, commits those, then stages and commits the scope expansion separately. Two clean commits instead of one muddled one. + +**Sam's accidental commit to main.** Sam forgets to create a branch. He commits a screen redesign directly to `main`. Branch protection catches it on push — he can't push to `main` without a PR. But the commit exists locally. He fixes it: + +``` +git reset --soft HEAD~1 +git checkout -b feature/screen-redesign +git commit -m "Redesign generation progress screen with loading animation" +``` + +The commit moves to the correct branch. `main` is clean. + +**Priya's messy history.** Priya's icon branch has five commits: + +``` +Add home icon +Fix home icon — wrong stroke width +Update home icon — adjust padding +Add settings icon +Fix settings icon — align to grid +``` + +Before opening her PR, she cleans up with interactive rebase: + +``` +git rebase -i HEAD~5 +``` + +She squashes the home icon commits into one ("Add home navigation icon") and the settings icon commits into one ("Add settings navigation icon"). The PR shows two clean additions instead of five noisy iterations. + +**Kai's submodule.** The AI pipeline has grown complex enough to be its own repository: `sketchspark-ml`. Kai adds it as a submodule of the main product repo: + +``` +git submodule add git@github.com:sketchspark/sketchspark-ml.git pipeline/ +``` + +When the model improves — better option variety, faster generation — Kai updates the submodule pointer in the main repo. The team pulls and gets the latest pipeline version without managing ML code directly. + +--- + +## Chapter 8 — Process & Automation + +The team has grown beyond informal coordination. They need guardrails. + +**Git attributes for binary files.** Nora creates `.gitattributes` to tell Git which files are binary and which can be meaningfully diffed: + +``` +# Binary — don't attempt to diff or merge +*.png binary +*.psd binary +*.fig binary +*.sketch binary + +# Text-based design files — diff normally +*.svg diff +*.md diff +*.json diff +*.yaml diff +*.txt diff + +# Large source files — version but exclude from archives +*.psd export-ignore +*.sketch export-ignore +research/raw-interviews/ export-ignore +``` + +This means `git diff` produces useful output for SVGs, tokens, prompts, and documentation — but doesn't try to diff PNGs or Figma files (which would just show binary garbage). + +**Commit message template.** Nora creates `.gitmessage`: + +``` +[Phase: Component] Short description + +# Phases: Research, Concept, Design, Pipeline, Docs, Fix, Release +# Examples: +# [Design: Results Screen] Add overlay diff comparison mode +# [Research: Persona] Update early-adopter goals after round 2 interviews +# [Pipeline: Prompts] Improve mobile layout generation constraints +# [Fix: Onboarding] Correct tablet breakpoint for step 2 illustration +``` + +She configures it: + +``` +git config commit.template .gitmessage +``` + +Every commit now starts from this template. The `[Phase: Component]` prefix makes `git log --oneline` scannable and `git log --grep="[Design:"` filters to design-only changes. + +**Pre-commit hook.** Nora adds a hook that runs before every commit: + +1. Validates `model-params.yaml` is syntactically correct YAML +2. Checks that prompt templates in `prompts/` don't exceed 4096 tokens (the model's context limit) +3. Warns (but doesn't block) if any PNG file exceeds 5MB + +The hook is a shell script — Nora found a template online and adapted it. She couldn't write it from scratch (she's not a programmer), but she can read it and modify the file size threshold. + +**Commit-msg hook.** A second hook validates that commit messages match the `[Phase: Component]` pattern. If Sam writes "fix stuff", the commit is rejected with a message explaining the expected format. + +**Image metadata diffing.** Nora configures Git to use `exiftool` for PNG diffs. Now `git diff` on an illustration shows metadata changes: dimensions, color profile, export date, DPI. It's not a visual diff, but it catches the color profile mistake that cost Priya time in Chapter 7. + +The team's process is now encoded in the repository itself. New contributors (like Marcus) inherit the rules automatically when they clone. + +--- + +## Chapter 9 — Legacy Migration + +SketchSpark acquires a smaller competitor, **QuickMock**. QuickMock has three years of design assets — mockups, illustrations, user research, and brand materials — stored in a Subversion (SVN) repository on a company server. + +Nora leads the migration. + +**Assessment.** She checks the SVN repo: 2,400 files, 1.2GB total. Most of the size comes from PSD source files (some over 100MB) and high-resolution marketing renders. The text files (research notes, documentation) are small and numerous. + +**Planning.** She decides: +- Import full history for text files (research, documentation, changelogs) — the evolution matters +- Import only the latest version of large binary files (PSDs, high-res PNGs) — old versions of 100MB PSDs aren't useful enough to justify the repo bloat +- Configure Git LFS for files over 10MB going forward +- Map QuickMock's flat folder structure to SketchSpark's organized hierarchy + +**Execution.** She uses `git svn clone` to pull the history: + +``` +git svn clone https://svn.quickmock.internal/trunk quickmock-import --authors-file=authors.txt +``` + +The authors file maps SVN usernames to Git identities so QuickMock's team gets proper attribution. + +Post-import cleanup: +- SVN branch names with `@` suffixes get cleaned up +- Large binaries get migrated to Git LFS: `git lfs migrate import --include="*.psd,*.ai" --above=10mb` +- QuickMock's flat `designs/` folder gets reorganized into SketchSpark's `screens/`, `illustrations/`, and `icons/` structure + +The migration takes a day. The combined repo is 800MB with LFS (down from 1.2GB if everything were inline). Three years of QuickMock's design evolution is now searchable alongside SketchSpark's history. + +Priya notes: "I wish we'd set up LFS from the start. My onboarding illustrations have been bloating the repo since Chapter 5." + +--- + +## Chapter 10 — Scale & Recovery + +It's two days before the v1.0 launch. The team is in final polish mode. Sam is updating screenshots in the documentation. Priya is exporting final marketing assets. Nora is writing release notes. Kai is tuning the model's generation speed. + +Then Sam makes a mistake. + +He means to reset his working directory to discard some local experiments. He types: + +``` +git reset --hard HEAD~3 +``` + +On `main`. He just rewound the main branch by three commits — Nora's release notes, Priya's final marketing illustrations, and Kai's generation speed improvement. All gone from `main`. + +Panic. Then Nora says: "Git doesn't delete anything. It just moves pointers." + +She opens the reflog: + +``` +git reflog +``` + +The reflog shows every position `HEAD` has been in. Three entries up, there's the commit before Sam's reset. She creates a recovery branch: + +``` +git branch recovery a1b2c3d +git checkout recovery +git log --oneline -5 +``` + +All three commits are there. She merges recovery into main: + +``` +git merge recovery +``` + +Everything is restored. The launch stays on schedule. + +This moment — the near-disaster and the recovery — becomes the frame for understanding Git internals: + +**Objects.** Every file version, every directory snapshot, every commit is stored as an object with a unique hash. Nora explains: "When you committed those release notes, Git created an object. When Sam reset `main`, Git didn't delete the object — it just moved the `main` label to point at an older one. The release notes object was still there, just unreachable through normal commands." + +**References.** Branches are labels. Tags are labels. HEAD is a label. Moving them — even destructively — doesn't destroy the underlying objects. Sam's `reset --hard` moved the `main` label backward. Nora's `branch recovery` created a new label pointing at the still-existing commit. + +**Reflog.** Git keeps a log of every label movement for at least 30 days. Even if Sam had deleted the branch, the reflog would still know where it pointed. The reflog is the safety net that makes Git's model robust against human error. + +**Packfiles.** Priya asks why `git clone` takes 45 seconds for a repo with thousands of files. Nora explains: Git packs similar objects together using delta compression. When Priya commits a slightly modified illustration, Git doesn't store a second full copy — it stores the difference. But very large binary files (her PSDs) resist delta compression, which is why LFS exists. + +The internals chapter isn't about cryptographic hash functions or the Git object database's implementation. It's about understanding *why your work is never truly lost* — and why that matters when months of research, design, and AI configuration are at stake. + +--- + +## Appendix A — Tooling Choices + +The team never agreed on one tool. That turned out fine. + +**Nora** uses the command line. Her work is text-heavy — product briefs, research notes, user flows. She types `git status`, `git diff`, `git log --oneline --graph` dozens of times a day. The CLI is fastest for her. + +**Sam** uses VS Code. He edits `design-tokens.json` and `user-flows.md` with Git's inline gutter indicators showing what changed since the last commit. The built-in source control panel lets him stage individual hunks without learning `git add -p` syntax. He reviews PRs with the GitHub Pull Requests extension. + +**Priya** uses GitHub Desktop. She stages files by checking boxes. She sees a visual list of changed files — critical when her commits include a dozen illustration exports. Drag-and-drop staging and clear binary file indicators ("This file has changed but can't be displayed") match how she thinks about her work. + +**Kai** uses JetBrains (WebStorm). The integrated terminal, diff viewer, and Git log sit alongside his Python and JavaScript code. He resolves merge conflicts in the three-pane merge tool without leaving his IDE. + +The appendix presents a decision tree: +- "I mainly write text and research documents" → CLI or VS Code +- "I work with lots of image files" → GitHub Desktop +- "I write code alongside design work" → VS Code or JetBrains +- "I want the simplest possible interface" → GitHub Desktop +- "I want maximum control" → CLI + +No choice is wrong. The best Git tool is the one you'll actually use. + +--- + +## Appendix B — Tool Integration + +Kai gives the team a look behind the curtain. + +SketchSpark's own architecture uses Git internally. When a user uploads a sketch and the system generates 5 UI options, each option is created as a lightweight branch in a temporary repository using **libgit2** (C library, called from the Python backend). The user's "compare options" screen is reading from Git branches. The "pick this one" button is a merge. The product's UX is a Git workflow — the user just never sees `git` commands. + +This reframing — "you've been using Git concepts all along without knowing it" — lands differently now that readers understand branches and merges from their own experience. + +Priya is intrigued by a different angle. She wants to automate her export workflow: every time she exports illustrations from her design tool, a script should auto-commit them to Git. She finds **Dulwich**, a Python Git library, and writes a script: + +```python +# Simplified — watches export folder and auto-commits new PNGs +from dulwich.repo import Repo +repo = Repo(".") +repo.stage(["illustrations/onboarding/step-1-upload.png"]) +repo.do_commit(b"Auto-export: updated onboarding illustration step 1") +``` + +It's ten lines of code (Kai helps with the details). Now her Git workflow is: export from design tool → script commits automatically → she opens a PR when the batch is ready. The manual `git add` / `git commit` cycle disappears for her binary file workflow. + +The appendix isn't about learning to write Git libraries. It's about understanding that the tools designers already use — GitHub Desktop, Figma plugins, CI/CD pipelines — are built on these libraries. Knowing they exist demystifies "how does GitHub Desktop work?" and opens the door to simple automation. + +--- + +## Appendix C — Reference + +The command reference is organized by SketchSpark workflow, not alphabetical command taxonomy. + +**Starting a Project** +- `git init` — Create a new repository (Nora in Chapter 2) +- `git clone` — Copy an existing repository (Sam joining in Chapter 3) +- `git config` — Set your name, email, editor, commit template (Chapter 1, Chapter 8) + +**Daily Design Work** +- `git status` — What's changed since my last commit? +- `git add` — Select files to include in the next commit +- `git add -p` — Select specific changes within a file (Nora in Chapter 7) +- `git commit` — Save a checkpoint with a message +- `git diff` — What exactly changed? (works for text files; limited for binary) +- `git stash` — Set aside work-in-progress temporarily (Sam in Chapter 7) + +**Exploring & Branching** +- `git branch` — List, create, or delete branches +- `git checkout` / `git switch` — Move to a different branch +- `git merge` — Combine one branch into another +- `git rebase` — Replay commits onto a different base (Sam in Chapter 3) + +**Collaborating** +- `git remote` — Manage connections to shared repositories +- `git push` — Send your commits to the shared repository +- `git pull` — Download and merge teammates' changes +- `git fetch` — Download without merging (check first, merge later) + +**Reviewing History** +- `git log` — See commit history (with `--oneline --graph` for visual overview) +- `git log -S "keyword"` — Find when a specific term was added or removed +- `git blame` — Find who last changed each line of a file (Priya in Chapter 7) +- `git show` — Display a specific commit's contents + +**Shipping a Release** +- `git tag` — Mark a commit as a release (v0.1-concept, v0.5-alpha, v1.0) +- `git archive` — Create a distributable zip/tar without Git history + +**Fixing Mistakes** +- `git restore` — Discard uncommitted changes to a file +- `git restore --staged` — Unstage a file without losing changes +- `git reset --soft HEAD~1` — Undo the last commit, keep changes staged (Sam in Chapter 7) +- `git revert` — Create a new commit that undoes a previous commit (safe for shared branches) +- `git reflog` — Find lost commits after a destructive operation (Nora in Chapter 10) + +**Maintaining Quality** +- `git clean` — Remove untracked files (caution: irreversible for design exports) +- `git lfs` — Manage large binary files (illustrations, PSDs) without bloating the repo + +Each command links back to the chapter where it appears in the storyline, so readers can revisit the full context. + +--- + +## Recurring Threads + +These themes weave through every chapter, creating continuity beyond the plot: + +**Binary vs. Text.** Introduced in Chapter 1 (Nora's question about Sketch files), demonstrated in Chapter 2 (wireframe PNGs vs. markdown briefs), painful in Chapter 5 (Priya's large illustrations), configured in Chapter 8 (`.gitattributes`), resolved in Chapter 9 (Git LFS). Every chapter reinforces: text files are Git's strength; binary files require extra care. + +**The Five Options.** The product generates 5 options from 1 sketch. Git creates parallel branches from 1 commit. This parallel is explicit in Chapter 3 (Sam's three `option/` branches), implicit in Chapter 5 (four parallel feature branches), and architectural in Appendix B (the product uses Git branches internally). The metaphor deepens as the reader's Git knowledge grows. + +**Design Decisions as Commits.** Every commit in the storyline represents a design decision — not a code change. "Update primary color for accessibility," "Add tablet breakpoint to onboarding," "Improve mobile generation prompt." This reframes Git from a developer tool to a design decision ledger. + +**Progressive Team Growth.** Chapter 1: solo. Chapter 2: solo with structure. Chapter 3: pair. Chapter 5: team of four. Chapter 6: open community. Each growth stage introduces the Git workflow that stage demands — tags when you're solo, branches when you're two, integration manager when you're four, fork-and-PR when you're open source. + +**The Safety Net.** Git's ability to recover from mistakes is introduced gently (undo in Chapter 2), tested (reset in Chapter 7), and fully proven (reflog recovery in Chapter 10). By the final chapter, the reader trusts that Git protects their work — the same trust that motivated Nora to adopt it after her file loss in Chapter 1. The story ends where it began: your work is never truly lost. From 0c21fb605592487cb0e293bd1dc7e4f4fa87fc45 Mon Sep 17 00:00:00 2001 From: Claude <noreply@anthropic.com> Date: Sat, 4 Apr 2026 22:55:55 +0000 Subject: [PATCH 13/17] Add section-by-section outlines for all 13 chapters and appendices Each outline maps the original Pro Git sections to the SketchSpark storyline, specifying what stays, what gets rewritten, what's new, and what gets cut. Includes target line counts and specific example replacements for every section. https://claude.ai/code/session_011MhF8iWLG3rS5jturtiTZ5 --- 00-notes/01-introduction/outline.md | 140 ++++++++++++ 00-notes/02-git-basics/outline.md | 199 ++++++++++++++++++ 00-notes/03-git-branching/outline.md | 158 ++++++++++++++ 00-notes/04-git-server/outline.md | 142 +++++++++++++ 00-notes/05-distributed-git/outline.md | 143 +++++++++++++ 00-notes/06-github/outline.md | 134 ++++++++++++ 00-notes/07-git-tools/outline.md | 157 ++++++++++++++ 00-notes/08-customizing-git/outline.md | 136 ++++++++++++ 00-notes/09-git-and-other-scms/outline.md | 90 ++++++++ 00-notes/10-git-internals/outline.md | 153 ++++++++++++++ .../A-git-in-other-environments/outline.md | 92 ++++++++ 00-notes/B-embedding-git/outline.md | 106 ++++++++++ 00-notes/C-git-commands/outline.md | 96 +++++++++ 13 files changed, 1746 insertions(+) create mode 100644 00-notes/01-introduction/outline.md create mode 100644 00-notes/02-git-basics/outline.md create mode 100644 00-notes/03-git-branching/outline.md create mode 100644 00-notes/04-git-server/outline.md create mode 100644 00-notes/05-distributed-git/outline.md create mode 100644 00-notes/06-github/outline.md create mode 100644 00-notes/07-git-tools/outline.md create mode 100644 00-notes/08-customizing-git/outline.md create mode 100644 00-notes/09-git-and-other-scms/outline.md create mode 100644 00-notes/10-git-internals/outline.md create mode 100644 00-notes/A-git-in-other-environments/outline.md create mode 100644 00-notes/B-embedding-git/outline.md create mode 100644 00-notes/C-git-commands/outline.md diff --git a/00-notes/01-introduction/outline.md b/00-notes/01-introduction/outline.md new file mode 100644 index 000000000..877c27ef5 --- /dev/null +++ b/00-notes/01-introduction/outline.md @@ -0,0 +1,140 @@ +# Chapter 1: Getting Started — Section Outline + +> **Storyline phase**: Research & Discovery +> **Characters**: Nora (solo) +> **Key event**: Nora loses research files to a sync conflict, discovers Git + +--- + +## Section: About Version Control (`about-version-control.asc`) +**Original**: 61 lines | **Action**: REWRITE + +### Keep +- Core structure: local → centralized → distributed progression +- Diagrams (local VCS, CVCS, DVCS) — update captions only + +### Rewrite +- **Opening hook**: Replace generic "graphic designers or web designers" mention (line 8) with Nora's story — she's running user research for SketchSpark and loses a week of interview notes when her cloud sync overwrites the folder with a stale version +- **Local VCS**: Replace RCS reference with "saving copies in dated folders" — `interview-notes-v1/`, `interview-notes-FINAL/`, `interview-notes-FINAL-v3-REAL/`. Nora's actual workflow before Git. +- **Centralized VCS**: Replace CVS/Subversion/Perforce with shared Google Drive analogy. "Everyone connects to one place. If it's down or conflicts, work is lost." Reference Figma's shared file model as another example designers know. +- **Distributed VCS**: Replace Mercurial/Darcs with practical framing. "Every team member has the full history locally. If the cloud disappears, your laptop still has everything." + +### New +- After DVCS section, add 2-line SketchSpark context: "In this book, we'll follow a product called SketchSpark — an AI-powered prototyping tool — from research through launch. Git protects every artifact the team creates along the way." + +--- + +## Section: A Short History of Git (`history.asc`) +**Original**: 20 lines | **Action**: TRIM + REFRAME + +### Keep +- Design goals list (speed, simple design, non-linear development, fully distributed, large projects) + +### Rewrite +- Replace Linux kernel / BitKeeper backstory (irrelevant to designers) with 2-line summary: "Git was created in 2005 for the Linux kernel project. Its design goals — speed, branching, and full local history — make it equally suited to managing design projects." +- Add after goals list: "For a design team, these goals mean: Git handles hundreds of files, supports exploring multiple directions simultaneously, and works fully offline." + +### Target +- ~12 lines (down from 20) + +--- + +## Section: What is Git? (`what-is-git.asc`) +**Original**: 109 lines | **Action**: REWRITE + +### Keep +- Section structure (Snapshots, Local Operations, Integrity, Only Adds Data, Three States) +- Diagrams (snapshots vs. deltas, three states) +- Three-step workflow summary + +### Rewrite +- **Snapshots**: Replace "stream of snapshots" language with "Git takes a picture of your entire project every time you commit — like a save point you can always return to." Connect to Nora: "Each commit captures every research document, wireframe, and design file exactly as they are at that moment." +- **Local Operations**: Add: "You can review your project history, compare versions, and commit new work without internet. Critical when working on planes, in cafes, or when the office Wi-Fi goes down." +- **Integrity**: Simplify SHA-1 to: "Every commit is identified uniquely and permanently. You don't need to understand the math — just know that Git can always detect if something has been corrupted or changed." +- **Only Adds Data**: Add Nora's reassurance: "After losing those interview notes, this is what sold me on Git. Once you commit, that snapshot is safe. You'd have to go out of your way to destroy it." +- **Three States**: Map to Nora's workflow: + - Modified = "You've updated the competitive analysis but haven't marked it as ready" + - Staged = "You've selected which updates to bundle into this checkpoint" + - Committed = "The checkpoint is permanent — you can always come back to it" + +### New +- Add sidebar: "Git and Design Files — What to Know Early" + - Text files (`.md`, `.json`, `.yaml`, `.txt`, `.svg`) → Git tracks every change, shows diffs, merges cleanly + - Binary files (`.png`, `.psd`, `.sketch`, `.fig`) → Git stores them but can't show what changed visually, can't merge + - "This distinction — text vs. binary — comes up in every chapter. Keep it in mind." + +--- + +## Section: The Command Line (`command-line.asc`) +**Original**: 11 lines | **Action**: REWRITE + +### Rewrite +- Soften CLI-only stance. Replace "only place you can run all Git commands" with balanced framing: + - "This book teaches Git through the command line because every Git concept maps directly to a command. Once you understand the commands, any GUI tool (GitHub Desktop, VS Code, GitKraken) will make sense." + - "If you prefer a visual interface, that's fine. Appendix A covers GUI options. But learning the commands first gives you the vocabulary to understand what the GUI is doing." +- Add: "Nora started with the command line. Sam (who joins in Chapter 3) prefers VS Code. Priya (Chapter 5) uses GitHub Desktop. All three are valid." + +--- + +## Section: Installing Git (`installing.asc`) +**Original**: 137 lines | **Action**: TRIM + +### Keep +- Linux (dnf/apt), macOS (Xcode CLT), Windows (git-scm.com) instructions +- Basic structure + +### Cut +- "Installing from Source" section (lines 64-137, 73 lines) — move to appendix or link. No designer will compile Git from source. + +### New +- Add after installation: verification step — `git --version` to confirm it worked +- Add note: "If you prefer a GUI, install GitHub Desktop (desktop.github.com) alongside Git. It includes Git and provides a visual interface." + +### Target +- ~70 lines (down from 137) + +--- + +## Section: First-Time Git Setup (`first-time-setup.asc`) +**Original**: 136 lines | **Action**: REWRITE + +### Keep +- Identity setup commands (`git config --global user.name`, `user.email`) +- Default branch name (`init.defaultBranch main`) +- Checking settings (`git config --list`) + +### Rewrite +- Simplify three-level config hierarchy to: "Git has settings at three levels: system-wide, your user account, and per-project. The user-level (`--global`) is all you need right now." +- Replace editor setup (Vim/Emacs/Notepad++) with: "If you use VS Code: `git config --global core.editor 'code --wait'`". Add one-liner for other common editors as a table. +- Add Nora connection: "Just like Figma records who made each change, Git attributes every commit to you using this name and email." + +### Cut +- Detailed editor configuration table (lines 50-84) — replace with 3-line quick reference +- Windows-specific registry detail + +### Target +- ~80 lines (down from 136) + +--- + +## Section: Getting Help (`help.asc`) +**Original**: 50 lines | **Action**: TRIM + UPDATE + +### Keep +- Three help syntax variants +- `git add -h` quick help example + +### Rewrite +- Replace IRC/Libera Chat references with modern resources: Stack Overflow, GitHub Community, Discord servers +- Reorder: put `-h` flag first (quick, easy), then `git help <verb>` for full docs + +### Target +- ~35 lines (down from 50) + +--- + +## Chapter Summary Section +**Action**: REWRITE + +### New +- Connect to storyline: "Nora has Git installed, configured, and understands the core concepts — snapshots, the three states, and the text-vs-binary distinction. In the next chapter, she creates the SketchSpark repository and starts tracking the product's concept design artifacts." diff --git a/00-notes/02-git-basics/outline.md b/00-notes/02-git-basics/outline.md new file mode 100644 index 000000000..bcb4c954c --- /dev/null +++ b/00-notes/02-git-basics/outline.md @@ -0,0 +1,199 @@ +# Chapter 2: Git Basics — Section Outline + +> **Storyline phase**: Concept Design +> **Characters**: Nora (solo) +> **Key event**: Nora creates the SketchSpark repo, learns the daily Git workflow + +--- + +## Section: Getting a Repository (`getting-a-repository.asc`) +**Original**: 88 lines | **Action**: REWRITE EXAMPLES + +### Keep +- Two-path structure: init vs. clone +- Command syntax and explanations +- Protocol mention for clone + +### Rewrite +- **Init example**: Replace generic `my_project` with Nora initializing the SketchSpark directory: + ``` + cd sketchspark + git init + git add product-brief.md research/personas/ concept/user-flows.md + git commit -m "Add product brief, personas, and initial user flows" + ``` +- **Clone example**: Replace `libgit2` with: `git clone https://github.com/sketchspark/sketchspark.git` — framed as "this is how Sam will join the project in the next chapter" +- Add `.gitignore` mention here (currently absent): "Before your first commit, create a `.gitignore` file to exclude temp files your design tools generate." + +### New +- Add sidebar: "What Belongs in a Design Project Repo?" — text files (briefs, research, tokens, docs), exported assets (PNGs, SVGs), source files (discussion of tradeoffs with large binaries) + +--- + +## Section: Recording Changes (`recording-changes.asc`) +**Original**: 630 lines | **Action**: REWRITE EXAMPLES, TRIM + +### Keep +- File lifecycle diagram +- Status → stage → commit workflow structure +- `.gitignore` pattern syntax +- `git diff` explanation +- Commit message guidance +- File removal and moving + +### Rewrite +- **All file references**: Replace `benchmarks.rb`, `CONTRIBUTING.md`, `Rakefile`, `lib/simplegit.rb` with: + - `product-brief.md` (text, mergeable) + - `research/competitive-analysis.md` (text) + - `concept/wireframes/sketch-input.png` (binary) + - `design-tokens.json` (structured text, later chapters) +- **Status example**: Nora checks status after adding wireframe exports — show both tracked text files and new binary files +- **Staging explanation**: "Staging is selecting which changes to bundle into this commit. Nora updated both the product brief and the wireframes, but she commits them separately — text and binary changes serve different review purposes." +- **`.gitignore`**: Replace default patterns with design-specific template: + ``` + .DS_Store + __MACOSX/ + Thumbs.db + *.sketch~ + *.figma_cache + node_modules/ + ``` +- **Diff**: Show `git diff` on `product-brief.md` (useful, shows word changes) and note: "Running `git diff` on `sketch-input.png` shows nothing useful — Git knows the file changed but can't display visual differences for binary files." +- **Commit messages**: Replace generic messages with SketchSpark examples: + - `Add product brief and initial user flows` + - `Add wireframes for sketch input and results comparison screens` + - `Update competitive analysis with two additional tools` + +### Cut +- Reduce `git diff --staged` vs `git diff` explanation (keep one clear example, cut repetition) +- Trim "Skipping the Staging Area" — keep as a note, not a full subsection + +### New +- Add "Commit Messages for Design Work" sidebar: + - Good: `Add competitive analysis with 6 prototyping tools reviewed` + - Good: `Update product brief — change from 3 to 5 parallel options` + - Bad: `Updated stuff` / `WIP` / `changes` + - Tip: "Write messages that help your future self (or teammate) understand *why*, not just *what*." + +--- + +## Section: Viewing the Commit History (`viewing-history.asc`) +**Original**: 307 lines | **Action**: REWRITE EXAMPLES, TRIM + +### Keep +- `git log` with common flags (`--oneline`, `--graph`, `--stat`) +- Limiting output (`--since`, `--author`, `-S`) +- Format table (useful reference) + +### Rewrite +- All example output uses SketchSpark commits: + ``` + a1b2c3d Add wireframes for sketch input and results comparison screens + d4e5f6g Update competitive analysis with two additional tools + h7i8j9k Add product brief, personas, and initial user flows + ``` +- **`-S` search**: `git log -S "5 options" -- product-brief.md` — Nora traces when the product concept changed from 3 options to 5 +- **`--author`**: Preview for later chapters: "When Sam joins, `git log --author='Sam'` shows only his commits." +- **`--stat`**: Show file-level summary including a binary file (PNG) to demonstrate that stats work for binary too (shows bytes changed) + +### Trim +- Reduce format specifier table to the 5 most useful entries +- Cut `--pretty=format:` deep dive — keep one example, link to docs for full reference + +--- + +## Section: Undoing Things (`undoing.asc`) +**Original**: 236 lines | **Action**: REWRITE EXAMPLES + +### Keep +- Amend workflow +- Both old (`git reset`, `git checkout`) and new (`git restore`) unstaging/unmodifying +- Warnings about dangerous operations + +### Rewrite +- **Amend scenario**: Nora commits the product brief but forgets to include the updated persona document: + ``` + git commit -m "Add product brief and personas" + # Oops — forgot early-adopter.md + git add research/personas/early-adopter.md + git commit --amend + ``` +- **Unstage scenario**: Nora accidentally stages a large wireframe PNG she's not ready to commit: + ``` + git restore --staged concept/wireframes/results-comparison.png + ``` +- **Discard changes**: Nora decides her edits to `user-flows.md` went in the wrong direction: + ``` + git restore concept/user-flows.md + ``` + Warning: "This throws away uncommitted changes permanently. Unlike committed work, uncommitted changes can't be recovered." + +### New +- Add Nora's reflection: "This is why I commit frequently — committed work is safe. Uncommitted work is not." + +--- + +## Section: Working with Remotes (`remotes.asc`) +**Original**: 241 lines | **Action**: REWRITE EXAMPLES, TRIM + +### Keep +- Core concepts: origin, fetch, pull, push +- Adding/removing remotes +- Inspecting remotes + +### Rewrite +- Replace `pb` (Paul's branch) / `teamone` / `bakkdoor` with design-relevant remotes: + - `origin` = SketchSpark's main repo on GitHub (set up in Chapter 4) + - Preview: "In Chapter 5, when Kai joins with the AI pipeline, his repository may become a second remote." +- All URL examples use `github.com/sketchspark/sketchspark.git` +- Simplify `git remote show origin` output to show only the branches relevant to the storyline + +### Trim +- Reduce multiple-remote complexity — one remote (`origin`) is enough for this chapter. Multiple remotes return in Chapter 5. + +--- + +## Section: Tagging (`tagging.asc`) +**Original**: 300 lines | **Action**: REWRITE EXAMPLES, TRIM + +### Keep +- Annotated vs. lightweight distinction +- Creating, listing, sharing, deleting tags +- Tagging past commits + +### Rewrite +- Replace generic `v1.4` / `v1.5` with SketchSpark milestones: + ``` + git tag -a v0.1-concept -m "Research complete, concept approved, entering UI exploration" + ``` +- Frame tags as product milestones: "Tags mark moments you'll want to return to — concept approval, alpha release, public beta. They're permanent bookmarks in your project history." + +### Trim +- Reduce "Checking out Tags" to a note about detached HEAD — designers won't use this often +- Cut lightweight tag detail to 2 lines — annotated tags are the recommendation + +--- + +## Section: Git Aliases (`aliases.asc`) +**Original**: 71 lines | **Action**: REWRITE EXAMPLES + +### Keep +- Concept and syntax +- External command aliases (`!`) + +### Rewrite +- Replace generic aliases with SketchSpark-relevant ones: + ``` + git config --global alias.last 'log -1 HEAD' + git config --global alias.visual 'log --oneline --graph --all' + git config --global alias.recent 'log --oneline -10' + ``` +- Add: "Nora creates an alias to check what changed in research files: `git config --global alias.research-log 'log --oneline -- research/'`" + +--- + +## Chapter Summary +**Action**: REWRITE + +### New +- "Nora's SketchSpark repo has a product brief, personas, a competitive analysis, user flows, and wireframes — all versioned, all recoverable. She's tagged the concept milestone (`v0.1-concept`) and established a commit rhythm. In the next chapter, Sam joins the project and they discover branches — the feature that makes Git indispensable for parallel design exploration." diff --git a/00-notes/03-git-branching/outline.md b/00-notes/03-git-branching/outline.md new file mode 100644 index 000000000..c25b68ae8 --- /dev/null +++ b/00-notes/03-git-branching/outline.md @@ -0,0 +1,158 @@ +# Chapter 3: Git Branching — Section Outline + +> **Storyline phase**: Parallel Exploration +> **Characters**: Nora, Sam (joins this chapter) +> **Key event**: Sam explores 3 UI directions as branches; first merge conflict on `user-flows.md` + +--- + +## Section: Branches in a Nutshell (`nutshell.asc`) +**Original**: 211 lines | **Action**: REWRITE + +### Keep +- Core explanation of how branches work (pointer to a commit) +- HEAD as "where you are now" +- Diagrams showing branch pointer movement +- `git branch`, `git checkout`, `git switch` commands + +### Rewrite +- **Opening**: Replace abstract pointer explanation with: "A branch is a parallel workspace. You can explore an idea without affecting anyone else's work — and switch back to the stable version instantly." +- **Creating a branch**: Replace `testing` with `option/card-layout` — Sam's first UI direction for the results screen +- **HEAD analogy**: "HEAD is which workspace you're currently in. When you switch branches, HEAD moves, and your files update to match." +- **All file references**: Replace generic files with SketchSpark artifacts +- Remove "41 bytes" lightweight emphasis — provides no actionable value for designers + +### New +- Add after branch creation: "Sam will create three branches to explore three different layouts for the results screen — the screen where users see 5 generated UI options. This mirrors the product's own concept: multiple options from a single starting point." + +--- + +## Section: Basic Branching and Merging (`basic-branching-and-merging.asc`) +**Original**: 319 lines | **Action**: REWRITE + +### Keep +- Three-part structure: branching → merging → conflict resolution +- Fast-forward merge concept +- Three-way merge concept +- Conflict markers explanation +- Diagrams + +### Rewrite +- **Branching scenario**: Replace issue #53 / hotfix with SketchSpark story: + - Sam is working on `option/card-layout` (results screen as a card grid) + - Nora discovers a missing upload error state on `main` + - Sam creates `fix/sketch-input-upload-error`, fixes the error state, merges to `main` + - Sam returns to `option/card-layout` +- **Merge scenario**: Sam finishes the card layout and merges to `main` +- **Conflict scenario**: Both Nora and Sam edited `concept/user-flows.md` — Nora refined the upload step, Sam added a "compare options" step. Show the conflict markers with design-relevant content: + ``` + <<<<<<< HEAD + 3. User uploads sketch via drag-and-drop or file picker + ======= + 3. User uploads sketch via drag-and-drop + 4. System generates 5 options and displays comparison view + >>>>>>> option/card-layout + ``` + Resolution: keep both — Nora's refined upload step AND Sam's comparison step. +- Add after conflict resolution: "This was a text file, so Git showed exactly where the conflict was. If this had been a PNG or Figma file, Git couldn't show the conflict — you'd need to open both versions and manually compare." + +--- + +## Section: Branch Management (`branch-management.asc`) +**Original**: 184 lines | **Action**: REWRITE EXAMPLES, TRIM + +### Keep +- `git branch -v`, `--merged`, `--no-merged` +- Branch deletion + +### Rewrite +- Replace generic branch names with SketchSpark names: + - `option/card-layout` (merged) + - `option/list-layout` (not merged — still exploring) + - `option/canvas-freeform` (not merged) + - `fix/sketch-input-upload-error` (merged) +- Show `git branch --merged` to identify which exploration branches have been integrated + +### Trim +- Cut "Changing the master branch name" subsection (lines 80-184) — useful but not storyline-relevant. Keep as a note linking to the full guide. + +### New +- Add "Branch Naming for Design Projects" sidebar: + - `option/` — design explorations (may be discarded) + - `feature/` — approved work heading to production + - `fix/` — corrections to existing work + - `research/` — investigation branches (new interviews, usability tests) + +--- + +## Section: Branching Workflows (`workflows.asc`) +**Original**: 64 lines | **Action**: REWRITE + +### Keep +- Long-running branches concept +- Topic branches concept +- Diagrams + +### Rewrite +- **Long-running branches**: Map stability levels to SketchSpark: + - `main` = approved, stable work (could ship at any time) + - `develop` = reviewed work queued for next milestone (used in later chapters) + - `option/*` and `feature/*` = work-in-progress +- **Topic branches**: Frame as "each design exploration gets its own branch." Sam's three `option/` branches are the example. +- Replace "pu" (proposed updates) with design-relevant naming +- Add: "The team reviews all three options. They choose the card layout. The other two branches are archived — the work isn't lost, just not merged." + +--- + +## Section: Remote Branches (`remote-branches.asc`) +**Original**: 237 lines | **Action**: REWRITE EXAMPLES, TRIM + +### Keep +- Remote-tracking branches concept (`origin/main`) +- Pushing and tracking +- `git branch -vv` for tracking status +- Pulling = fetch + merge + +### Rewrite +- Replace `serverfix` with SketchSpark branches: `feature/zoom-on-selection` +- Replace multi-server example (too complex for this stage) with single-remote workflow +- Add: "When Sam pushes `option/card-layout` to GitHub, it becomes `origin/option/card-layout`. Nora can fetch it, review it locally, and merge it through a pull request." + +### Trim +- Reduce multi-remote complexity — save for Chapter 5 +- Cut detailed refspec discussion — save for Chapter 10 + +--- + +## Section: Rebasing (`rebasing.asc`) +**Original**: 241 lines | **Action**: REWRITE, SIMPLIFY + +### Keep +- Basic rebase concept and workflow +- Rebase vs. merge comparison +- "Do not rebase commits that exist outside your repository" warning +- Diagrams + +### Rewrite +- **Basic rebase**: Sam rebases `option/list-layout` onto `main` (which now includes the merged card layout) to see if any ideas from the list layout are worth carrying forward on the updated codebase. +- **Analogy**: "Rebasing replays your changes on top of someone else's latest work — like re-sketching your concept using the team's updated component library as the foundation." +- **Perils**: "If Sam rebases a branch he's already pushed and shared with Nora, it rewrites history she's already seen. Don't rebase shared branches." + +### Trim +- Cut `--onto` advanced rebase (move to Chapter 7) +- Simplify "Rebase When You Rebase" recovery section — mention it exists, link to Chapter 7 for details +- Cut patch-id explanation to 1 line + +### New +- Add decision guide: "Should I rebase or merge?" + - "Working alone on a local branch? Rebase to keep history clean." + - "Branch is shared with teammates? Merge to preserve everyone's work." + - "Not sure? Merge. It's always safe." + +--- + +## Chapter Summary +**Action**: REWRITE + +### New +- "Sam explored three directions for the results screen. The team chose one, archived two, and cherry-picked an interaction from a third. They resolved their first merge conflict — in a text file, where Git could help. They know it won't be as easy with binary files. In the next chapter, the project outgrows Nora's laptop and moves to GitHub." diff --git a/00-notes/04-git-server/outline.md b/00-notes/04-git-server/outline.md new file mode 100644 index 000000000..f953e91da --- /dev/null +++ b/00-notes/04-git-server/outline.md @@ -0,0 +1,142 @@ +# Chapter 4: Git on the Server — Section Outline + +> **Storyline phase**: Team Infrastructure +> **Characters**: Nora, Sam +> **Key event**: SketchSpark moves to GitHub; branch protection and roles established + +--- + +## Structural Change: Reorder Sections + +The original chapter buries hosted options at the end. Designers almost always use hosted platforms. Reorder: + +1. Third Party Hosted Options (moved from position 9 to position 1) +2. The Protocols (trimmed) +3. SSH Key Generation (simplified) +4. GitLab (kept, reframed) +5. Getting Git on a Server (moved to "Advanced" section) +6. Setting Up the Server (moved to "Advanced") +7. Git Daemon (moved to "Advanced") +8. Smart HTTP (moved to "Advanced") +9. GitWeb (moved to "Advanced") + +--- + +## Section: Third Party Hosted Options (`hosted.asc`) — MOVED TO LEAD +**Original**: 11 lines | **Action**: EXPAND + +### Keep +- Concept of hosted options + +### Rewrite +- Expand from 11 lines to ~60 lines +- Add comparison table: GitHub vs. GitLab vs. Bitbucket (features relevant to design teams: PR reviews, branch protection, project boards, Pages for docs, free tier) +- Add Nora's decision: "The SketchSpark team picks GitHub — they already have accounts, the PR review workflow is visual, and GitHub Pages will host their product documentation later." + +### New +- "Quick Start: GitHub for Your Design Project" walkthrough: + 1. Create organization → create repository → push existing local repo + 2. Invite Sam as collaborator + 3. Enable branch protection on `main` (require PR, require 1 approval) + 4. Set up team roles (admin, write, read-only) +- This replaces the need for most of the server setup sections + +--- + +## Section: The Protocols (`protocols.asc`) +**Original**: 212 lines | **Action**: TRIM HEAVILY + +### Keep +- HTTPS and SSH protocol descriptions (the only two designers use) +- Brief pros/cons of each + +### Rewrite +- Frame as "Two ways to connect to GitHub": HTTPS (simpler, uses password/token) and SSH (more secure, uses key pair) +- Replace security language with designer framing: "HTTPS asks for your password each time (or a saved token). SSH uses a key file on your computer — set it up once and forget it." + +### Cut +- Local Protocol (lines 6-64) — move to advanced/appendix +- Dumb HTTP (irrelevant) +- Git Protocol (lines 180-211) — irrelevant for design teams + +### Target +- ~60 lines (down from 212) + +--- + +## Section: Generating Your SSH Public Key (`generating-ssh-key.asc`) +**Original**: 58 lines | **Action**: SIMPLIFY + +### Keep +- Key generation command (`ssh-keygen`) +- Checking for existing keys +- Displaying public key + +### Rewrite +- Sam's first SSH key: "Sam has never used SSH. Nora walks him through it." +- Simplify passphrase guidance: "Choose a passphrase you'll remember. It protects your key if your laptop is lost or stolen." +- Add: "The `.pub` file is safe to share — give it to GitHub. The other file is your secret key. Never share it, never commit it to a repository." + +### Cut +- `ssh-agent` discussion — too advanced for this stage +- Detailed key inspection + +### Target +- ~35 lines (down from 58) + +--- + +## Section: GitLab (`gitlab.asc`) +**Original**: 131 lines | **Action**: REFRAME + +### Keep +- Basic structure (installation, administration, usage, collaboration) +- Merge request workflow + +### Rewrite +- Reframe administration terms for design teams: + - Users → "Team Members" + - Groups → "Design Teams" + - Projects → "Repositories" +- Add design governance context: branch protection rules, merge request assignment, labels (`new-component`, `bug-fix`, `breaking-change`) +- Note: "If your organization uses GitLab instead of GitHub, the core concepts are identical — repositories, branches, merge requests (GitLab's term for pull requests), and code review." + +### Trim +- Cut installation details to: "GitLab can be self-hosted or used at gitlab.com. Ask your IT team for the URL." + +--- + +## Sections Moved to "Advanced: Self-Hosting" Block + +The following sections are wrapped in a single prefaced block: + +> "The sections below cover self-hosted Git servers. Most design teams use GitHub or GitLab and can skip this entirely. Read on only if your organization requires on-premises hosting." + +### Getting Git on a Server (`git-on-a-server.asc`) +**Original**: 102 lines | **Action**: KEEP, ADD NOTE +- Add intro note directing designers to the hosted section +- Replace `my_project` with `sketchspark.git` +- Keep bare repository explanation: "A bare repository is like a server copy — not edited directly, only used as a central reference point." + +### Setting Up the Server (`setting-up-server.asc`) +**Original**: 150 lines | **Action**: KEEP AS-IS +- Mark clearly as "for system administrators" + +### Git Daemon (`git-daemon.asc`) +**Original**: 67 lines | **Action**: KEEP AS-IS, ADD NOTE +- Add: "Rarely used by design teams. Skip unless your sysadmin specifically requires it." + +### Smart HTTP (`smart-http.asc`) +**Original**: 73 lines | **Action**: KEEP AS-IS, ADD NOTE + +### GitWeb (`gitweb.asc`) +**Original**: 71 lines | **Action**: KEEP AS-IS, ADD NOTE +- Add: "If you're using GitHub or GitLab, they provide much better interfaces. This section is for self-hosted setups only." + +--- + +## Chapter Summary +**Action**: REWRITE + +### New +- "SketchSpark lives on GitHub. The team has branch protection, roles, and a pull request workflow. Sam can push his branches and Nora can review before anything reaches `main`. In the next chapter, two more people join — Priya (illustrator) and Kai (engineer) — and the team learns to coordinate four parallel workstreams." diff --git a/00-notes/05-distributed-git/outline.md b/00-notes/05-distributed-git/outline.md new file mode 100644 index 000000000..831e1aab6 --- /dev/null +++ b/00-notes/05-distributed-git/outline.md @@ -0,0 +1,143 @@ +# Chapter 5: Distributed Git — Section Outline + +> **Storyline phase**: Design & Build Sprint +> **Characters**: Nora, Sam, Priya (joins), Kai (joins) +> **Key event**: Four parallel workstreams; first alpha release (v0.5-alpha) + +--- + +## Section: Distributed Workflows (`distributed-workflows.asc`) +**Original**: 103 lines | **Action**: REWRITE + +### Keep +- Three workflow patterns: Centralized, Integration-Manager, Dictator/Lieutenants +- Diagrams for each workflow + +### Rewrite +- **Centralized Workflow**: "For a two-person team like Nora and Sam in the previous chapters — both push to `main` on the same repo. Simple, but doesn't scale." +- **Integration-Manager Workflow**: "Nora now acts as integration manager. Sam, Priya, and Kai each work on their own branches. Nora reviews and merges their PRs to `main`. This is the workflow most teams on GitHub use." +- **Dictator/Lieutenants**: "Used in massive projects like Material Design or Bootstrap — governance layers for design system decisions. The SketchSpark team doesn't need this, but you might encounter it when contributing to large open-source design projects." +- Add: "As a designer, you'll most likely use Integration-Manager (fork + PR) for open-source projects, or Centralized for small internal teams." + +--- + +## Section: Contributing to a Project (`contributing.asc`) +**Original**: 803 lines | **Action**: REWRITE EXAMPLES, TRIM HEAVILY + +### Commit Guidelines (lines 33-99) +**Action**: REWRITE + +- Cut `git diff --check` for whitespace — irrelevant to designers +- Replace Tim Pope commit template with SketchSpark template: + ``` + [Design: Results Screen] Add card layout with 5-option grid + + The card layout shows all 5 generated options in a responsive grid. + Each card includes a thumbnail, confidence score, and "Select" button. + Choosing a card opens the refinement view. + ``` +- Keep: "Make each commit a logically separate changeset" — reframe with: "Nora commits the product brief separately from the wireframes because they serve different review purposes." +- Cut `git add --patch` reference — save for Chapter 7 + +### Private Small Team (lines 101-325) +**Action**: REWRITE + +- Replace John/Jessica with Nora/Sam/Priya/Kai: + - Nora: UX flows and research updates (`feature/ux-flows-v2`) + - Sam: production UI screens (`feature/production-screens`) + - Priya: onboarding illustrations (`feature/onboarding-illustrations`) + - Kai: AI pipeline setup (`feature/ai-pipeline-setup`) +- Replace all file references: + - `lib/simplegit.rb` → `concept/user-flows.md` + - `TODO` → `product-brief.md` + - `index.html` → `screens/results/card-layout.fig` +- Show the fetch/merge/push coordination cycle with Nora as integrator +- Add: Priya's first push takes 3 minutes (large illustration files). Note: "We'll address large file management in Chapter 8." + +### Private Managed Team (lines 327-497) +**Action**: REWRITE + TRIM + +- Replace `featureA`/`featureB` with: + - `feature/sketch-input-redesign` (Nora + Sam) + - `feature/ai-pipeline-v1` (Kai) +- Reframe: "Ideal when your team splits into workstreams — one pair working on the input experience, another building the generation pipeline." +- Trim detail — keep the coordination pattern, cut repetitive fetch/merge sequences + +### Forked Public Project (lines 499-636) +**Action**: LIGHT REWRITE + +- Preview for Chapter 6: "This workflow appears when SketchSpark goes public. External contributors fork the repo, make changes, and submit PRs." +- Reframe `--squash`: "Collapses all experimental changes into one clean commit — like flattening your iteration layers before presenting a final design." +- Replace file examples with SketchSpark prompt template improvement + +### Public Project over Email (lines 638-791) +**Action**: REPLACE WITH NOTE + +- Replace 153 lines of email workflow with: + > "This section describes an older contribution workflow using email patches. Modern design teams use GitHub or GitLab pull requests instead. If you're contributing to a project that requires email patches, refer to the original Pro Git book for detailed instructions." +- ~5 lines (down from 153) + +--- + +## Section: Maintaining a Project (`maintaining.asc`) +**Original**: 557 lines | **Action**: REWRITE EXAMPLES, TRIM + +### Working in Topic Branches (lines 8-29) +**Action**: REWRITE +- Replace `sc/ruby_client` with `priya/icon-overhaul`, `kai/generation-speed` +- Add: "Unlike code, design changes often span multiple file types — an illustration update might include PNGs, an SVG, and a documentation update. Keep related changes in one branch." + +### Applying Patches from Email (lines 31-182) +**Action**: REPLACE WITH NOTE +- Replace 151 lines with: "Most design projects use GitHub/GitLab pull requests. If you need to apply patches from email, see the original Pro Git reference." +- ~3 lines (down from 151) + +### Checking Out Remote Branches (lines 184-218) +**Action**: LIGHT REWRITE +- Replace generic contributor with: "Priya sends you a link to her `feature/onboarding-illustrations` branch. You want to review her illustrations locally." + +### Determining What Is Introduced (lines 220-294) +**Action**: REWRITE +- Replace generic diffs with: "You want to see exactly what screens Sam designed that aren't in `main` yet." +- Show `git log main..feature/production-screens --oneline` +- Show `git diff main...feature/production-screens -- screens/` + +### Integrating Contributed Work (lines 296-402) +**Action**: REWRITE + TRIM +- **Merging Workflows**: Nora's integration pattern — review PR, merge to `main`, tag milestones +- **Large-Merging Workflows**: Label as "advanced — for massive projects, not typical product teams" +- **Cherry-Picking**: Sam cherry-picks the "pinch-to-zoom" interaction from `option/canvas-freeform` into a new feature branch (callback to Chapter 3) +- **Rerere**: Trim to concept + 3-line summary — "Git can remember how you resolved a conflict and apply the same resolution automatically next time." + +### Tagging Releases (lines 428-482) +**Action**: REWRITE +- SketchSpark `v0.5-alpha`: + ``` + git tag -a v0.5-alpha -m "Alpha: end-to-end sketch-to-options pipeline working" + ``` +- Simplify PGP signing to 1 line: "Optional. For open-source projects, signed tags add credibility." + +### Preparing a Release (lines 505-528) +**Action**: REWRITE +- ``` + git archive main --prefix='sketchspark-v0.5-alpha/' --format=zip > sketchspark-v0.5-alpha.zip + ``` +- "The archive goes to the CEO for demo day." + +### The Shortlog (lines 531-557) +**Action**: REWRITE +- Show SketchSpark shortlog: + ``` + Nora (4): Updated user flows, Added round 2 interview findings, ... + Sam (6): Added card layout screens, Fixed upload error state, ... + Priya (3): Added onboarding illustrations, ... + Kai (5): Set up AI pipeline, Added generation prompts, ... + ``` + +--- + +## Chapter Summary +**Action**: REWRITE + +### New +- "The alpha works. Four team members coordinated their work through branches, pull requests, and an integration-manager workflow. Priya's large files are a growing concern. The next chapter takes SketchSpark public — and the team learns how open-source contribution works from the receiving end." diff --git a/00-notes/06-github/outline.md b/00-notes/06-github/outline.md new file mode 100644 index 000000000..5b73ead1c --- /dev/null +++ b/00-notes/06-github/outline.md @@ -0,0 +1,134 @@ +# Chapter 6: GitHub — Section Outline + +> **Storyline phase**: Public Beta & Community +> **Characters**: Nora, Sam, Priya, Kai, Marcus (external contributor) +> **Key event**: SketchSpark goes public; Marcus contributes improved mobile prompt via PR + +--- + +## Section: Account Setup and Configuration (`1-setting-up-account.asc`) +**Original**: 97 lines | **Action**: REWRITE EXAMPLES + +### Keep +- Account creation, SSH key upload, avatar, email settings +- Two-factor authentication + +### Rewrite +- Add SSH analogy: "Like a trusted device — once registered, no re-authentication needed." +- Add 2FA context: "Prevents a compromised password from putting all your team's design assets at risk." +- Replace email linking example: "If you use work and personal accounts, link both emails so GitHub tracks your total contribution history across both." + +--- + +## Section: Contributing to a Project (`2-contributing.asc`) +**Original**: 548 lines | **Action**: REWRITE + +### Forking (lines 5-26) +- Replace fork explanation with: "Forking is like duplicating a shared project to your own workspace. You can experiment freely without affecting the original." + +### GitHub Flow / Creating a PR (lines 29-195) +**Action**: FULL REWRITE — this is the chapter's centerpiece +- Replace Arduino blink example with Marcus's contribution to SketchSpark: + 1. Marcus forks `sketchspark/sketchspark` to `marcus/sketchspark` + 2. Creates `feature/mobile-prompt-template` + 3. Edits `prompts/sketch-to-ui.txt` to add mobile-specific layout constraints + 4. Adds new file: `prompts/mobile-layout.txt` + 5. Commits, pushes, opens PR + 6. PR description includes before/after screenshots: 5 generated options from the same sketch, current vs. improved prompt. Mobile options show better touch target sizing. +- Walk through the PR interface with design-relevant content + +### Iterating on a PR (lines 147-205) +**Action**: REWRITE +- Nora reviews Marcus's PR the next morning (different timezone — 16 hours apart) +- Feedback: prompt format doesn't match template, mobile-layout file needs a header comment, suggests splitting touch-target constraint for readability +- Marcus pushes updates. Nora approves and merges. +- Key point: "You don't need changes to be 'perfect' before opening a PR. Opening early lets your team weigh in on direction — just like sharing a rough sketch for feedback." + +### Advanced Pull Requests (lines 206-296) +**Action**: TRIM +- Keep cross-reference and PR-on-PR concepts +- Cut detail on keeping up with upstream — simplify to: `git fetch upstream && git merge upstream/main` + +### GitHub Flavored Markdown (lines 298-486) +**Action**: KEEP + EXPAND IMAGES +- Keep task lists, code blocks, tables, emoji — all useful for PR descriptions +- **Expand image embedding** (currently 10 lines): "Drag-and-drop screenshots into PR comments for design reviews. Include before/after comparisons, annotate with arrows or highlights, show responsive behavior at different breakpoints." +- Add: "For design PRs, screenshots aren't optional — they're the primary review artifact. Every PR that changes visual output should include them." + +### Keeping Forks in Sync (lines 488-548) +**Action**: LIGHT REWRITE +- Frame as: "Marcus keeps his fork synced so his next contribution starts from the latest version." + +--- + +## Section: Maintaining a Project (`3-maintaining.asc`) +**Original**: 377 lines | **Action**: REWRITE EXAMPLES + +### Keep +- Repository creation, README, CONTRIBUTING, LICENSE +- Branch protection +- Collaborator management + +### Rewrite +- **CONTRIBUTING.md**: Replace generic example with SketchSpark guidelines: + - Prompt template format (system context → user instruction → constraints) + - Illustration specs (2x resolution, brand palette, PNG with transparent background) + - Icon specs (24x24 grid, 2px stroke, SVG format) + - Screen mockups must include light and dark mode + - All UI must pass WCAG AA contrast +- **README**: Expand for design project: + - Product screenshot/GIF showing sketch-to-options flow + - Repository structure overview + - Quick start guide + - Link to live docs (GitHub Pages) +- **Branch protection**: Nora configures: PRs required, 1 approval, status checks +- **Labels**: `prompt-improvement`, `new-screen`, `bug`, `accessibility`, `breaking-change` + +### New +- Add "GitHub Pages for Design Documentation" subsection: + - Team deploys product docs to `sketchspark.github.io` + - Setup walkthrough (enable Pages, point to `/docs` folder or `gh-pages` branch) + +--- + +## Section: Managing an Organization (`4-managing-organization.asc`) +**Original**: 72 lines | **Action**: REWRITE EXAMPLES + +### Keep +- Organization creation, teams, permissions + +### Rewrite +- Frame with SketchSpark org: + - `@core-team`: Nora, Sam, Priya, Kai (write access to all repos) + - `@contributors`: Marcus and other external designers (fork-and-PR) + - `@stakeholders`: CEO, investors (read-only, comment on PRs) +- "If your product has 3+ contributors, an organization makes access management simpler than adding individual collaborators." + +--- + +## Section: Scripting GitHub (`5-scripting.asc`) +**Original**: 301 lines | **Action**: REWRITE + TRIM + +### Keep +- Webhooks concept +- API basics +- Practical automation examples + +### Rewrite +- Replace generic webhook with SketchSpark example: "When someone opens a PR, automatically post to `#design-reviews` in Slack." +- **GitHub Actions** (replace outdated Services section): + - "Actions let you automate validation when PRs are opened." + - SketchSpark example: validate that prompt templates don't exceed token limits, check SVG files for missing `<title>` elements +- Simplify API section: "Most automation tasks are easier via GitHub Actions than manual API calls. Use the API when Actions can't do what you need." + +### Cut +- Services section (deprecated, replaced by Actions/webhooks) +- Detailed API pagination examples — keep one simple example + +--- + +## Chapter Summary +**Action**: REWRITE + +### New +- "SketchSpark is public. The team receives and reviews external contributions, maintains clear guidelines for contributors, and uses GitHub's tools to manage the growing community. Marcus improved the mobile generation from Melbourne without ever meeting the team. In the next chapter, the product enters production — and the team encounters the complexity that comes with real users and real deadlines." diff --git a/00-notes/07-git-tools/outline.md b/00-notes/07-git-tools/outline.md new file mode 100644 index 000000000..0b101ec68 --- /dev/null +++ b/00-notes/07-git-tools/outline.md @@ -0,0 +1,157 @@ +# Chapter 7: Git Tools — Section Outline + +> **Storyline phase**: Production Hardening +> **Characters**: Nora, Sam, Priya, Kai +> **Key event**: Stashing, blame, interactive staging, rebase cleanup, submodules + +--- + +## Structural Note + +Chapter 7 is the largest chapter (15 sections, 38 walkthroughs). Several sections have very low design relevance. The outline groups them by priority tier and recommends cuts. + +--- + +## TIER 1: Full Rewrite (High design relevance) + +### Section: Stashing and Cleaning (`stashing-cleaning.asc`) +**Original**: 294 lines | **Action**: REWRITE + +- **Stash scenario**: Sam is redesigning the results comparison screen (adding overlay diff mode). Tablet layout bug reported. Sam stashes: + ``` + git stash push -m "WIP: overlay diff mode for results comparison" + ``` + Fixes tablet bug on `fix/onboarding-tablet-layout`, merges, returns: + ``` + git checkout feature/overlay-diff + git stash pop + ``` +- Replace `index.html`/`lib/simplegit.rb` with `screens/results/overlay-diff.fig`, `concept/user-flows.md` +- Keep `git stash list`, `git stash apply`, `git stash drop` +- Expand branch-from-stash: "Perfect when you start work on `main` and realize it should be a feature branch." +- **Clean**: Add warning — "If design exports were untracked, `git clean` removes them permanently. Use `git clean -n` (dry run) first." + +### Section: Advanced Merging (`advanced-merging.asc`) +**Original**: 682 lines | **Action**: REWRITE + TRIM + +- Replace `hello.rb` with `design-tokens.json` merge conflict (Nora changed color values, Sam changed typography values in the same file) +- Keep three-tree analogy, reframe: "Your version (working directory), the last shared version (HEAD), the incoming version (their branch)" +- Keep `--ours`/`--theirs` strategies — frame as: "For binary files that can't merge, choose one version: `git checkout --ours illustrations/hero.png`" +- Cut `dos2unix` preprocessing, `diff3` attribute detail +- Trim to ~350 lines + +### Section: Submodules (`submodules.asc`) +**Original**: 1039 lines | **Action**: REWRITE + TRIM HEAVILY + +- **Frame**: Kai's AI pipeline repo (`sketchspark-ml`) is a submodule of the main product repo +- Keep: adding a submodule, cloning with submodules, updating submodule pointer +- Rewrite all examples with `sketchspark-ml` as the submodule +- Cut: publishing submodule changes, submodule foreach, submodule merge/rebase (advanced — link to reference) +- Target: ~300 lines (down from 1039) + +--- + +## TIER 2: Rewrite Examples (Medium relevance) + +### Section: Reset Demystified (`reset.asc`) +**Original**: 331 lines | **Action**: REWRITE + +- Redesign three-tree metaphor for designers: + - HEAD = last committed snapshot ("the version you shipped") + - Index/Staging = next commit in preparation ("what you're about to ship") + - Working Directory = current state of files ("your live canvas") +- Replace `file.txt` with `design-tokens.json` +- **Sam's mistake**: commits to `main` instead of feature branch: + ``` + git reset --soft HEAD~1 # undo commit, keep changes staged + git checkout -b feature/screen-redesign + git commit -m "Redesign generation progress screen" + ``` +- Keep `--soft`, `--mixed`, `--hard` explanation with clear warnings +- **Squashing via reset**: Priya squashes messy icon commits (add/fix/fix again) into one clean commit + +### Section: Rewriting History (`rewriting-history.asc`) +**Original**: 402 lines | **Action**: REWRITE + TRIM + +- **Amend**: Nora commits product brief update but forgot to include the updated persona: + ``` + git add research/personas/early-adopter.md + git commit --amend + ``` +- **Interactive rebase**: Priya cleans up 5 icon commits into 2 clean ones before opening PR +- **Split**: Sam's commit touches both token changes and screen layout — split for separate review +- Add prominent warning: "Never rewrite history that's been pushed and shared with teammates." +- Cut `filter-branch` entirely — replaced by `git filter-repo` (mention as 1-line note for accidental large file commits) +- Target: ~250 lines (down from 402) + +### Section: Interactive Staging (`interactive-staging.asc`) +**Original**: 204 lines | **Action**: REWRITE + +- Replace file names with `product-brief.md`, `design-tokens.json` +- **Nora's scenario**: `product-brief.md` has both a scope change (adding tablet support) and research findings update. She stages only the research hunks for the current PR: + ``` + git add -p product-brief.md + ``` +- Keep patch mode explanation (`y/n/s/e`) +- Note: "This works for text files only. Binary files (PNGs, Figma exports) can't be partially staged." + +### Section: Searching (`searching.asc`) +**Original**: 160 lines | **Action**: REWRITE EXAMPLES + +- `git grep "primary-blue"` — find all files referencing a specific color token +- `git log -S "5 options" -- product-brief.md` — find when the product concept changed +- `git log -L :generateOptions:pipeline/main.py` — Kai traces function history +- Frame as "more relevant for design system maintainers and leads than individual contributors" + +### Section: Debugging (`debugging.asc`) +**Original**: 149 lines | **Action**: REWRITE EXAMPLES + +- **Blame**: Priya uses `git blame design-tokens.json` to find who changed `primary-blue` and when +- Since it's a text file, blame shows line-by-line attribution — "Commit `a1b2c3d` by Sam, 3 days ago, changed `primary-blue` from `#1a73e8` to `#1f71e8`" +- **Bisect**: Mark as optional/advanced — "If you're maintaining a large project and a visual regression appeared somewhere in the last 50 commits, bisect helps you find the exact commit. Otherwise, skip this." + +--- + +## TIER 3: Trim or Cut (Low relevance) + +### Section: Revision Selection (`revision-selection.asc`) +**Original**: 401 lines | **Action**: TRIM TO ~100 LINES +- Keep: short SHA references, branch references, `HEAD~` and `HEAD^` syntax +- Keep: commit ranges (`main..feature/screens`) +- Cut: detailed reflog walkthrough (save for Ch10), `@{upstream}` syntax detail, ancestry detail +- Frame ranges with: "See what Sam added that's not in main yet: `git log main..feature/production-screens`" + +### Section: Credentials (`credentials.asc`) +**Original**: 203 lines | **Action**: TRIM TO ~50 LINES +- Keep: cache, store, osxkeychain overview +- Cut: custom credential helpers, detailed implementation +- Frame: "If Git keeps asking for your password, configure a credential helper." + +### Section: Rerere (`rerere.asc`) +**Original**: 255 lines | **Action**: TRIM TO ~30 LINES +- Concept + enable command: `git config --global rerere.enabled true` +- "Git remembers how you resolved a conflict and applies the same resolution next time." + +### Section: Signing (`signing.asc`) +**Original**: 204 lines | **Action**: TRIM TO ~10 LINES +- "If your organization requires signed commits for compliance, configure GPG here. Most product teams don't use this." + +### Section: Bundling (`bundling.asc`) +**Original**: 171 lines | **Action**: CUT +- Move to appendix or remove. Designers don't transfer repos offline. + +### Section: Replace (`replace.asc`) +**Original**: 211 lines | **Action**: CUT +- Too advanced. No design team use case. + +### Section: Subtree Merges (`subtree-merges.asc`) +**Original**: 103 lines | **Action**: CUT +- Submodules section covers the relevant use case. Subtree merging is an alternative most teams won't need. + +--- + +## Chapter Summary +**Action**: REWRITE + +### New +- "The team has the tools to handle real-world complexity — stashing interrupted work, cleaning up messy history, resolving merge conflicts in token files, and managing the AI pipeline as a submodule. In the next chapter, they encode their process into the repository itself: Git attributes for binary files, commit templates, and validation hooks." diff --git a/00-notes/08-customizing-git/outline.md b/00-notes/08-customizing-git/outline.md new file mode 100644 index 000000000..35e93b379 --- /dev/null +++ b/00-notes/08-customizing-git/outline.md @@ -0,0 +1,136 @@ +# Chapter 8: Customizing Git — Section Outline + +> **Storyline phase**: Process & Automation +> **Characters**: Nora, Sam, Priya, Kai +> **Key event**: `.gitattributes` for binary files, commit template, pre-commit hooks + +--- + +## Section: Git Configuration (`config.asc`) +**Original**: 517 lines | **Action**: REWRITE + TRIM + +### Keep +- External merge/diff tools (visual comparison — intuitive for designers) +- Commit templates +- Color configuration +- `core.editor` setting + +### Rewrite +- **Commit template**: Replace `[Ticket: X]` with SketchSpark template: + ``` + [Phase: Component] Short description + + # Phases: Research, Concept, Design, Pipeline, Docs, Fix, Release + ``` + Show `git config commit.template .gitmessage` +- **Diff tool**: Expand with `design-tokens.json` diff example — show how visual diff tools make JSON changes easier to review +- **Color**: "Designers naturally understand color configuration — customize Git's terminal output to match your preferences." + +### Cut +- `core.autocrlf` and `core.whitespace` — irrelevant to designers working with design files +- Server-side config — designers don't administer servers +- Detailed pager/diff algorithm config + +### Target +- ~250 lines (down from 517) + +--- + +## Section: Git Attributes (`attributes.asc`) +**Original**: 377 lines | **Action**: REWRITE — THIS IS THE CHAPTER'S CENTERPIECE + +### Keep +- Binary file identification +- Custom diff drivers +- Export-ignore +- Merge strategies per file + +### Rewrite +- **Binary file handling**: Replace generic examples with SketchSpark's `.gitattributes`: + ``` + # Binary — don't attempt to diff or merge + *.png binary + *.psd binary + *.fig binary + *.sketch binary + + # Text-based design files — diff normally + *.svg diff + *.md diff + *.json diff + *.yaml diff + + # Large source files — version but exclude from archives + *.psd export-ignore + *.sketch export-ignore + research/raw-interviews/ export-ignore + ``` +- **Image diffing**: Nora sets up EXIF-based diffing for PNG exports — `git diff` shows metadata changes (dimensions, color profile, DPI). "It's not a visual diff, but it catches the color profile mistake that cost Priya time in Chapter 7." +- **Export-ignore**: "Priya's `.psd` source files are versioned in Git (for backup and history) but excluded from release archives. Stakeholders get clean exports, not 100MB Photoshop files." +- **Merge strategy**: "For binary design files, set `merge=ours` — if two people modify the same illustration, Git keeps your version and flags the conflict rather than producing a corrupted merge." + +### Cut +- C code indentation filter — replace with design-relevant filter concept: "A filter could auto-optimize SVGs on checkout or transform design tokens from JSON to CSS variables." +- Complex Ruby keyword expansion + +### New +- Add complete `.gitattributes` template for design projects with comments explaining each rule + +--- + +## Section: Git Hooks (`hooks.asc`) +**Original**: 131 lines | **Action**: REWRITE + +### Keep +- Hook lifecycle (client-side vs. server-side) +- pre-commit, commit-msg, post-commit + +### Rewrite +- Front-load the hooks designers will use: + 1. **pre-commit**: "Validate `model-params.yaml` syntax before committing. Check that prompt templates don't exceed 4096 tokens. Warn if PNG files exceed 5MB." + 2. **commit-msg**: "Validate that commit messages match `[Phase: Component]` pattern. Reject `fix stuff` with a helpful error." + 3. **post-commit**: "Trigger a design system build or Slack notification after each commit." +- De-emphasize email hooks (`applypatch-msg`, `pre-applypatch`) — designers never use `git am` +- Add: "Hooks are shell scripts in `.git/hooks/`. They run automatically. If a pre-commit hook fails, the commit is blocked until you fix the issue." + +### New +- Provide copy-paste hook scripts — designers can't write Ruby/Perl from scratch: + - YAML validation pre-commit hook (5 lines of bash) + - Commit message format validation (10 lines of bash) + - File size warning (5 lines of bash) + +--- + +## Section: An Example Git-Enforced Policy (`policy.asc`) +**Original**: 443 lines | **Action**: REWRITE + TRIM HEAVILY + +### Keep +- Concept of policy enforcement through hooks +- Client-side hook testing walkthrough + +### Rewrite +- Replace full Ruby scripts with simpler shell scripts +- Replace `[ref: XXXX]` pattern with `[Phase: Component]` pattern +- **ACL example**: Reframe for SketchSpark: + - Nora: edit anything + - Sam: edit `screens/`, `design-tokens.json`, `concept/` + - Priya: edit `illustrations/`, `icons/` + - Kai: edit `pipeline/`, `model-params.yaml` + - "This prevents accidentally committing to someone else's area." +- Emphasize client-side hooks over server-side — designers care about local validation +- Add testing scenario: "Sam tries to commit with message `fix stuff`. The hook rejects it and shows the expected format." + +### Cut +- Dense Ruby ACL implementation — replace with pseudo-code + explanation +- Server-side update hook detail (designers don't manage server hooks) + +### Target +- ~150 lines (down from 443) + +--- + +## Chapter Summary +**Action**: REWRITE + +### New +- "The team's process is now encoded in the repository. `.gitattributes` tells Git how to handle binary files. The commit template enforces consistent messages. Hooks validate files before they're committed. New contributors (like Marcus from Chapter 6) inherit these rules automatically when they clone. In the next chapter, the team faces an unexpected challenge: migrating a competitor's design assets from an older version control system." diff --git a/00-notes/09-git-and-other-scms/outline.md b/00-notes/09-git-and-other-scms/outline.md new file mode 100644 index 000000000..2d14a6f98 --- /dev/null +++ b/00-notes/09-git-and-other-scms/outline.md @@ -0,0 +1,90 @@ +# Chapter 9: Git and Other Systems — Section Outline + +> **Storyline phase**: Legacy Migration +> **Characters**: Nora, Priya +> **Key event**: Acquiring QuickMock competitor; migrating 3 years of SVN design assets + +--- + +## Structural Change: Drastically Trim + +This chapter drops from 7 sections (2,298 lines) to 3 focused sections. Most VCS bridge content is irrelevant to designers. The migration storyline justifies the content that remains. + +--- + +## Section: Git as a Client — Subversion (`client-svn.asc`) +**Original**: 490 lines | **Action**: TRIM TO ~120 LINES + +### Keep +- `git svn clone` basics +- `git svn dcommit` and `git svn rebase` workflow +- Branching limitations when bridging + +### Rewrite +- Frame: "QuickMock's design assets have lived in SVN for 3 years. During the transition period, the SketchSpark team needs to work with both systems." +- Replace generic branch examples with: `redesign/components`, `feature/new-icons` +- Add context: "SVN is the most likely legacy system you'll encounter in enterprise design environments — large companies sometimes keep design archives in SVN." + +### Cut +- SVN Style History detail +- SVN Annotation +- Detailed branching/merging mechanics (designers won't need SVN branching) +- Pre-rebase hook detail + +--- + +## Section: Importing from Subversion (`import-svn.asc`) +**Original**: 144 lines | **Action**: REWRITE + +### Keep +- `git svn clone` for full import +- Author mapping with `authors.txt` +- Post-import cleanup + +### Rewrite +- **Pre-import planning**: Nora audits QuickMock's SVN repo: + - 2,400 files, 1.2GB total + - Bulk of size: PSD source files (some >100MB) and high-res marketing renders + - Text files (research notes, docs): small and numerous +- **Decisions**: + - Import full history for text files — the evolution matters + - Import latest version only for large binaries — old 100MB PSDs aren't useful enough to justify bloat + - Configure Git LFS for files >10MB going forward + - Map QuickMock's flat folder structure to SketchSpark's organized hierarchy +- **Author mapping**: Map SVN usernames to Git identities so QuickMock's team gets proper attribution +- **Post-cleanup**: SVN `@` suffixes, LFS migration, folder reorganization +- Add: `git lfs migrate import --include="*.psd,*.ai" --above=10mb` +- Priya's observation: "I wish we'd set up LFS from the start." + +### New +- Add "Pre-Migration Checklist" sidebar: + 1. Check total repo size + 2. Identify files >10MB for LFS + 3. Create author mapping file + 4. Plan target folder structure + 5. Decide: full history or latest snapshot for binaries? + +--- + +## Sections: Everything Else +**Action**: REPLACE WITH NOTES + +### Git and Mercurial (`client-hg.asc`, `import-hg.asc`) +**Original**: 520 lines combined | **Action**: REPLACE WITH 3-LINE NOTE +- "Mercurial is rarely used in design workflows. If you need to migrate from Mercurial, see the original Pro Git reference." + +### Git and Perforce (`client-p4.asc`, `import-p4.asc`) +**Original**: 773 lines combined | **Action**: REPLACE WITH 5-LINE NOTE +- "Perforce is used in some enterprise environments, particularly game studios and organizations with large binary assets. If your design assets are in Perforce, the migration approach is similar to SVN: assess size, plan LFS, map authors. See the original Pro Git reference for detailed instructions." + +### Custom Importer (`import-custom.asc`) +**Original**: 371 lines | **Action**: REPLACE WITH 5-LINE NOTE +- "If your team versioned designs as dated folders (`backup_2023_01_15/components.sketch`), Git's fast-import tool can convert that history into proper Git commits. This is a specialized task — see the original Pro Git reference or ask your engineering team for help." + +--- + +## Chapter Summary +**Action**: REWRITE + +### New +- "The QuickMock migration took a day. Three years of design evolution is now searchable alongside SketchSpark's history. The combined repo is 800MB with LFS. The team learned to plan migrations carefully — size audits, LFS configuration, and author mapping make the difference between a clean import and a bloated mess. In the next chapter, a near-disaster teaches the team why Git's internals matter." diff --git a/00-notes/10-git-internals/outline.md b/00-notes/10-git-internals/outline.md new file mode 100644 index 000000000..480321d61 --- /dev/null +++ b/00-notes/10-git-internals/outline.md @@ -0,0 +1,153 @@ +# Chapter 10: Git Internals — Section Outline + +> **Storyline phase**: Scale & Recovery +> **Characters**: Nora, Sam +> **Key event**: Sam force-resets `main` before launch; Nora recovers via reflog + +--- + +## Section: Plumbing and Porcelain (`plumbing-porcelain.asc`) +**Original**: 37 lines | **Action**: REWRITE + +### Rewrite +- Open with the incident: "Two days before SketchSpark's v1.0 launch, Sam accidentally runs `git reset --hard HEAD~3` on `main`. Three days of work disappear — Nora's release notes, Priya's final marketing illustrations, Kai's generation speed improvement." +- Then: "To understand why the work isn't actually gone, you need to understand how Git stores data. This chapter looks under the hood — not to teach you to build Git, but to give you confidence that your work is safe." +- Frame plumbing vs. porcelain: "Everything you've done so far — commit, push, merge — is porcelain. The plumbing underneath is what makes recovery possible." + +--- + +## Section: Git Objects (`objects.asc`) +**Original**: 437 lines | **Action**: REWRITE + TRIM HEAVILY + +### Keep +- Three object types: blob, tree, commit +- Concept of content-addressable storage +- How commits chain together + +### Rewrite +- Replace "content-addressable filesystem" with: "Every file version gets a unique fingerprint based on its exact content. If the same icon appears in two branches, Git stores it once." +- Replace `test.txt` examples with SketchSpark files: + - Blob = the contents of `product-brief.md` at a specific moment + - Tree = the `screens/results/` directory listing at a specific moment + - Commit = a snapshot of the entire project, plus who made it and why +- **Nora explains to Sam**: "When you committed those release notes, Git created objects for every file. When you reset `main`, Git didn't delete those objects — it just moved the `main` pointer to an older commit. The objects are still in the database." + +### Cut +- Ruby SHA-1 object creation walkthrough — zero design relevance +- Low-level `git cat-file` details — keep one example showing a commit object +- Manual tree creation with `git update-index` / `git write-tree` + +### Target +- ~150 lines (down from 437) + +--- + +## Section: Git References (`refs.asc`) +**Original**: 209 lines | **Action**: REWRITE + +### Keep +- Branches as pointers to commits +- HEAD as pointer to current branch +- Tags as permanent pointers +- Remote references + +### Rewrite +- "Branches are just labels pointing to commits — like sticky notes on a timeline. Moving them — even destructively — doesn't destroy the commits they pointed to." +- "When Sam ran `reset --hard`, he moved the `main` sticky note backward. The commits it used to point to are still there, just no longer reachable through `main`." +- Tags: "`v0.5-alpha` is a permanent label. Unlike branches, tags don't move. They're anchors in your project history." +- Simplify HEAD to: "HEAD is 'where you are now.' It usually points to a branch name, which points to a commit." + +--- + +## Section: Packfiles (`packfiles.asc`) +**Original**: 163 lines | **Action**: REWRITE + +### Rewrite +- Open: "Priya notices `git push` takes 90 seconds. The repo has grown — thousands of files across months of work." +- Explain: "Git packs similar objects together using delta compression. When Priya commits a slightly modified illustration, Git stores one complete version plus a compact diff — not two full copies." +- But: "Very large binary files (her 50MB PSDs) resist delta compression. That's why Git LFS exists — it stores large files outside the main object database." +- Simplify `git gc`: "Git does this automatically. You don't need to run it manually." +- Replace `repo.rb` example with `design-tokens.json` and `illustrations/onboarding/step-1.png` + +--- + +## Section: Maintenance and Data Recovery (`maintenance.asc`) +**Original**: 353 lines | **Action**: REWRITE — THIS IS THE CHAPTER'S CLIMAX + +### Keep +- Reflog walkthrough +- `git fsck` for deeper recovery +- Auto-gc concept + +### Rewrite +- **Reflog recovery** — the centerpiece: + ``` + git reflog + ``` + Nora sees every position HEAD has been in. Three entries up: the commit before Sam's reset. + ``` + git branch recovery a1b2c3d + git checkout recovery + git log --oneline -5 + ``` + All three commits are there. Merge recovery into main. +- Frame: "Git's reflog keeps a record of every label movement for at least 30 days. Even if Sam had deleted the branch, the reflog would still know where it pointed." +- **fsck**: "If the reflog is empty (rare — requires manual deletion), `git fsck --full` finds dangling commits. Create a branch from one to recover." +- **Large object removal**: Simplify to concept + alternatives: `.gitignore` prevention, Git LFS, `git filter-repo` for cleanup. Link to detailed reference. + +### New +- Add "Best Practices for Preventing Data Loss" sidebar: + 1. Commit frequently (committed work is safe; uncommitted isn't) + 2. Never use `--hard` on shared branches + 3. Push regularly (remote is a second backup) + 4. Use branch protection to prevent accidental force-pushes to `main` + +--- + +## Section: The Refspec (`refspec.asc`) +**Original**: 145 lines | **Action**: TRIM TO ~40 LINES + +### Keep +- Basic refspec concept +- Selective fetching + +### Rewrite +- "Refspecs define which branches you fetch. Useful if your project has 20 branches and you only need `main` and `feature/screens`." +- One example, then link to reference for details + +### Cut +- Pushing refspecs detail +- Deleting references via refspec + +--- + +## Section: Transfer Protocols (`transfer-protocols.asc`) +**Original**: 292 lines | **Action**: TRIM TO ~30 LINES + +### Rewrite +- Replace protocol mechanics with practical troubleshooting: + - "Why does `git clone` fail?" → check URL, SSH keys, network + - "Why does push hang?" → large files, network timeout + - "SSH vs. HTTPS?" → SSH for regular contributors, HTTPS for occasional +- Add: "Most designers can skip this section. Return here if you're troubleshooting a connection problem." + +--- + +## Section: Environment Variables (`environment.asc`) +**Original**: 237 lines | **Action**: TRIM TO ~30 LINES + +### Keep +- `GIT_EDITOR` (which editor opens for commit messages) +- `GIT_TRACE` (debugging — "my clone/push hangs") +- `GIT_SSH_COMMAND` (custom SSH key) + +### Cut +- Everything else — pathspecs, advanced networking, internal variables + +--- + +## Chapter Summary +**Action**: REWRITE + +### New +- "Sam's mistake and Nora's recovery bookend the journey. In Chapter 1, Nora lost work because she *didn't* use version control. In Chapter 10, Sam nearly lost work despite using it — but Git's design made recovery straightforward. The reflog, immutable objects, and reference labels form a safety net that protects months of research, design, and configuration. Your work is never truly lost." diff --git a/00-notes/A-git-in-other-environments/outline.md b/00-notes/A-git-in-other-environments/outline.md new file mode 100644 index 000000000..73ee9020d --- /dev/null +++ b/00-notes/A-git-in-other-environments/outline.md @@ -0,0 +1,92 @@ +# Appendix A: Git in Other Environments — Section Outline + +> **Storyline phase**: Tooling Choices +> **Characters**: Nora (CLI), Sam (VS Code), Priya (GitHub Desktop), Kai (JetBrains) +> **Key event**: Team never agreed on one tool — each uses what fits their workflow + +--- + +## Structural Change: Add Decision Tree Opening + +### New Section: "Choosing Your Git Interface" +Add at the start (~20 lines): +- "There is no single best Git tool. Each SketchSpark team member uses something different." +- Decision tree: + - "I mainly write text files (research, docs, tokens)" → CLI or VS Code + - "I work with lots of image files and large binaries" → GitHub Desktop + - "I write code alongside design work" → VS Code or JetBrains + - "I want the simplest possible interface" → GitHub Desktop + - "I want maximum control" → CLI +- "No choice is wrong. The best Git tool is the one you'll actually use." + +--- + +## Section: Graphical Interfaces (`guis.asc`) +**Original**: 151 lines | **Action**: REWRITE + +### Keep +- gitk and git-gui mention (for reference) +- Third-party client overview concept + +### Rewrite +- Lead with the three tools the team actually uses: GitHub Desktop, VS Code Git panel, GitKraken +- Add: "When to use Git vs. cloud design tools" — Figma's version history handles Figma files; Git handles everything else (tokens, docs, research, exports, configs) +- Add `.gitignore` reminder: "GUI tools still require `.gitignore` — they just provide a friendlier way to stage and commit." +- Replace generic client list with curated recommendations for designers + +--- + +## Section: Visual Studio Code (`visualstudiocode.asc`) +**Original**: 22 lines | **Action**: EXPAND + +### Rewrite +- Expand to ~50 lines — VS Code is Sam's primary tool +- "Sam edits `design-tokens.json` and `user-flows.md` with inline gutter indicators showing what changed since last commit." +- Highlight: Source Control panel, inline diff, staging individual hunks via UI, GitHub PR extension for reviewing Marcus's contributions +- Add: "VS Code's Git integration covers 90% of daily design workflow. You'll need the CLI for advanced operations (rebase, bisect, reflog)." +- Note limitation: "Binary files (PNGs, Figma exports) show as 'changed' but can't display visual diffs in VS Code." + +--- + +## Section: JetBrains IDEs (`jetbrainsides.asc`) +**Original**: 11 lines | **Action**: LIGHT EXPAND + +### Rewrite +- Frame for Kai: "WebStorm integrates Git into the development workflow — commit, push, merge conflicts, and log are accessible without leaving the editor." +- Add: Version Control ToolWindow, three-pane merge conflict resolution +- ~20 lines (up from 11) + +--- + +## Section: Sublime Text (`sublimetext.asc`) +**Original**: 16 lines | **Action**: KEEP, ADD NOTE + +### Add +- "If you use Sublime Text, its Git integration is solid. For most designers, VS Code or GitHub Desktop will be more intuitive." + +--- + +## Sections: Shell Configuration (Bash, Zsh, PowerShell) +**Original**: 184 lines combined | **Action**: TRIM + +### Bash (`bash.asc`, 43 lines) → TRIM TO ~20 LINES +- Keep: prompt showing current branch (safety check — "prevents committing to wrong branch") +- Cut: detailed `\w`, `\$` syntax — link to reference + +### Zsh (`zsh.asc`, 55 lines) → TRIM TO ~25 LINES +- Note: Zsh is macOS default post-Catalina +- Recommend oh-my-zsh as beginner-friendly path +- Cut: manual `vcs_info` configuration detail + +### PowerShell (`powershell.asc`, 86 lines) → TRIM TO ~30 LINES +- Simplify posh-git installation to single command +- Cut: ExecutionPolicy scope explanation +- Add: "For Windows designers who prefer a visual tool, GitHub Desktop is a simpler alternative." + +--- + +## Appendix Summary +**Action**: ADD + +### New +- "The right tool depends on your role and comfort level. Nora's CLI mastery, Sam's VS Code workflow, Priya's GitHub Desktop staging, and Kai's JetBrains integration all accomplish the same thing — they just match different working styles. Start with whatever feels least intimidating and expand from there." diff --git a/00-notes/B-embedding-git/outline.md b/00-notes/B-embedding-git/outline.md new file mode 100644 index 000000000..7e0438f75 --- /dev/null +++ b/00-notes/B-embedding-git/outline.md @@ -0,0 +1,106 @@ +# Appendix B: Embedding Git in Your Applications — Section Outline + +> **Storyline phase**: Tool Integration +> **Characters**: Kai, Priya, Nora +> **Key event**: SketchSpark uses libgit2 internally; Priya automates exports with Dulwich + +--- + +## Structural Change: Reframe Entirely + +Replace "how to code Git integration" with "where Git integration appears in design tools and how it affects UX." + +### New Introduction (~15 lines) +> "This appendix is relevant in two scenarios: (1) you're designing applications that integrate version control, or (2) you want to understand how your design tools use Git under the hood. You don't need to write code — this is about understanding the landscape." + +### New Section Order +1. Overview: "Where Git Integration Appears in Design Tools" (NEW) +2. Libgit2 → "The Library Behind Your Tools" +3. Dulwich → "Git Automation with Python" +4. Command-Line Git → "When Tools Shell Out to Git" +5. JGit & go-git → consolidated as "Other Libraries" (brief) + +--- + +## New Section: Where Git Integration Appears +**Action**: NEW (~40 lines) + +- GitHub Desktop, GitKraken, Sublime Merge — all built on libgit2 +- Figma plugins that export to Git — use Dulwich or command-line Git +- CI/CD systems (GitHub Actions) — use command-line Git +- SketchSpark itself: Kai explains that the generation pipeline uses libgit2 to create each of the 5 generated options as a lightweight branch in a temporary repo. "The product's architecture mirrors Git's branching model — you've been using Git concepts through the UI all along." + +--- + +## Section: Libgit2 (`libgit2.asc`) +**Original**: 237 lines | **Action**: REWRITE + TRIM + +### Keep +- What libgit2 is and what it powers +- Language bindings concept (Rugged/Ruby, LibGit2Sharp/C#) +- Basic usage example + +### Rewrite +- Lead with: "Libgit2 powers GitHub Desktop, GitKraken, and Sublime Merge — the GUI tools designers actually use." +- After code example, add: "In a design tool, users never see this code. They click 'Save Version' and libgit2 creates the commit." +- Frame bindings as: "Available in every language — Ruby, Python, C#, JavaScript. If your engineering team builds internal tools, they likely use one of these." + +### Cut +- Advanced ODB backends +- Detailed binding installation instructions + +### Target +- ~80 lines (down from 237) + +--- + +## Section: Dulwich (`dulwich.asc`) +**Original**: 42 lines | **Action**: EXPAND + +### Keep +- What Dulwich is (pure Python Git) + +### Rewrite +- Frame as most designer-relevant: "Python is widely used in design automation — Figma plugins, token generation scripts, SVG optimization pipelines." +- **Priya's export script**: She wants to auto-commit illustrations whenever she exports from her design tool: + ```python + from dulwich.repo import Repo + repo = Repo(".") + repo.stage(["illustrations/onboarding/step-1-upload.png"]) + repo.do_commit(b"Auto-export: updated onboarding illustration step 1") + ``` + "Ten lines of code. Now her workflow is: export from design tool → script commits automatically → she opens a PR when the batch is ready." +- Add: "Common in: Figma plugins, design token scripts, CI/CD automation, export pipelines." + +### Target +- ~50 lines (up from 42) + +--- + +## Section: Command-Line Git (`command-line.asc`) +**Original**: 16 lines | **Action**: REWRITE + +### Rewrite +- Replace technical constraints (text parsing, process management) with UX design patterns: + - "If you're designing an application that integrates Git, users expect: version history, save/commit, undo, branch/explore, and sync/share." + - Reference existing UX patterns: GitHub Desktop's commit list, VS Code's gutter indicators, GitKraken's visual graph +- **Nora's exercise**: She sketches a "version history" panel for SketchSpark — translating Git concepts into a visual interface for non-technical designers + +--- + +## Sections: JGit and go-git +**Original**: 243 lines combined | **Action**: CONSOLIDATE + TRIM + +### Rewrite +- Combine into single "Other Libraries" section (~30 lines) +- JGit: "Java — powers Eclipse and some CI tools" +- go-git: "Go — powers CLI tools and some design token generators" +- Add: "For most design-adjacent work, Dulwich (Python) or libgit2 (multi-language) are more relevant." + +--- + +## Appendix Summary +**Action**: ADD + +### New +- "The tools you use every day — GitHub Desktop, VS Code, Figma plugins — are built on these libraries. Understanding that they exist demystifies how those tools work and opens the door to simple automation, like Priya's export script. You don't need to become a programmer — you just need to know what's possible." diff --git a/00-notes/C-git-commands/outline.md b/00-notes/C-git-commands/outline.md new file mode 100644 index 000000000..55c4487a4 --- /dev/null +++ b/00-notes/C-git-commands/outline.md @@ -0,0 +1,96 @@ +# Appendix C: Git Commands — Section Outline + +> **Storyline phase**: Reference +> **Characters**: All (referenced by chapter) +> **Key event**: Workflow-based reorganization of command reference + +--- + +## Structural Change: Reorganize by Workflow + +Replace the current taxonomy-based organization (Setup, Snapshotting, Branching, Sharing, Inspection, Debugging, Patching, Email, External, Admin, Plumbing) with workflow-based grouping that mirrors how the SketchSpark team actually uses Git. + +--- + +## New Structure + +### 1. Starting a Project (~30 lines) +- `git init` — Create a new repository (Nora, Ch2) +- `git clone` — Copy an existing repository (Sam joining, Ch3) +- `git config` — Set your name, email, editor, commit template (Ch1, Ch8) + +### 2. Daily Design Work (~60 lines) +- `git status` — What's changed since my last commit? +- `git add` — Select files to include in the next commit +- `git add -p` — Select specific changes within a file (Nora, Ch7) +- `git commit` — Save a checkpoint with a message +- `git diff` — What exactly changed? (text files: detailed; binary: limited) +- `git stash` — Set aside work-in-progress temporarily (Sam, Ch7) +- `git rm` — Remove a file from tracking +- `git mv` — Rename or move a tracked file + +### 3. Exploring & Branching (~50 lines) +- `git branch` — List, create, or delete branches +- `git checkout` / `git switch` — Move to a different branch +- `git merge` — Combine one branch into another +- `git rebase` — Replay commits onto a different base (Sam, Ch3) +- `git cherry-pick` — Copy a single commit to another branch (Ch5) + +### 4. Collaborating (~50 lines) +- `git remote` — Manage connections to shared repositories +- `git push` — Send your commits to the shared repository +- `git pull` — Download and merge teammates' changes +- `git fetch` — Download without merging (check first, merge later) +- `git submodule` — Manage nested repositories (Kai's pipeline, Ch7) + +### 5. Reviewing History (~40 lines) +- `git log` — See commit history (use `--oneline --graph` for visual overview) +- `git log -S "keyword"` — Find when a specific term was added or removed +- `git show` — Display a specific commit's contents +- `git blame` — Find who last changed each line (Priya, Ch7) +- `git diff` (between branches) — Compare two branches side by side + +### 6. Shipping a Release (~25 lines) +- `git tag` — Mark a commit as a release (v0.1-concept, v0.5-alpha, v1.0) +- `git archive` — Create a distributable zip/tar without Git history +- `git describe` — Generate a version string from the nearest tag + +### 7. Fixing Mistakes (~40 lines) +- `git restore` — Discard uncommitted changes to a file +- `git restore --staged` — Unstage a file without losing changes +- `git reset --soft HEAD~1` — Undo the last commit, keep changes staged (Sam, Ch7) +- `git reset --mixed HEAD~1` — Undo the last commit, unstage changes +- `git revert` — Create a new commit that undoes a previous commit (safe for shared branches) +- `git reflog` — Find lost commits after a destructive operation (Nora, Ch10) +- `git clean` — Remove untracked files (caution: irreversible) + +### 8. Managing Large Files (~15 lines) +- `git lfs install` — Enable Git LFS in a repository +- `git lfs track "*.psd"` — Track large files with LFS +- `git lfs migrate` — Move existing large files to LFS storage +- Note: "Essential for design projects with illustrations, PSDs, or high-res exports >10MB." + +--- + +## Sections to Cut + +| Original Section | Lines | Action | +|-----------------|-------|--------| +| Email (am, apply, format-patch, send-email, request-pull, imap-send) | ~48 | DELETE — "Modern teams use GitHub/GitLab Pull Requests. See Chapter 6." | +| External Systems (svn, fast-import) | ~16 | DELETE — "See Chapter 9 if migrating from SVN." | +| Plumbing (ls-files, ls-remote, rev-parse) | ~12 | DELETE — "For advanced internals, see Chapter 10." | +| Administration (filter-branch, fsck, reflog, gc) | ~20 | MOVE reflog to "Fixing Mistakes"; delete rest or link to Ch10 | + +## Format Changes + +- Each command includes: 1-line description + chapter reference where it appears in the storyline +- Commands link back to their chapter so readers can revisit the full context +- Add relevance indicator: **Essential** (use daily), **Important** (use weekly), **Advanced** (use occasionally) + +--- + +## Estimated Impact +- Cut ~80 lines of irrelevant content (email, external, plumbing) +- Add ~15 lines (LFS section) +- Reorganize remaining ~350 lines into workflow groups +- Net: ~285 lines, significantly more navigable From 12e6080e2e95778309a06816014f9ad0a84cf976 Mon Sep 17 00:00:00 2001 From: Claude <noreply@anthropic.com> Date: Sun, 5 Apr 2026 01:32:11 +0000 Subject: [PATCH 14/17] Move initial revision notes to archive directory with README Pre-storyline analysis files relocated from per-chapter directories to 00-notes/initial-revision-notes/. README explains their context, why they were superseded, and their relationship to the current outline.md files. https://claude.ai/code/session_011MhF8iWLG3rS5jturtiTZ5 --- .../01-introduction.md} | 0 .../02-git-basics.md} | 0 .../03-git-branching.md} | 0 .../04-git-server.md} | 0 .../05-distributed-git.md} | 0 .../06-github.md} | 0 .../07-git-tools.md} | 0 .../08-customizing-git.md} | 0 .../09-git-and-other-scms.md} | 0 .../10-git-internals.md} | 0 .../A-git-in-other-environments.md} | 0 .../B-embedding-git.md} | 0 .../C-git-commands.md} | 0 00-notes/initial-revision-notes/README.md | 41 +++++++++++++++++++ 14 files changed, 41 insertions(+) rename 00-notes/{01-introduction/ux-designer-revision-notes.md => initial-revision-notes/01-introduction.md} (100%) rename 00-notes/{02-git-basics/ux-designer-revision-notes.md => initial-revision-notes/02-git-basics.md} (100%) rename 00-notes/{03-git-branching/ux-designer-revision-notes.md => initial-revision-notes/03-git-branching.md} (100%) rename 00-notes/{04-git-server/ux-designer-revision-notes.md => initial-revision-notes/04-git-server.md} (100%) rename 00-notes/{05-distributed-git/ux-designer-revision-notes.md => initial-revision-notes/05-distributed-git.md} (100%) rename 00-notes/{06-github/ux-designer-revision-notes.md => initial-revision-notes/06-github.md} (100%) rename 00-notes/{07-git-tools/ux-designer-revision-notes.md => initial-revision-notes/07-git-tools.md} (100%) rename 00-notes/{08-customizing-git/ux-designer-revision-notes.md => initial-revision-notes/08-customizing-git.md} (100%) rename 00-notes/{09-git-and-other-scms/ux-designer-revision-notes.md => initial-revision-notes/09-git-and-other-scms.md} (100%) rename 00-notes/{10-git-internals/ux-designer-revision-notes.md => initial-revision-notes/10-git-internals.md} (100%) rename 00-notes/{A-git-in-other-environments/ux-designer-revision-notes.md => initial-revision-notes/A-git-in-other-environments.md} (100%) rename 00-notes/{B-embedding-git/ux-designer-revision-notes.md => initial-revision-notes/B-embedding-git.md} (100%) rename 00-notes/{C-git-commands/ux-designer-revision-notes.md => initial-revision-notes/C-git-commands.md} (100%) create mode 100644 00-notes/initial-revision-notes/README.md diff --git a/00-notes/01-introduction/ux-designer-revision-notes.md b/00-notes/initial-revision-notes/01-introduction.md similarity index 100% rename from 00-notes/01-introduction/ux-designer-revision-notes.md rename to 00-notes/initial-revision-notes/01-introduction.md diff --git a/00-notes/02-git-basics/ux-designer-revision-notes.md b/00-notes/initial-revision-notes/02-git-basics.md similarity index 100% rename from 00-notes/02-git-basics/ux-designer-revision-notes.md rename to 00-notes/initial-revision-notes/02-git-basics.md diff --git a/00-notes/03-git-branching/ux-designer-revision-notes.md b/00-notes/initial-revision-notes/03-git-branching.md similarity index 100% rename from 00-notes/03-git-branching/ux-designer-revision-notes.md rename to 00-notes/initial-revision-notes/03-git-branching.md diff --git a/00-notes/04-git-server/ux-designer-revision-notes.md b/00-notes/initial-revision-notes/04-git-server.md similarity index 100% rename from 00-notes/04-git-server/ux-designer-revision-notes.md rename to 00-notes/initial-revision-notes/04-git-server.md diff --git a/00-notes/05-distributed-git/ux-designer-revision-notes.md b/00-notes/initial-revision-notes/05-distributed-git.md similarity index 100% rename from 00-notes/05-distributed-git/ux-designer-revision-notes.md rename to 00-notes/initial-revision-notes/05-distributed-git.md diff --git a/00-notes/06-github/ux-designer-revision-notes.md b/00-notes/initial-revision-notes/06-github.md similarity index 100% rename from 00-notes/06-github/ux-designer-revision-notes.md rename to 00-notes/initial-revision-notes/06-github.md diff --git a/00-notes/07-git-tools/ux-designer-revision-notes.md b/00-notes/initial-revision-notes/07-git-tools.md similarity index 100% rename from 00-notes/07-git-tools/ux-designer-revision-notes.md rename to 00-notes/initial-revision-notes/07-git-tools.md diff --git a/00-notes/08-customizing-git/ux-designer-revision-notes.md b/00-notes/initial-revision-notes/08-customizing-git.md similarity index 100% rename from 00-notes/08-customizing-git/ux-designer-revision-notes.md rename to 00-notes/initial-revision-notes/08-customizing-git.md diff --git a/00-notes/09-git-and-other-scms/ux-designer-revision-notes.md b/00-notes/initial-revision-notes/09-git-and-other-scms.md similarity index 100% rename from 00-notes/09-git-and-other-scms/ux-designer-revision-notes.md rename to 00-notes/initial-revision-notes/09-git-and-other-scms.md diff --git a/00-notes/10-git-internals/ux-designer-revision-notes.md b/00-notes/initial-revision-notes/10-git-internals.md similarity index 100% rename from 00-notes/10-git-internals/ux-designer-revision-notes.md rename to 00-notes/initial-revision-notes/10-git-internals.md diff --git a/00-notes/A-git-in-other-environments/ux-designer-revision-notes.md b/00-notes/initial-revision-notes/A-git-in-other-environments.md similarity index 100% rename from 00-notes/A-git-in-other-environments/ux-designer-revision-notes.md rename to 00-notes/initial-revision-notes/A-git-in-other-environments.md diff --git a/00-notes/B-embedding-git/ux-designer-revision-notes.md b/00-notes/initial-revision-notes/B-embedding-git.md similarity index 100% rename from 00-notes/B-embedding-git/ux-designer-revision-notes.md rename to 00-notes/initial-revision-notes/B-embedding-git.md diff --git a/00-notes/C-git-commands/ux-designer-revision-notes.md b/00-notes/initial-revision-notes/C-git-commands.md similarity index 100% rename from 00-notes/C-git-commands/ux-designer-revision-notes.md rename to 00-notes/initial-revision-notes/C-git-commands.md diff --git a/00-notes/initial-revision-notes/README.md b/00-notes/initial-revision-notes/README.md new file mode 100644 index 000000000..19ef39e2d --- /dev/null +++ b/00-notes/initial-revision-notes/README.md @@ -0,0 +1,41 @@ +# Initial Revision Notes + +These 13 files are the first-pass analysis of how each Pro Git chapter could be adapted for UX designers learning Git. They were generated by deploying parallel agents to read the original AsciiDoc source files and the walkthrough catalogs, then compiling recommendations per chapter. + +## Context + +- **Created**: Early in the project, before the SketchSpark product storyline existed +- **Purpose**: Identify what resonates, what confuses, and what's missing for a UX designer audience in each chapter +- **Scope**: Section-by-section priority ratings, design tool analogies (Figma, Sketch, Adobe XD), content gaps, and structural recommendations + +## Why They Were Superseded + +These notes recommend generic design adaptations — "replace with design system example," "add Figma analogy," "use design token scenario" — without a unifying product, team, or narrative thread. They are useful as raw analysis but don't specify *which* product, *which* characters, or *which* artifacts to use. + +The project subsequently developed: + +1. **`storyline.md`** — A complete narrative following "SketchSpark" (an AI-powered rapid prototyping tool) from research through launch, with four named characters and a defined repository structure +2. **`storyline-analysis.md`** — A mapping of how the storyline applies to each chapter's revision recommendations +3. **Per-chapter `outline.md` files** — Section-by-section outlines specifying what stays, what's rewritten, and what's new, using SketchSpark examples throughout + +## Files + +| File | Original Location | Content | +|------|-------------------|---------| +| `01-introduction.md` | `00-notes/01-introduction/` | Version control concepts, Git fundamentals, installation | +| `02-git-basics.md` | `00-notes/02-git-basics/` | Daily workflow: init, clone, status, add, commit, diff, log | +| `03-git-branching.md` | `00-notes/03-git-branching/` | Branching, merging, rebasing, remote branches | +| `04-git-server.md` | `00-notes/04-git-server/` | Hosting, protocols, SSH, GitLab | +| `05-distributed-git.md` | `00-notes/05-distributed-git/` | Workflows, contributing, maintaining projects | +| `06-github.md` | `00-notes/06-github/` | Account setup, PRs, organizations, scripting | +| `07-git-tools.md` | `00-notes/07-git-tools/` | Stashing, reset, submodules, searching, debugging | +| `08-customizing-git.md` | `00-notes/08-customizing-git/` | Configuration, attributes, hooks, policy | +| `09-git-and-other-scms.md` | `00-notes/09-git-and-other-scms/` | SVN/Mercurial/Perforce bridges and migration | +| `10-git-internals.md` | `00-notes/10-git-internals/` | Objects, references, packfiles, recovery | +| `A-git-in-other-environments.md` | `00-notes/A-git-in-other-environments/` | GUIs, IDEs, shell configuration | +| `B-embedding-git.md` | `00-notes/B-embedding-git/` | Libgit2, JGit, Dulwich, go-git | +| `C-git-commands.md` | `00-notes/C-git-commands/` | Command reference reorganization | + +## Status + +**Archived.** These files are retained as historical context. The per-chapter `outline.md` files are the current working documents for the adaptation. From 4d3464c84b8dbc1c9382068a46bfea7e494cd097 Mon Sep 17 00:00:00 2001 From: Claude <noreply@anthropic.com> Date: Sun, 5 Apr 2026 01:43:56 +0000 Subject: [PATCH 15/17] Add full SketchSpark product specification Defines the product concept, core interaction model, screen inventory, AI generation pipeline, prompt templates, design tokens, user roles, technical stack, milestones, and competitive landscape. https://claude.ai/code/session_011MhF8iWLG3rS5jturtiTZ5 --- 00-notes/sketchspark-product-spec.md | 298 +++++++++++++++++++++++++++ 1 file changed, 298 insertions(+) create mode 100644 00-notes/sketchspark-product-spec.md diff --git a/00-notes/sketchspark-product-spec.md b/00-notes/sketchspark-product-spec.md new file mode 100644 index 000000000..075d9a515 --- /dev/null +++ b/00-notes/sketchspark-product-spec.md @@ -0,0 +1,298 @@ +# SketchSpark — Product Specification + +## What Is SketchSpark? + +SketchSpark is an AI-powered rapid prototyping application that turns rough sketches into polished UI designs. A designer provides a single input — a napkin wireframe, a whiteboard photo, a tablet drawing, or a simple digital sketch — and SketchSpark generates up to five distinct, high-fidelity UI options in parallel. The designer reviews, compares, selects a direction, and refines it iteratively until the design is ready for development handoff. + +--- + +## The Problem + +The gap between idea and testable prototype is the slowest part of the design process. A designer has a concept — maybe sketched on paper during a meeting, maybe roughed out on a tablet on the train home — and turning that into something a team can evaluate takes hours or days. Wireframing tools require manual construction of every element. High-fidelity mockup tools demand pixel-level precision before anything looks real enough to test. + +Meanwhile, the best design decisions come from comparing options. Research consistently shows that teams who evaluate multiple directions produce stronger outcomes than teams who refine a single idea. But generating multiple polished directions multiplies the time cost — so in practice, most teams explore one direction and hope it's the right one. + +SketchSpark eliminates this tradeoff. + +--- + +## Core Interaction Model + +### Input +The designer provides a rough sketch through one of three input methods: + +1. **Upload**: Photograph of a hand-drawn sketch (napkin, whiteboard, notebook), uploaded as JPEG or PNG +2. **Draw**: Freehand sketch drawn directly in the SketchSpark canvas using a mouse, trackpad, or stylus +3. **Import**: Existing low-fidelity wireframe imported from Figma, Sketch, or as SVG/PNG + +The sketch does not need to be precise. SketchSpark interprets intent: a rectangle becomes a card, a circle becomes an avatar, a squiggle with lines becomes a text block, an arrow becomes navigation. The AI model is trained to read rough spatial relationships and structural patterns, not pixel-perfect drawings. + +### Processing +SketchSpark analyzes the sketch and generates up to five UI interpretations simultaneously. Each option: + +- Applies a different layout strategy (grid, list, asymmetric, card-based, editorial) +- Respects the spatial relationships in the original sketch +- Uses the project's design tokens (colors, typography, spacing) if configured +- Follows platform conventions (iOS, Android, or web) based on project settings +- Meets WCAG AA accessibility standards by default (contrast, touch targets, font sizes) + +Generation takes 15–45 seconds depending on sketch complexity and selected platform. + +### Output +The results screen presents all generated options in a side-by-side comparison view. For each option, the designer sees: + +- A full-fidelity screen mockup at the target resolution +- A confidence score (how closely the option matches the sketch's intent) +- Layout strategy label (e.g., "Card Grid," "Editorial Stack," "Split Panel") +- Quick annotations highlighting key interpretation decisions + +The designer can: + +- **Select** an option to use as the starting point for refinement +- **Compare** two options in an overlay diff view (superimposed at 50% opacity) +- **Regenerate** a single option with adjusted parameters (e.g., "more whitespace," "larger typography") +- **Refine** the selected option in an integrated editor with AI-assisted adjustments +- **Export** any option as Figma file, SVG, PNG, or development-ready code (HTML/CSS or React components) + +### Iteration +After selecting a direction, the designer enters the refinement loop: + +1. Adjust the selected design (move elements, change hierarchy, update content) +2. Ask SketchSpark to regenerate variations of the adjusted design +3. Compare, select, adjust again +4. Repeat until satisfied + +Each iteration takes seconds, not hours. The designer maintains creative control — SketchSpark generates options, the designer makes decisions. + +--- + +## Product Architecture + +### Core Screens + +| Screen | Purpose | Key Interactions | +|--------|---------|------------------| +| **Home / Dashboard** | Project list, recent sketches, quick-start | Create new project, open recent, view history | +| **Sketch Input** | Upload, draw, or import the source sketch | Drag-and-drop upload, freehand canvas, file picker, Figma import | +| **Generation Progress** | Loading state during AI processing | Progress indicator, cancel button, "What's happening" explainer | +| **Results Comparison** | Side-by-side view of 5 generated options | Select, compare overlay, regenerate single, expand detail | +| **Refinement Editor** | Edit selected option with AI assistance | Direct manipulation, AI regeneration of subsections, token application | +| **Export** | Output to design tools or development formats | Figma, Sketch, SVG, PNG, HTML/CSS, React components | +| **History** | Version timeline of all generations and refinements | Browse, restore, branch from any point | +| **Settings** | Project configuration | Platform target, design tokens, team preferences, API keys | +| **Onboarding** | First-run experience for new users | 3-step tutorial: upload → generate → refine | + +### Platform Targets +SketchSpark generates designs for three platforms: + +- **Web** (responsive: desktop 1440px, tablet 768px, mobile 375px) +- **iOS** (iPhone 15 Pro, iPad Pro) +- **Android** (Pixel 8, Galaxy Tab) + +Platform selection affects layout conventions, navigation patterns, typography scales, and touch target sizes. A single sketch can generate options for multiple platforms simultaneously. + +### Design Token Integration +Projects can define design tokens (via `design-tokens.json`) that constrain generation: + +```json +{ + "colors": { + "primary": "#2563EB", + "secondary": "#7C3AED", + "surface": "#FFFFFF", + "on-surface": "#1E293B", + "error": "#DC2626", + "success": "#16A34A" + }, + "typography": { + "heading-1": { "family": "Inter", "weight": 700, "size": "32px", "line-height": 1.2 }, + "heading-2": { "family": "Inter", "weight": 600, "size": "24px", "line-height": 1.3 }, + "body": { "family": "Inter", "weight": 400, "size": "16px", "line-height": 1.5 }, + "caption": { "family": "Inter", "weight": 400, "size": "12px", "line-height": 1.4 } + }, + "spacing": { + "xs": "4px", + "sm": "8px", + "md": "16px", + "lg": "24px", + "xl": "32px", + "2xl": "48px" + }, + "border-radius": { + "sm": "4px", + "md": "8px", + "lg": "16px", + "full": "9999px" + } +} +``` + +When tokens are configured, all generated options use them — ensuring brand consistency across every variation. When tokens are absent, SketchSpark applies sensible defaults. + +--- + +## AI Generation Pipeline + +### Sketch Interpretation +The input sketch passes through a vision model that identifies: + +- **Elements**: rectangles (cards, containers), circles (avatars, icons), lines (dividers, borders), text blocks, arrows (navigation, flow), images (placeholders) +- **Hierarchy**: relative size indicates importance; vertical position indicates reading order +- **Grouping**: proximity and alignment suggest related elements +- **Intent patterns**: recognized UI conventions (tab bar, header, list, form, modal) + +### Option Generation +Each of the five options is generated by the same base model with different layout strategy parameters: + +| Option | Strategy | Characteristics | +|--------|----------|-----------------| +| Option 1 | **Faithful** | Closest interpretation of the sketch's literal layout | +| Option 2 | **Grid** | Elements reorganized into a structured grid system | +| Option 3 | **Editorial** | Asymmetric, magazine-style layout with visual hierarchy emphasis | +| Option 4 | **Minimal** | Maximum whitespace, reduced elements, focus on core content | +| Option 5 | **Dense** | Information-rich, compact layout maximizing content density | + +The strategies are configurable. Teams can replace defaults or add custom strategies via prompt templates (`prompts/sketch-to-ui.txt`, `prompts/mobile-layout.txt`). + +### Prompt Templates +The generation pipeline uses text-based prompt templates that define how the model interprets and renders sketches: + +``` +# prompts/sketch-to-ui.txt +# Core generation prompt for SketchSpark + +## System Context +You are a UI design generator. Given a sketch analysis (element positions, +hierarchy, grouping, intent patterns), generate a high-fidelity UI mockup. + +## Constraints +- Apply design tokens if provided; use system defaults otherwise +- Meet WCAG AA contrast ratios (4.5:1 for body text, 3:1 for large text) +- Touch targets minimum 44x44px for mobile, 24x24px for web +- Respect platform conventions for navigation, typography, and spacing + +## Layout Strategy: {strategy_name} +{strategy_description} + +## Output +Render as structured layout definition with element positions, styles, +and content. Include accessibility labels for all interactive elements. +``` + +These templates are plain text files — fully version-controllable, diffable, and improvable via pull requests (as Marcus demonstrates in Chapter 6). + +### Accessibility +Every generated option includes: + +- WCAG AA contrast compliance (checked automatically, violations flagged) +- Semantic structure (headings, landmarks, reading order) +- Touch target sizing per platform guidelines +- Alt text suggestions for image placeholders +- Focus order and keyboard navigation hints + +An optional post-generation accessibility audit (`prompts/accessibility-check.txt`) runs a second pass and annotates the design with specific compliance notes. + +### Model Configuration +The AI model's behavior is controlled through `model-params.yaml`: + +```yaml +model: + version: "sketchspark-v3.2" + inference: + temperature: 0.7 # Higher = more creative variation between options + max_tokens: 8192 + timeout_seconds: 45 + generation: + num_options: 5 # 1-5 parallel options + min_confidence: 0.6 # Don't show options below this confidence + platform: "web" # web | ios | android + responsive_breakpoints: + - 1440 + - 768 + - 375 + quality: + accessibility_level: "AA" # AA | AAA + contrast_check: true + touch_target_check: true +``` + +This file is structured YAML — Git can diff it, hooks can validate it, and changes are traceable through commit history. + +--- + +## User Roles and Workflows + +### Solo Designer (Freelancer) +- Uploads client sketches, generates options, presents 3–5 directions to the client +- Uses SketchSpark to compress the "sketch to mockup" phase from 2 days to 2 hours +- Exports directly to Figma for final polish and handoff + +### Design Team (3–8 people) +- Shared project with design tokens enforcing brand consistency +- Multiple designers generate options for different screens simultaneously +- Results comparison view used in team critiques — "let's look at everyone's options for the checkout flow" +- History view tracks who generated what and which directions were chosen + +### Design-Engineering Handoff +- Selected designs export as development-ready code (HTML/CSS or React components) +- Design tokens ensure generated code uses the same spacing, colors, and typography as the design +- Engineers consume tokens from `design-tokens.json` in their build system +- Version history provides context: "why does this screen look this way?" → trace back to the original sketch and the option selection decision + +--- + +## Technical Stack (for repository context) + +| Layer | Technology | Repository Artifacts | +|-------|-----------|---------------------| +| Frontend | React + TypeScript | `src/` (not in design repo) | +| Design | Figma (source), PNG/SVG (exports) | `screens/`, `illustrations/`, `icons/` | +| AI Pipeline | Python + PyTorch | `pipeline/`, `model-params.yaml`, `prompts/` | +| Design Tokens | JSON (consumed by both design and engineering) | `design-tokens.json` | +| Documentation | Markdown | `docs/`, `product-brief.md`, `research/` | +| CI/CD | GitHub Actions | `.github/workflows/` | + +The design repository (the one tracked in the book's storyline) contains everything except the frontend source code. This is intentional — the repo is a designer's workspace, not an engineering monorepo. + +--- + +## Product Milestones (as referenced in the storyline) + +| Tag | Milestone | What's Working | +|-----|-----------|----------------| +| `v0.1-concept` | Concept approved | Product brief, personas, competitive analysis, initial user flows, wireframes | +| `v0.5-alpha` | Internal alpha | End-to-end pipeline: upload sketch → generate 5 options → view comparison. Single platform (web). Default tokens only. | +| `v0.8-beta` | Public beta | All three input methods. Web + iOS platforms. Design token integration. Export to Figma and PNG. Onboarding flow. GitHub public repo. | +| `v1.0` | Public launch | All platforms. Refinement editor. Code export. Accessibility audit. Team collaboration features. Mobile prompt improvements (Marcus's contribution). QuickMock migration complete. | + +--- + +## Competitive Landscape + +| Competitor | What It Does | How SketchSpark Differs | +|-----------|-------------|------------------------| +| **Figma** | Collaborative design tool | Figma is the canvas; SketchSpark is the idea accelerator. Exports *to* Figma. | +| **Uizard** | AI screen generation from text prompts | Text-to-UI vs. sketch-to-UI. SketchSpark preserves the designer's spatial intent. | +| **Galileo AI** | AI UI generation from text descriptions | Similar AI approach but text-driven. SketchSpark starts from visual input. | +| **Framer** | Design + publish tool with AI features | Framer focuses on shipping websites. SketchSpark focuses on the exploration phase. | +| **Midjourney / DALL-E** | General image generation | Produces images, not structured UI. Can't export to Figma or generate code. No accessibility checking. | + +SketchSpark's differentiator: **parallel options from spatial input**. The designer's sketch encodes intent that text prompts can't — relative sizing, spatial grouping, reading order. Five options from one sketch means the designer explores more of the solution space in less time than any competitor allows. + +--- + +## Why This Product Works as a Book Example + +SketchSpark is designed to serve double duty as a compelling product *and* an effective Git teaching vehicle: + +1. **Parallel generation mirrors branching.** Five options from one sketch is the same mental model as five branches from one commit. The product's core concept reinforces Git's most important feature. + +2. **Full design lifecycle.** Research → concept → exploration → build → beta → launch → scale. Every phase produces different artifact types (text, binary, structured config) that teach different Git workflows. + +3. **Mixed file types.** Research briefs (merge-friendly markdown), screen mockups (binary Figma exports), AI prompts (diffable text), illustrations (large binary PNGs), tokens (structured JSON). This variety naturally teaches Git's strengths and limitations. + +4. **Team growth.** Solo (Ch1–2) → pair (Ch3) → small team (Ch5) → open source (Ch6). Each growth stage demands the exact Git workflow that chapter teaches. + +5. **AI pipeline.** Model configs, prompt templates, and training manifests are text files that benefit from version control, validation hooks, and code review — making chapters on hooks, attributes, and collaboration feel immediately relevant rather than abstract. + +6. **Real product decisions.** "Should we use card layout or list layout?" is a design decision readers can visualize. It's more engaging than "should we use tabs or spaces?" — and it naturally becomes a branch, a PR, and a merge. From 4205beb18d5f36f8f9a7ed06d833a9e26e99cf3c Mon Sep 17 00:00:00 2001 From: Claude <noreply@anthropic.com> Date: Wed, 8 Apr 2026 11:46:39 +0000 Subject: [PATCH 16/17] Move ToC files into chapter directories; remove obsolete storyline files - 13 toc-*.md files moved from 00-notes/ root into their respective chapter directories as toc.md - Removed storyline-analysis.md (superseded by per-chapter outlines) - Removed storyline-rewrite-task.md (completed task doc) https://claude.ai/code/session_011MhF8iWLG3rS5jturtiTZ5 --- .../toc.md} | 0 .../toc.md} | 0 .../toc.md} | 0 .../toc.md} | 0 .../toc.md} | 0 .../{toc-ch06-github.md => 06-github/toc.md} | 0 .../toc.md} | 0 .../toc.md} | 0 .../toc.md} | 0 .../toc.md} | 0 .../toc.md} | 0 .../toc.md} | 0 .../toc.md} | 0 00-notes/storyline-analysis.md | 258 ------------------ 00-notes/storyline-rewrite-task.md | 29 -- 15 files changed, 287 deletions(-) rename 00-notes/{toc-ch01-getting-started.md => 01-introduction/toc.md} (100%) rename 00-notes/{toc-ch02-git-basics.md => 02-git-basics/toc.md} (100%) rename 00-notes/{toc-ch03-git-branching.md => 03-git-branching/toc.md} (100%) rename 00-notes/{toc-ch04-git-on-the-server.md => 04-git-server/toc.md} (100%) rename 00-notes/{toc-ch05-distributed-git.md => 05-distributed-git/toc.md} (100%) rename 00-notes/{toc-ch06-github.md => 06-github/toc.md} (100%) rename 00-notes/{toc-ch07-git-tools.md => 07-git-tools/toc.md} (100%) rename 00-notes/{toc-ch08-customizing-git.md => 08-customizing-git/toc.md} (100%) rename 00-notes/{toc-ch09-git-and-other-systems.md => 09-git-and-other-scms/toc.md} (100%) rename 00-notes/{toc-ch10-git-internals.md => 10-git-internals/toc.md} (100%) rename 00-notes/{toc-appendix-a-git-in-other-environments.md => A-git-in-other-environments/toc.md} (100%) rename 00-notes/{toc-appendix-b-embedding-git.md => B-embedding-git/toc.md} (100%) rename 00-notes/{toc-appendix-c-git-commands.md => C-git-commands/toc.md} (100%) delete mode 100644 00-notes/storyline-analysis.md delete mode 100644 00-notes/storyline-rewrite-task.md diff --git a/00-notes/toc-ch01-getting-started.md b/00-notes/01-introduction/toc.md similarity index 100% rename from 00-notes/toc-ch01-getting-started.md rename to 00-notes/01-introduction/toc.md diff --git a/00-notes/toc-ch02-git-basics.md b/00-notes/02-git-basics/toc.md similarity index 100% rename from 00-notes/toc-ch02-git-basics.md rename to 00-notes/02-git-basics/toc.md diff --git a/00-notes/toc-ch03-git-branching.md b/00-notes/03-git-branching/toc.md similarity index 100% rename from 00-notes/toc-ch03-git-branching.md rename to 00-notes/03-git-branching/toc.md diff --git a/00-notes/toc-ch04-git-on-the-server.md b/00-notes/04-git-server/toc.md similarity index 100% rename from 00-notes/toc-ch04-git-on-the-server.md rename to 00-notes/04-git-server/toc.md diff --git a/00-notes/toc-ch05-distributed-git.md b/00-notes/05-distributed-git/toc.md similarity index 100% rename from 00-notes/toc-ch05-distributed-git.md rename to 00-notes/05-distributed-git/toc.md diff --git a/00-notes/toc-ch06-github.md b/00-notes/06-github/toc.md similarity index 100% rename from 00-notes/toc-ch06-github.md rename to 00-notes/06-github/toc.md diff --git a/00-notes/toc-ch07-git-tools.md b/00-notes/07-git-tools/toc.md similarity index 100% rename from 00-notes/toc-ch07-git-tools.md rename to 00-notes/07-git-tools/toc.md diff --git a/00-notes/toc-ch08-customizing-git.md b/00-notes/08-customizing-git/toc.md similarity index 100% rename from 00-notes/toc-ch08-customizing-git.md rename to 00-notes/08-customizing-git/toc.md diff --git a/00-notes/toc-ch09-git-and-other-systems.md b/00-notes/09-git-and-other-scms/toc.md similarity index 100% rename from 00-notes/toc-ch09-git-and-other-systems.md rename to 00-notes/09-git-and-other-scms/toc.md diff --git a/00-notes/toc-ch10-git-internals.md b/00-notes/10-git-internals/toc.md similarity index 100% rename from 00-notes/toc-ch10-git-internals.md rename to 00-notes/10-git-internals/toc.md diff --git a/00-notes/toc-appendix-a-git-in-other-environments.md b/00-notes/A-git-in-other-environments/toc.md similarity index 100% rename from 00-notes/toc-appendix-a-git-in-other-environments.md rename to 00-notes/A-git-in-other-environments/toc.md diff --git a/00-notes/toc-appendix-b-embedding-git.md b/00-notes/B-embedding-git/toc.md similarity index 100% rename from 00-notes/toc-appendix-b-embedding-git.md rename to 00-notes/B-embedding-git/toc.md diff --git a/00-notes/toc-appendix-c-git-commands.md b/00-notes/C-git-commands/toc.md similarity index 100% rename from 00-notes/toc-appendix-c-git-commands.md rename to 00-notes/C-git-commands/toc.md diff --git a/00-notes/storyline-analysis.md b/00-notes/storyline-analysis.md deleted file mode 100644 index cb63e31f1..000000000 --- a/00-notes/storyline-analysis.md +++ /dev/null @@ -1,258 +0,0 @@ -# Common Storyline Analysis - -## Problem: Fragmented Examples Across Chapters - -The current revision notes propose disconnected examples across chapters: - -- **Inconsistent characters**: Sarah (Ch5), Marcus (Ch5), Aisha (Ch5), Maria (Ch6), Megan (Ch5 branch name only) — none carry between chapters -- **Disconnected artifacts**: button components, checkout flows, form components, icon sets, and design tokens appear repeatedly but without continuity -- **No progression**: each chapter reinvents its scenario from scratch, so readers never build on prior context - -A unified storyline solves all three problems. Readers follow one product, one team, and one set of artifacts from Chapter 1 through Chapter 10, with each chapter advancing the story naturally. - ---- - -## Proposed Storyline: "SketchSpark" — AI-Powered Rapid Prototyping - -### The Product -SketchSpark is an AI-powered rapid prototyping application. A designer uploads or draws a rough sketch, and the system generates up to 5 polished UI options in parallel. The designer reviews, selects, and refines a direction — then iterates toward a shippable product. - -### Why This Product -- **Parallel generation mirrors Git branching**: 5 options from 1 sketch = 5 branches from 1 commit. The core metaphor is baked into the product itself. -- **Full design lifecycle**: research (user interviews, competitive analysis), concept design (sketches, information architecture), UI design (wireframes, mockups), visual design (high-fidelity screens, motion), development, testing, launch, iteration — every phase produces distinct artifacts that need version control. -- **Rich artifact variety**: research briefs, persona documents, journey maps, wireframes, AI model configuration files, prompt templates, training data manifests, screen mockups, icon sets, motion specs, design tokens, and production assets — a mix of text (Git-friendly) and binary (Git-challenged) files that naturally teaches both workflows. -- **AI component adds modern relevance**: model configs (`model-params.yaml`), prompt templates (`prompts/sketch-to-ui.txt`), and generation pipelines are text files that merge cleanly — contrasting with binary mockup files that don't. -- **Accessible domain**: every designer understands "sketch to prototype" — no industry-specific jargon required. - -### The Team - -| Character | Role | Personality Trait | Introduced | -|-----------|------|-------------------|------------| -| **Nora** | UX Lead / Product Owner | Methodical researcher, sets standards, writes the briefs | Ch1 | -| **Sam** | UI/Visual Designer | Fast mover, generates options quickly, sometimes commits messy | Ch2 | -| **Priya** | Concept Designer / Illustrator | Works with large binary files (sketches, illustrations, journey maps) | Ch3 | -| **Kai** | Frontend Engineer / ML Integration | Bridges design and code, maintains AI pipeline configs | Ch5 | - -Each character's working style naturally triggers specific Git scenarios: -- **Nora's** research documents and briefs are text-heavy — perfect for diffs and merges -- **Sam's** speed creates stash/reset/amend situations — he commits too fast, forgets files, works on wrong branches -- **Priya's** illustrations and high-fidelity mockups are large binaries — triggers LFS, attributes, and binary merge challenges -- **Kai's** model configs and pipeline files are structured text — demonstrates cross-functional collaboration and submodules - -### The Product Timeline - -Each chapter picks up where the prior left off, following SketchSpark from idea to shipped product: - -| Chapter | Product Phase | What Happens | -|---------|---------------|--------------| -| **Ch1** | Research & Discovery | Nora loses a week of user research notes when her "interview-notes-FINAL-v3" folder gets overwritten by a sync conflict. She discovers Git. Installs it. Learns what version control means through the lens of protecting research artifacts. | -| **Ch2** | Concept Design | Nora creates the SketchSpark repo. Adds the product brief (`product-brief.md`), early wireframes, competitive analysis, and persona documents. Learns status, add, commit, diff, log. Creates `.gitignore` for design tool temp files. First tag: `v0.1-concept`. | -| **Ch3** | Parallel Exploration | Sam joins to explore UI directions. The core product idea — 5 options from 1 sketch — plays out in their workflow: Sam creates 3 branches (`option/card-layout`, `option/list-layout`, `option/canvas-freeform`) to explore different approaches to the results screen. Nora continues refining the input sketch flow on `main`. Their first merge conflict: both edited `user-flows.md`. | -| **Ch4** | Team Infrastructure | The team moves from local-only to GitHub. Nora sets up the org, branch protection (no direct pushes to `main`), and team roles. They evaluate hosting options — GitHub wins over self-hosted for a startup-stage product. | -| **Ch5** | Design & Build Sprint | Priya joins for illustration and high-fidelity mockups. Kai joins to build the AI generation pipeline. Four people coordinating: Nora on UX flows, Sam on UI screens, Priya on onboarding illustrations, Kai on model configs. Integration-manager workflow. First milestone release: `v0.5-alpha` — the sketch-to-options pipeline works end to end. | -| **Ch6** | Public Beta & Community | SketchSpark launches a public beta on GitHub. External contributor (Marcus) forks the repo and submits a PR improving the prompt template for better mobile layouts. Nora reviews with annotated screenshots, requests changes, merges. The team writes CONTRIBUTING.md with guidelines for prompt templates, asset specs, and accessibility requirements. | -| **Ch7** | Production Hardening | Real-world complexity hits: Sam stashes half-finished screen designs to hotfix a broken onboarding flow. Priya uses `git blame` to find when an illustration's color palette drifted from the brand guide. Nora uses interactive rebase to clean up a messy sprint of "fix layout" / "fix layout again" / "actually fix layout" commits. Kai's AI pipeline repo becomes a submodule. | -| **Ch8** | Process & Automation | Nora configures `.gitattributes` for Priya's binary illustration files, creates a commit message template (`[Phase: Component] Description`), and adds a pre-commit hook that validates `model-params.yaml` syntax and checks that prompt templates don't exceed token limits. | -| **Ch9** | Legacy Migration | The company acquires a competitor whose design assets live in SVN. The team migrates 3 years of mockups, illustrations, and research documents into the SketchSpark repo. They handle large binaries, history cleanup, and Git LFS setup. | -| **Ch10** | Scale & Recovery | Sam accidentally force-resets `main`, losing three days of work before a launch deadline. Nora uses reflog to recover every commit. The chapter demystifies Git internals through the lens of "your work is never truly lost" — critical when months of design research, illustrations, and AI configs are at stake. | -| **App A** | Tooling Choices | Each team member uses different tools: Nora uses CLI, Sam prefers VS Code's Git panel for visual diffs of screen designs, Priya uses GitHub Desktop for large file management, Kai uses JetBrains. Decision tree based on role and comfort. | -| **App B** | Tool Integration | Kai explains how SketchSpark's own AI pipeline uses libgit2 under the hood to version-control generated options. Priya explores how Figma plugins use Dulwich (Python) to auto-export assets to Git. | -| **App C** | Reference | Quick-reference card organized by SketchSpark workflow phases: "Starting research" (init, clone), "Daily design work" (branch, add, commit, status), "Reviewing options" (diff, log, show), "Shipping a release" (tag, merge, push). | - ---- - -## Artifact Continuity Map - -These artifacts appear and evolve across chapters, giving readers anchoring reference points. - -### Core Files (appear 5+ chapters) - -| Artifact | First Appears | Evolves Through | Purpose | -|----------|---------------|-----------------|---------| -| `product-brief.md` | Ch2 (created) | Ch3 (updated with chosen direction), Ch5 (alpha scope), Ch6 (public beta scope), Ch8 (commit template references it) | The "source of truth" text file — mergeable, diffable, anchors every design decision | -| `user-flows.md` | Ch2 (initial sketch flow) | Ch3 (merge conflict — Nora and Sam both edited), Ch5 (expanded for full pipeline), Ch7 (blame to find when a flow changed) | Primary UX artifact — where merge conflicts feel real and relatable | -| `screens/results/` | Ch3 (3 layout options as branches) | Ch5 (Sam's production screens), Ch7 (stash scenario mid-redesign), Ch8 (commit template) | The heart of the product — where parallel options become parallel branches | -| `model-params.yaml` | Ch5 (Kai creates) | Ch7 (submodule), Ch8 (pre-commit validation hook), Ch10 (recovered via reflog) | Structured text config — demonstrates Git-friendly AI/ML files alongside binary design files | -| `.gitignore` | Ch2 (created) | Ch5 (expanded for build artifacts), Ch8 (expanded for design tools and model caches) | Practical file designers need immediately | - -### Secondary Files (appear 2-3 chapters) - -| Artifact | Chapters | Purpose | -|----------|----------|---------| -| `research/personas/` | Ch2 (Nora creates), Ch5 (referenced in sprint planning), Ch9 (migrated from legacy) | Text-heavy research artifacts — ideal for diffs | -| `research/competitive-analysis.md` | Ch2 (created), Ch6 (updated when going public) | Shows how research docs evolve alongside product | -| `illustrations/onboarding/` | Ch5 (Priya creates), Ch7 (blame for color drift), Ch10 (packfile performance with large PNGs) | Binary file handling — large asset management | -| `prompts/sketch-to-ui.txt` | Ch5 (Kai creates), Ch6 (Marcus improves via PR), Ch8 (token-limit validation hook) | AI prompt templates — text files that external contributors can improve | -| `CONTRIBUTING.md` | Ch6 (created for public beta), Ch8 (referenced in hooks) | Governance and standards for open contribution | -| `CHANGELOG.md` | Ch5 (v0.5-alpha), Ch7 (rewriting history to clean up entries) | Release documentation | -| `design-tokens.json` | Ch5 (Sam creates for handoff to Kai), Ch7 (selective staging — color vs. typography), Ch8 (attributes config) | Bridge between design and code — the handoff file | - -### Lifecycle Phase Artifacts - -| Product Phase | Key Artifacts | File Types | Git Behavior | -|---------------|---------------|------------|--------------| -| Research | `product-brief.md`, `personas/*.md`, `competitive-analysis.md`, `interview-notes/*.md` | Markdown, text | Fully mergeable, excellent diffs | -| Concept Design | `user-flows.md`, `information-architecture.md`, `sketches/*.png` | Mixed | Text merges cleanly; sketch PNGs are binary | -| UI Design | `screens/**/*.fig`, `screens/**/*.png`, `wireframes/*.md` | Mostly binary | Binary conflicts require manual resolution | -| Visual Design | `illustrations/**/*.png`, `icons/**/*.svg`, `design-tokens.json` | Binary + JSON | SVGs diff as text; PNGs don't; tokens merge | -| AI Pipeline | `model-params.yaml`, `prompts/*.txt`, `training-data-manifest.json` | Structured text | Fully mergeable, hookable, validatable | -| Production | `assets/exported/**`, `docs/`, `CHANGELOG.md` | Mixed | Export-ignore for source files; archive for releases | - ---- - -## Scene-by-Scene Storyline Mapping to Existing Recommendations - -### Chapter 1 — Research & Discovery - -| Revision Note Recommendation | Storyline Scene | -|------------------------------|-----------------| -| Add concrete scenario after line 8's designer mention | Nora's "interview-notes-FINAL-v3" folder disaster — a cloud sync conflict overwrites a week of user research for the SketchSpark concept | -| CVCS = Figma shared file analogy | Nora compares her team's shared Google Drive (centralized, single point of failure) to Git (full local copy of all research history) | -| Three states = draft/ready/approved | Nora maps modified/staged/committed to her research workflow: draft notes → reviewed findings → published insight | -| Binary file support flag | Nora asks: "Can I version my sketch mockups and interview recordings?" — honest answer about binary limitations sets up a theme that runs through every chapter | - -### Chapter 2 — Concept Design - -| Revision Note Recommendation | Storyline Scene | -|------------------------------|-----------------| -| "Initializing a design system repository" | Nora runs `git init` in the `sketchspark/` directory after completing the concept phase | -| Replace `.c` file examples | All examples use `product-brief.md`, `research/personas/early-adopter.md`, `wireframes/sketch-input-flow.png` | -| `.gitignore` template for designers | Nora creates `.gitignore` excluding `.sketch~`, `*.figma_cache`, `__MACOSX/`, `.DS_Store`, `node_modules/` | -| Commit message conventions | Nora writes: `Add product brief and initial user flow wireframes` | -| Design token search in log | Nora uses `git log -S "single sketch"` to find when the core product concept changed from "3 options" to "5 options" in the brief | -| Tags for releases | Nora tags the concept milestone: `git tag -a v0.1-concept -m "Research complete, concept approved, entering UI exploration"` | - -### Chapter 3 — Parallel Exploration - -| Revision Note Recommendation | Storyline Scene | -|------------------------------|-----------------| -| Branch as design variant | Sam creates `option/card-layout`, `option/list-layout`, `option/canvas-freeform` — three parallel UI directions for the results screen, mirroring SketchSpark's own "5 options from 1 sketch" philosophy | -| Hotfix interruption scenario | Sam is deep in `option/card-layout`; Nora discovers a critical user flow gap in the sketch input screen on `main` — Sam creates `fix/sketch-input-upload-error` | -| Merge conflict in token file | Both Nora and Sam edited `user-flows.md` — Nora refined the upload step, Sam added a "compare options" step. They resolve together, learning that text files merge but require coordination. | -| Branch naming conventions | Team establishes: `option/` (design explorations), `feature/` (approved work), `fix/` (corrections), `research/` (investigation branches) | -| Rebasing as "replay on cleaner foundation" | Sam rebases `option/card-layout` onto main to pick up Nora's updated user flow before the team reviews all three options side by side | - -### Chapter 4 — Team Infrastructure - -| Revision Note Recommendation | Storyline Scene | -|------------------------------|-----------------| -| Lead with hosted options | Nora evaluates GitHub vs. GitLab for the growing team — picks GitHub for its PR review workflow and project boards | -| SSH key setup with context | Sam struggles with SSH keys — Nora walks him through it: "The `.pub` file is like a badge that proves who you are. The private file is your ID — never share it." | -| Branch protection | Nora enables `main` branch protection: PRs required, one design review approval needed before merge. No direct commits to `main`. | -| Role mapping | Nora = admin (merges to main, manages releases), Sam = write (creates branches, opens PRs), stakeholders = read-only (view progress, leave comments) | - -### Chapter 5 — Design & Build Sprint - -| Revision Note Recommendation | Storyline Scene | -|------------------------------|-----------------| -| Three-person coordination | Nora (UX flows and research updates), Sam (production UI screens), Priya (onboarding illustrations), Kai (AI pipeline configs) — four parallel workstreams | -| Replace `lib/simplegit.rb` files | All file references: `screens/results/card-layout.fig`, `illustrations/onboarding/step-1.png`, `model-params.yaml`, `prompts/sketch-to-ui.txt` | -| Integration-manager workflow | Nora acts as integrator — reviews Sam's screen PRs, Priya's illustration PRs, and Kai's pipeline PRs before merging to `main` | -| Design system release cycle | Team releases SketchSpark `v0.5-alpha`: the sketch-to-options pipeline works end to end. Tag, archive, changelog. Sam creates `design-tokens.json` for handoff to Kai's frontend. | -| Email workflow → skip notice | "The SketchSpark team uses GitHub PRs for all collaboration. Email-based patches are a legacy workflow — skip unless contributing to projects that require them." | - -### Chapter 6 — Public Beta & Community - -| Revision Note Recommendation | Storyline Scene | -|------------------------------|-----------------| -| Replace Arduino blink with design system PR | Marcus forks SketchSpark, creates `feature/mobile-prompt-template`, improves `prompts/sketch-to-ui.txt` for better mobile layout generation, opens PR with before/after screenshots of generated options | -| Expand image embedding for reviews | Marcus includes side-by-side screenshots: "Current mobile output" vs. "Improved mobile output" with 5 generated options each. Nora annotates with feedback directly in the PR. | -| CONTRIBUTING.md for design projects | Nora writes guidelines: prompt template format, illustration specs (2x resolution, brand palette), screen mockup naming conventions, accessibility requirements for generated UI | -| GitHub Pages for documentation | Team deploys SketchSpark user docs and API reference to `sketchspark.github.io` | -| Async collaboration norms | Marcus is in a different timezone — PR review takes 24 hours. Nora leaves detailed written feedback with annotated screenshots rather than expecting a synchronous call. | - -### Chapter 7 — Production Hardening - -| Revision Note Recommendation | Storyline Scene | -|------------------------------|-----------------| -| Stashing scenario | Sam is redesigning the results comparison screen; urgent bug report — the onboarding flow crashes on tablet. Sam stashes his half-finished screens, switches to `fix/onboarding-tablet`, fixes the layout, merges, pops his stash, and continues. | -| `git blame` for design files | Priya uses `git blame illustrations/onboarding/step-2.png` to find who changed the illustration's color palette — it drifted from the brand guide three commits ago during a rushed sprint. | -| Interactive staging | Nora's `product-brief.md` has both a scope change (adding tablet support) and a research update (new user interview findings). She stages only the research update for the current PR, saving the scope change for a separate review. | -| Reset demystified | Sam accidentally commits directly to `main` instead of his feature branch — uses `git reset --soft HEAD~1` to move the commit back to staging, then creates the correct branch. | -| Squashing messy history | Sam squashes "Update results layout" + "Fix results layout spacing" + "Actually fix the spacing this time" + "Tweak padding" into clean "Redesign results comparison screen for card layout" | -| Submodules | Kai's AI pipeline repo (`sketchspark-ml`) becomes a submodule of the main product repo. When the model improves option generation quality, Kai updates the submodule pointer and the team pulls the new version. | - -### Chapter 8 — Process & Automation - -| Revision Note Recommendation | Storyline Scene | -|------------------------------|-----------------| -| `.gitattributes` for binary files | Nora configures: `*.png binary`, `*.fig binary`, `*.svg diff`, `*.md diff`, `*.yaml diff` — so Git knows which files can be meaningfully diffed | -| Commit message template | Team template enforced by hook: `[Phase: Component] Description` — e.g., `[Design: Results Screen] Add tablet breakpoint layout` or `[Research: Persona] Update early-adopter goals after round 2 interviews` | -| Pre-commit hook | Hook validates that `model-params.yaml` is valid YAML, checks that prompt templates in `prompts/` don't exceed 4096 tokens, and warns if PNG files exceed 5MB | -| Image diffing | Nora sets up EXIF-based diffing so `git diff` shows metadata changes on exported screen mockups — dimensions, color profile, export date | -| Export-ignore | `.fig` source files and `research/raw-interviews/` are versioned in Git but excluded from release archives via `.gitattributes export-ignore` | - -### Chapter 9 — Legacy Migration - -| Revision Note Recommendation | Storyline Scene | -|------------------------------|-----------------| -| SVN design archive migration | SketchSpark acquires a competitor ("QuickMock") whose 3 years of mockups, user research, and design assets live in SVN. Nora leads the migration into the SketchSpark repo. | -| Large binary file handling | Migration surfaces 400MB of PSD source files and high-res mockups — team configures Git LFS for files >10MB | -| Pre-import planning | Nora audits total size, identifies files for LFS, maps QuickMock's flat folder structure to SketchSpark's organized directory hierarchy, and plans which history to preserve vs. squash | - -### Chapter 10 — Scale & Recovery - -| Revision Note Recommendation | Storyline Scene | -|------------------------------|-----------------| -| Reflog for data recovery | Two days before the v1.0 launch, Sam runs `git reset --hard` on `main` by accident, losing three days of final polish commits. Nora uses `git reflog` to find the lost HEAD, creates a recovery branch, and restores everything. | -| Objects as "fingerprints" | Nora explains to Sam: "Every version of every file — every screen mockup, every prompt template, every research note — gets a unique ID. Even if you delete a branch, the data is still in Git's object store." | -| Packfiles and performance | Priya notices `git push` takes 90 seconds — learns that Git packs similar illustration files together using delta compression, but her 50MB PSD additions bypass efficient packing. The team moves large files to LFS. | -| References as labels | "Branches are just labels pointing to commits — like sticky notes on a timeline. Moving them doesn't destroy anything. That's why Sam's 'lost' work was still there." | - -### Appendix A — Tooling Choices - -| Revision Note Recommendation | Storyline Scene | -|------------------------------|-----------------| -| Decision tree | Nora uses CLI (fastest for research doc workflows), Sam prefers VS Code's Git panel (inline diffs of screen designs and tokens), Priya uses GitHub Desktop (visual staging of large illustration files), Kai uses JetBrains (integrated with Python ML pipeline) | -| VS Code for token workflows | Sam edits `design-tokens.json` and `user-flows.md` with inline Git gutter indicators showing what changed since last commit | - -### Appendix B — Tool Integration - -| Revision Note Recommendation | Storyline Scene | -|------------------------------|-----------------| -| Design tool internals | Kai explains how SketchSpark's own generation pipeline uses libgit2 to version-control each of the 5 generated options as lightweight branches — the product's architecture mirrors Git's branching model | -| UX patterns for Git integration | Nora designs SketchSpark's "version history" panel — translating Git concepts (commits, branches, diffs) into a visual interface that non-technical designers can use | -| Dulwich / Python integration | Priya's export script uses Dulwich to auto-commit illustration assets to Git whenever she exports from her design tool — removing manual `git add` from her workflow | - -### Appendix C — Reference - -| Revision Note Recommendation | Storyline Scene | -|------------------------------|-----------------| -| Workflow-based organization | Commands grouped by SketchSpark workflow: "Starting a research phase" (init, clone, branch), "Daily design work" (status, add, commit, diff), "Reviewing options" (log, show, diff between branches), "Collaborating" (push, pull, fetch, merge), "Shipping a release" (tag, archive, merge to main) | - ---- - -## Key Benefits of the Unified Storyline - -1. **Progressive complexity**: readers learn Git operations in the order they'd encounter them building a real product — research notes before merge conflicts, branching before rebasing -2. **Product mirrors Git**: SketchSpark generates 5 parallel options from 1 sketch; Git creates parallel branches from 1 commit. The product's core concept reinforces the most important Git mental model. -3. **Artifact familiarity**: by Chapter 5, `product-brief.md`, `user-flows.md`, and `screens/results/` are familiar landmarks — readers focus on the Git concept, not parsing new file names -4. **Full lifecycle coverage**: research, concept, design, build, test, launch, scale — every phase produces different artifacts (text vs. binary, solo vs. collaborative) that naturally teach different Git workflows -5. **Natural motivation**: each chapter answers "why do I need this?" through the product's progression — branching because the team explores 3 UI options, GitHub because they launched a beta, hooks because they need quality gates before shipping -6. **Character-driven scenarios**: Sam's speed creates stash/reset/recovery lessons; Priya's binary files trigger LFS/attributes lessons; Nora's leadership triggers governance/review/release lessons; Kai's ML pipeline triggers submodule/cross-functional lessons - ---- - -## Risks and Mitigations - -| Risk | Mitigation | -|------|------------| -| Storyline feels forced in reference chapters (App C) | Use storyline as organizational principle, not narrative prose | -| Readers skip chapters and miss context | Each chapter opens with a 2-line "Previously on SketchSpark" recap | -| AI product concept feels niche | The design workflow (research → concept → UI → ship) is universal; the AI generation is flavor, not prerequisite | -| Characters feel contrived | Keep characterization minimal — traits emerge from actions (Sam's messy commits, Priya's large files), not backstory | -| Chapters 9-10 have lower design relevance | Migration and internals are naturally "advanced" — the storyline (acquiring a competitor, recovering before launch) justifies why the team encounters them | -| Binary file challenges recur without resolution | Thread Git LFS as a progressive solution: mentioned Ch1, explained Ch5, configured Ch8, essential in Ch9 | - ---- - -## Implementation Priority - -| Priority | Action | Impact | -|----------|--------|--------| -| 1 | Lock character names, roles, and traits across all chapters | Consistency foundation | -| 2 | Define the `sketchspark/` repo file structure used in examples | Artifact continuity | -| 3 | Rewrite Ch1-3 examples with storyline (highest reader volume, establishes the product) | First impression — readers decide here whether to continue | -| 4 | Rewrite Ch5-6 collaboration examples (most design-relevant, introduces full team) | Core value proposition — collaboration is why designers need Git | -| 5 | Update Ch7-8 tool examples with established artifacts and characters | Builds on familiarity — advanced tools feel less intimidating | -| 6 | Adapt Ch4, Ch9-10, appendices last (infrastructure and advanced topics) | Completeness — important but lower reader volume | diff --git a/00-notes/storyline-rewrite-task.md b/00-notes/storyline-rewrite-task.md deleted file mode 100644 index 9215601dd..000000000 --- a/00-notes/storyline-rewrite-task.md +++ /dev/null @@ -1,29 +0,0 @@ -# Task: Rewrite Storyline Analysis - -## Status: In Progress - -## What Changed -The original `storyline-analysis.md` proposed "Meadow" — a design system for a wellness app — as the unifying storyline across all chapters. **A design system is not a product.** The storyline needs to follow a real product through a real design and development lifecycle. - -## New Direction -Replace the design system storyline with an **AI-powered rapid prototyping product** that: -- Generates up to **5 design options in parallel** from a single sketch -- Covers the **full product lifecycle**: research, concept design, UI design, visual design, development, testing, launch, iteration -- Gives readers a product they can follow from idea through shipping - -## Why This Product -- **Rich design artifact variety**: research docs, personas, journey maps, wireframes, mockups, prototypes, icons, illustrations, motion specs, design tokens, and production assets -- **Parallel generation is inherently visual**: 5 options from 1 sketch naturally produces branching/merging scenarios (each option is a branch; the chosen direction merges to main) -- **AI component adds modern relevance**: model configs, training data references, prompt templates — files that are text-based and Git-friendly alongside binary design files -- **Full lifecycle coverage**: unlike a design system (which is infrastructure), a product has research phases, concept phases, user testing, pivots, launches, and post-launch iteration — each mapping to different Git workflows - -## Requirements for the Rewrite -1. Replace all "Meadow design system" references with the new product concept -2. Redefine the team to reflect product roles (researcher, concept designer, UI/visual designer, engineer) -3. Remap the chapter timeline to product lifecycle phases (research → concept → design → build → test → launch → scale) -4. Update all artifact continuity maps to reflect product files (research briefs, personas, wireframes, screen mockups, prototype configs, AI model params) -5. Update all scene-by-scene mappings to use product scenarios -6. Preserve the structural framework (problem statement, benefits, risks, implementation priority) - -## File to Update -`00-notes/storyline-analysis.md` From e680d19efd765b38339b59b02a74e42ca4a2fdc9 Mon Sep 17 00:00:00 2001 From: Claude <noreply@anthropic.com> Date: Sun, 12 Apr 2026 18:15:30 +0000 Subject: [PATCH 17/17] Add next-steps document outlining foundational, writing, and strategic tasks Captures the recommended sequence for moving from outlines to drafted chapters: build the sample sketchspark repo, write voice/tone and conventions guides, draft Chapter 1 as a template, then prioritize Chapters 2, 3, 5, 6. Also flags build tooling and illustration planning as strategic decisions that should run in parallel. --- 00-notes/next-steps.md | 131 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 131 insertions(+) create mode 100644 00-notes/next-steps.md diff --git a/00-notes/next-steps.md b/00-notes/next-steps.md new file mode 100644 index 000000000..db40ecad7 --- /dev/null +++ b/00-notes/next-steps.md @@ -0,0 +1,131 @@ +# Next Steps + +Recommended work sequence following the completion of the storyline, product spec, and per-chapter outlines. Tasks are ordered within three phases: foundational (do before prose), writing (execute after foundation), and strategic (resolve in parallel). + +--- + +## Foundational + +These tasks establish the shared infrastructure that every chapter will reference. Completing them first prevents inconsistencies that would otherwise have to be fixed across many chapters later. + +### 1. Build the sample `sketchspark/` repository + +Create an actual directory of placeholder files matching the structure described in `storyline.md`: + +``` +sketchspark/ +├── product-brief.md +├── research/ +├── concept/ +├── screens/ +├── illustrations/ +├── icons/ +├── design-tokens.json +├── pipeline/ +│ ├── model-params.yaml +│ └── prompts/ +├── docs/ +├── CONTRIBUTING.md +├── CHANGELOG.md +├── .gitignore +└── .gitattributes +``` + +Every chapter's walkthroughs run against this repo. Having it exist as real files means commands, diffs, and outputs can be captured verbatim instead of invented. The placeholders do not need to be production-quality — they need to be diffable, committable, and believable. + +### 2. Write a voice and tone guide + +A short document capturing how to write for UX designers learning Git. Covers: + +- Reading level and assumed background (design fluency, no CLI assumption) +- When to use design analogies vs. plain explanation +- How to introduce commands (always show context before syntax) +- Terminology decisions (e.g., "commit" vs. "save," "branch" vs. "version") +- Character voice — how Nora, Sam, Priya, Kai, and Marcus sound in narration +- Illustration style guidance for the diagrams that will eventually replace `images/` + +Target: ~2 pages. Lives at `00-notes/voice-and-tone.md`. + +### 3. Define cross-chapter conventions + +A single source of truth for facts that must remain consistent across every chapter: + +- Branch names used in examples (e.g., `feature/mobile-prompts`, `fix/contrast-audit`) +- Tag names and what milestone each represents (`v0.1-concept`, `v0.5-alpha`, `v0.8-beta`, `v1.0`) +- File paths referenced across chapters +- Commit message format the team uses +- Which character owns which artifact type +- Dates and project timeline anchors + +Lives at `00-notes/conventions.md`. Every chapter outline already references these — this document makes them authoritative. + +--- + +## Writing + +### 4. Write Chapter 1 as a proof of concept + +Chapter 1 is the best candidate for the first prose pass because it sets the voice, establishes Nora as the entry character, and introduces the product. Completing it end-to-end will surface: + +- Whether the outline structure actually translates to readable prose +- How much of the original AsciiDoc can be preserved vs. rewritten +- What the walkthrough format looks like in practice +- How figures and screenshots need to be captured + +Treat the Chapter 1 draft as a template. Decisions made there will propagate to every subsequent chapter. + +### 5. Write Chapters 2, 3, 5, 6 next + +After Chapter 1, prioritize the highest-value chapters: + +- **Chapter 2** (Git Basics) — the daily workflow; most designers will use only this chapter +- **Chapter 3** (Branching) — the feature that most changes a designer's mental model +- **Chapter 5** (Distributed Git) — the team collaboration story; Marcus enters here +- **Chapter 6** (GitHub) — the PR workflow, which is most designers' real interface with Git + +Chapters 4, 7, 8, 9, 10 and the appendices come after these four are stable. Chapter 9 (other SCMs) is the lowest-priority chapter and may not need a full rewrite. + +--- + +## Strategic + +These decisions can be resolved in parallel with foundational and writing work, but they constrain downstream choices and should not be deferred indefinitely. + +### 6. Decide on build tooling and distribution + +Questions to resolve: + +- Does the UX designer edition live as a fork of progit2, a long-lived branch, or a parallel variant with its own master `.asc`? +- Does it build with the existing Asciidoctor pipeline or switch to a different toolchain? +- What output formats ship (HTML, PDF, EPUB, web-only)? +- How will illustrations be integrated (replacing `images/` entirely, or additive)? +- Is the title "Pro Git for UX Designers" or something else? Licensing implications of the CC-BY-NC-SA-3.0 inheritance. + +This decision affects how Chapter 1 gets drafted — prose written for a fork is different from prose written for a standalone book. + +### 7. Plan the illustration replacement + +The existing book has ~150 diagrams in `images/` built from `diagram-source/progit.sketch`. Most need to be redrawn for the new audience because they currently show generic branch diagrams, not design workflows. + +Plan: + +- Inventory the existing 150 diagrams and tag each as "keep," "adapt," or "replace" +- Identify new illustrations the storyline requires (SketchSpark screens, team avatars, repository structure, PR review interface) +- Decide illustration style (hand-drawn, flat vector, screenshot-with-callouts) +- Choose the source tool — Figma (matches the book's subject), Sketch (matches the original), or something else +- Budget: illustration work is typically the longest-lead item in a technical book revision + +Lives at `00-notes/illustration-plan.md` once started. + +--- + +## Suggested Order + +1. Cross-chapter conventions (fastest — pulls from outlines that already exist) +2. Sample `sketchspark/` repo skeleton (unblocks every walkthrough) +3. Voice and tone guide (unblocks prose) +4. Build tooling decision (unblocks Chapter 1 drafting) +5. Chapter 1 draft +6. Illustration inventory (can run in parallel with Chapter 1) +7. Chapters 2, 3, 5, 6 +8. Remaining chapters and appendices