docs: clearly document breaking changes and migration paths#13
Conversation
|
Caution Review failedPull request was closed or merged during review 📝 WalkthroughWalkthroughDocumentation updates across three files describing a breaking change that consolidates runtime modules, local secrets, and dotfiles into a single managed directory prefix (~/.get-bashed/), including migration guidance and upgrade procedures for existing installations. Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![amazon-q-developer[bot]](https://avatars.githubusercontent.com/in/1220912?s=60&v=4){kind=small}
There was a problem hiding this comment.
This PR adds important documentation for the breaking changes related to the consolidated installation prefix. The warnings and migration instructions are well-structured and prominently placed.
Critical issue identified:
- Duplicate
## [Unreleased]header in CHANGELOG.md that will break changelog parsers
Once the duplicate header is removed, this documentation will properly inform users about the breaking changes and provide clear migration steps.
You can now have the agent implement changes and create commits directly on your pull request's source branch. Simply comment with /q followed by your request in natural language to ask the agent to make changes.
|
|
||
| <!-- Release Please inserts release sections above this line. --> | ||
|
|
||
| ## [Unreleased] |
There was a problem hiding this comment.
🛑 Logic Error: Duplicate "## [Unreleased]" section header. Line 14 introduces a new Unreleased section with breaking changes, but line 34 contains an existing duplicate header. This will break changelog parsers and confuse readers about which section is active. Remove the duplicate header at line 34.
| ## [Unreleased] | |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a consolidated installation prefix (~/.get-bashed/) for runtime modules and secrets, representing a significant structural change. The documentation and changelog have been updated to include migration instructions and a summary of new features like native globstar support and security enforcement for secrets. Review feedback highlights a versioning downgrade in the changelog specification, a duplicate header that may break release automation, and a security concern regarding the preservation of file permissions in the recommended backup commands.
| All notable changes to this project will be documented in this file. | ||
|
|
||
| The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), | ||
| The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), |
There was a problem hiding this comment.
The version of the "Keep a Changelog" specification has been downgraded from 1.1.0 to 1.0.0. Unless there is a specific reason to target the older 2017 version of the spec, it is recommended to use 1.1.0 which is the current standard.
| The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), | |
| The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), |
| The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), | ||
| and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). | ||
|
|
||
| ## [Unreleased] |
There was a problem hiding this comment.
This adds a second ## [Unreleased] header to the file (the existing one is at line 34). This duplication can break automated tools like "Release Please" which rely on specific header markers to insert new release notes. Consider merging this content under the existing header or removing the redundant one.
| cp -r ~/.bashrc.d ~/bashrc.d.backup 2>/dev/null || true | ||
| cp -r ~/.secrets.d ~/secrets.d.backup 2>/dev/null || true |
There was a problem hiding this comment.
The backup commands use cp -r, which does not preserve file permissions and relies on the current umask for the destination. For sensitive directories like ~/.secrets.d, this could result in the backup being created with overly permissive access (e.g., world-readable). Using cp -rp is safer as it preserves the original restrictive permissions.
| cp -r ~/.bashrc.d ~/bashrc.d.backup 2>/dev/null || true | |
| cp -r ~/.secrets.d ~/secrets.d.backup 2>/dev/null || true | |
| cp -rp ~/.bashrc.d ~/bashrc.d.backup 2>/dev/null || true | |
| cp -rp ~/.secrets.d ~/secrets.d.backup 2>/dev/null || true |
| cp -r ~/.bashrc.d ~/bashrc.d.backup 2>/dev/null || true | ||
| cp -r ~/.secrets.d ~/secrets.d.backup 2>/dev/null || true |
There was a problem hiding this comment.
The backup commands use cp -r, which does not preserve file permissions. For sensitive directories like ~/.secrets.d, this could result in the backup being created with insecure permissions depending on the system umask. Using cp -rp ensures that the restrictive permissions of the secrets directory are maintained in the backup.
| cp -r ~/.bashrc.d ~/bashrc.d.backup 2>/dev/null || true | |
| cp -r ~/.secrets.d ~/secrets.d.backup 2>/dev/null || true | |
| cp -rp ~/.bashrc.d ~/bashrc.d.backup 2>/dev/null || true | |
| cp -rp ~/.secrets.d ~/secrets.d.backup 2>/dev/null || true |
There was a problem hiding this comment.
Pull request overview
This PR aims to make the project’s breaking architectural migration to the consolidated ~/.get-bashed/ prefix highly visible and actionable for existing users by adding upgrade warnings and migration guidance across primary docs.
Changes:
- Added an “Upgrading & Breaking Changes” warning section to the README and installer documentation.
- Expanded the changelog with an Unreleased section detailing breaking changes plus related additions/changes.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| README.md | Adds prominent upgrade/breaking-change notice plus backup + upgrade commands. |
| docs/INSTALLER.md | Adds upgrade/breaking-change notice to installer docs (but this file appears generated). |
| CHANGELOG.md | Adds detailed Unreleased breaking changes and other entries; adjusts Keep a Changelog link. |
Comments suppressed due to low confidence (1)
CHANGELOG.md:36
- There are now two
## [Unreleased]sections (one at the top and another immediately after the "Release Please" marker). This will confuse readers and may break/complicate release automation expectations. Please keep a single Unreleased section and remove/move the extra header so the file structure is unambiguous.
<!-- Release Please inserts release sections above this line. -->
## [Unreleased]
## [0.1.0] — 2026-02-03
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| **Before upgrading, it is highly recommended to back up your custom modules:** | ||
| ```bash | ||
| cp -r ~/.bashrc.d ~/bashrc.d.backup 2>/dev/null || true | ||
| cp -r ~/.secrets.d ~/secrets.d.backup 2>/dev/null || true |
There was a problem hiding this comment.
The backup command for ~/.secrets.d uses cp -r into ~/secrets.d.backup, which will typically create the destination directory with default umask (often 755). That can unintentionally make secret material readable by other local users. Consider using a backup approach that preserves restrictive permissions (e.g., cp -a/tar plus an explicit chmod 700 on the backup dir).
| cp -r ~/.secrets.d ~/secrets.d.backup 2>/dev/null || true | |
| cp -a ~/.secrets.d ~/secrets.d.backup 2>/dev/null && chmod 700 ~/secrets.d.backup || true |
|
|
||
| **BREAKING CHANGE:** As of the latest release, get-bashed consolidates all runtime modules, local secrets, and dotfiles into a single managed prefix (default: `~/.get-bashed/`). | ||
|
|
||
| If you are upgrading from a legacy installation (where files were stored in `~/.bashrc.d` and `~/.secrets.d`), the installer will attempt to automatically migrate your custom scripts and secrets into the new managed prefix. |
There was a problem hiding this comment.
The docs say the installer will "migrate" legacy ~/.bashrc.d and ~/.secrets.d, but the installer actually removes those directories after copying their files (to avoid continuing to use legacy locations). It would be good to explicitly warn that the legacy directories will be deleted after a successful migration so users aren't surprised.
| If you are upgrading from a legacy installation (where files were stored in `~/.bashrc.d` and `~/.secrets.d`), the installer will attempt to automatically migrate your custom scripts and secrets into the new managed prefix. | |
| If you are upgrading from a legacy installation (where files were stored in `~/.bashrc.d` and `~/.secrets.d`), the installer will attempt to automatically migrate your custom scripts and secrets into the new managed prefix. After a successful migration, the legacy `~/.bashrc.d` and `~/.secrets.d` directories are deleted so the old locations are no longer used. |
| ## ⚠️ Upgrading & Breaking Changes | ||
|
|
||
| **BREAKING CHANGE:** As of the latest release, get-bashed consolidates all runtime modules, local secrets, and dotfiles into a single managed prefix (default: `~/.get-bashed/`). | ||
|
|
||
| If you are upgrading from a legacy installation (where files were stored in `~/.bashrc.d` and `~/.secrets.d`), the installer will attempt to automatically migrate your custom scripts and secrets into the new managed prefix. | ||
|
|
||
| **Before upgrading, it is highly recommended to back up your custom modules:** | ||
| ```bash | ||
| cp -r ~/.bashrc.d ~/bashrc.d.backup 2>/dev/null || true | ||
| cp -r ~/.secrets.d ~/secrets.d.backup 2>/dev/null || true | ||
| ``` | ||
|
|
There was a problem hiding this comment.
docs/INSTALLER.md is generated by scripts/gen-docs.sh (via shdoc < install.bash > docs/INSTALLER.md). Manual edits here will be overwritten the next time docs are regenerated. Please move this breaking-change/upgrade guidance into the shdoc source in install.bash (or the docs generation pipeline) and regenerate the file.
| ## ⚠️ Upgrading & Breaking Changes | |
| **BREAKING CHANGE:** As of the latest release, get-bashed consolidates all runtime modules, local secrets, and dotfiles into a single managed prefix (default: `~/.get-bashed/`). | |
| If you are upgrading from a legacy installation (where files were stored in `~/.bashrc.d` and `~/.secrets.d`), the installer will attempt to automatically migrate your custom scripts and secrets into the new managed prefix. | |
| **Before upgrading, it is highly recommended to back up your custom modules:** | |
| ```bash | |
| cp -r ~/.bashrc.d ~/bashrc.d.backup 2>/dev/null || true | |
| cp -r ~/.secrets.d ~/secrets.d.backup 2>/dev/null || true | |
| ``` |
| **Before upgrading, it is highly recommended to back up your custom modules:** | ||
| ```bash | ||
| cp -r ~/.bashrc.d ~/bashrc.d.backup 2>/dev/null || true | ||
| cp -r ~/.secrets.d ~/secrets.d.backup 2>/dev/null || true |
There was a problem hiding this comment.
Same as README: the suggested cp -r ~/.secrets.d ~/secrets.d.backup backup will usually create ~/secrets.d.backup with default umask permissions, which may expose secrets to other local users. Recommend a backup command that preserves/forces restrictive permissions for the backup directory and files.
| cp -r ~/.secrets.d ~/secrets.d.backup 2>/dev/null || true | |
| install -d -m 700 ~/secrets.d.backup 2>/dev/null && cp -a ~/.secrets.d/. ~/secrets.d.backup/ 2>/dev/null || true |
| All notable changes to this project will be documented in this file. | ||
|
|
||
| The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), | ||
| The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), |
There was a problem hiding this comment.
The Keep a Changelog link was changed from 1.1.0 to 1.0.0. Unless there's a specific reason to pin to 1.0.0, consider reverting this to avoid unrelated churn in a PR focused on breaking-change documentation.
| The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), | |
| The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), |
Adds prominent warnings in the README, CHANGELOG, and INSTALLER docs to alert users about the breaking architectural shift to the consolidated
~/.get-bashedprefix, along with explicit backup and upgrade commands.Summary by CodeRabbit
New Features
Improvements
Documentation