docs: publish comprehensive master README guide by molhamfetnah · Pull Request #2 · molhamfetnah/ROS

molhamfetnah · 2026-05-04T13:37:39Z

Summary

rewrote root README into a full command-driven onboarding + day-2 operations manual
hardened setup/operations/troubleshooting commands with repo identity and worktree safety guards
aligned README references and implementation plan snippets with existing docs and safe command model

Test Plan

bash scripts/tests/test-track-git-status.sh
bash scripts/tests/test-git-tracking-shim.sh

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

Copilot

Pull request overview

This PR replaces the minimal root README with a comprehensive, command-driven operations guide for the ROS parent repo (and its program/* submodules), and introduces a “git status tracking” mechanism (collector script + bash shim + installer) with accompanying design/implementation docs and tests.

Changes:

Rewrote README.md into an onboarding + day-2 operations manual with troubleshooting and contribution workflow.
Added a git-status tracking system (collector, shim snippet, .bashrc installer) and end-to-end bash tests.
Added specs/plans under docs/superpowers/ documenting the README and tracking-system design/implementation.

Reviewed changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
`.gitignore`	Ignores `.tracking/` artifacts produced by the new tracker.
`README.md`	Full rewrite into an operations manual; includes tracking usage section and references.
`scripts/track-git-status.sh`	Collector that parses porcelain output and writes `.tracking/latest.json`, `history.ndjson`, `latest.txt` with rotation/locking.
`scripts/install-git-tracking-shim.sh`	Installs a snippet source block into `~/.bashrc` (idempotent).
`session/docs/snippets/git-tracking-shim.bash`	Bash `git()` function shim that runs the collector for `status`/`st` in the tracked repo root.
`scripts/tests/test-track-git-status.sh`	Tests collector output, rotation behavior, collision handling, and concurrent execution.
`scripts/tests/test-git-tracking-shim.sh`	Tests shim routing/guardrails and installer idempotence.
`docs/superpowers/specs/2026-05-03-master-readme-guidance-design.md`	Design spec for the new master README content/structure.
`docs/superpowers/specs/2026-05-01-git-status-tracking-design.md`	Design spec for the git status tracking system and constraints.
`docs/superpowers/plans/2026-05-03-master-readme-guidance-implementation.md`	Implementation plan describing how the README rewrite was produced/validated.
`docs/superpowers/plans/2026-05-02-git-status-tracking-implementation.md`	Implementation plan for the tracking collector/shim/installer/tests.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

molhamfetnah · 2026-05-04T14:21:57Z

+  real_git="$(_git_tracking_resolve_real_git_bin)"
+  tracker="${TRACKER_SCRIPT:-/mnt/data/ros/scripts/track-git-status.sh}"
+  tracked_root="/mnt/data/ros"
+  cmd="$(_git_tracking_effective_command "$@")"


@copilot apply changes based on this feedback

molhamfetnah · 2026-05-04T14:22:20Z

+      tracking_dir="$top/.tracking"
+      branch="$("$real_git" -C "$top" branch --show-current 2>/dev/null || printf 'unknown')"
+      porcelain_file="$tracking_dir/.git-status-porcelain.$$.$RANDOM"
+
+      mkdir -p "$tracking_dir"


@copilot apply changes based on this feedback

molhamfetnah · 2026-05-04T14:22:06Z

+cd <path-to-your-ROS-clone> || exit 1
+git rev-parse --show-toplevel
+git status
+ls -la .tracking
+```


@copilot apply changes based on this feedback

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

molhamfetnah · 2026-05-04T14:22:37Z

@copilot apply changes based on the comments in this thread

molhamfetnah · 2026-05-04T14:25:31Z

https://gh.io/copilot-coding-agent-docs apply changes based on the comments in #2 (review)

molhamfetnah · 2026-05-04T14:25:52Z

@copilot apply changes based on the comments in #2 (review)

molhamfetnah and others added 30 commits May 1, 2026 06:35

docs(spec): add git status tracking design

177fb61

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

docs(plan): add git status tracking implementation plan

cd39c7b

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

feat: add git status collector and artifact snapshots

0641af6

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

fix: harden collector rotation and array handling

ac7014b

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

fix: prevent rotation filename collisions

575d75b

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

fix: serialize history rotation and append

c5c4809

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

test: add git tracking shim behavior checks

598ce04

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

feat: add transparent git status tracking shim and installer

785fdb8

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

fix: harden git shim command routing

4bc39b6

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

test: fix concurrent rotation temp cleanup race

da95f33

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

merge: git status tracking implementation

5e55e00

docs(spec): add master README guidance design

64ac64b

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

docs(plan): add master README guidance implementation plan

5a4c197

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

docs: scaffold comprehensive root README structure

88c2086

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

docs: add quickstart and full setup procedures

58cb48f

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

docs: make setup path instructions portable

de05df6

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

docs: harden setup repo path validation

7e4cb63

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

docs: enforce repo identity check in setup

e80e224

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

docs: require exact ROS origin in setup guard

715c99e

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

docs: add day-2 operations and troubleshooting playbooks

a5917b5

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

docs: harden operations and PR-base troubleshooting guidance

a49e394

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

docs: correct worktree and PR troubleshooting commands

53c95eb

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

docs: publish comprehensive root README operations guide

6239cd6

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

docs: align README reference links with existing plan files

e4c368d

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

docs: clarify worktree context in pre-pr and cleanup

af86bfc

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

docs: enforce feature-branch context for parent updates

7506525

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

docs: scope submodule status checks to program repos

e5a09dd

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

docs: align README plan with final command safety rules

734593c

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

docs: finalize worktree and cleanup safety guards

625f8d5

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

docs: enforce fail-fast main base before worktree add

eed0f89

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

Copilot AI review requested due to automatic review settings May 4, 2026 13:37

Copilot started reviewing on behalf of molhamfetnah May 4, 2026 13:38 View session

Copilot AI reviewed May 4, 2026

View reviewed changes

molhamfetnah and others added 4 commits May 4, 2026 17:20

Potential fix for pull request finding

057f1a5

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

d0ac0cc

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

6381648

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Potential fix for pull request finding

4b1be1f

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot started work on behalf of molhamfetnah May 4, 2026 14:22 View session

molhamfetnah merged commit 3da07d4 into main May 4, 2026
1 check failed

Copilot stopped work on behalf of molhamfetnah due to an error May 4, 2026 14:23
Job was cancelled

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: publish comprehensive master README guide#2

docs: publish comprehensive master README guide#2
molhamfetnah merged 34 commits into
mainfrom
feature/master-readme-guidance

molhamfetnah commented May 4, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

molhamfetnah May 4, 2026

Uh oh!

molhamfetnah May 4, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

molhamfetnah May 4, 2026

Uh oh!

molhamfetnah commented May 4, 2026

Uh oh!

Uh oh!

molhamfetnah commented May 4, 2026

Uh oh!

molhamfetnah commented May 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

molhamfetnah commented May 4, 2026

Summary

Test Plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

molhamfetnah May 4, 2026

Choose a reason for hiding this comment

Uh oh!

molhamfetnah May 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

molhamfetnah May 4, 2026

Choose a reason for hiding this comment

Uh oh!

molhamfetnah commented May 4, 2026

Uh oh!

Uh oh!

molhamfetnah commented May 4, 2026

Uh oh!

molhamfetnah commented May 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants