Skip to content

docs: clearly document breaking changes and migration paths #13

New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Merged
jbdevprimary merged 1 commit into from
Apr 10, 2026
Merged

docs: clearly document breaking changes and migration paths #13

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

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 19 additions & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,9 +8,27 @@ status: current

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/),
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.

Suggested change
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/),

Copy link

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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/),

Copilot uses AI. Check for mistakes.
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

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.


### ⚠️ BREAKING CHANGES
- **Consolidated Installation Prefix**: The environment is now strictly managed under a single prefix (`~/.get-bashed/` by default). Runtime modules have moved from `~/.bashrc.d/` to `~/.get-bashed/bashrc.d/`, and local secrets have moved from `~/.secrets.d/` to `~/.get-bashed/secrets.d/`. The installer includes automatic migration logic, but users are strongly advised to back up custom modules and secrets before upgrading.
- **Dotfile Symlinking Logic**: Dotfiles are no longer automatically copied to the home directory. Instead, they are copied to the managed prefix and, when `--link-dotfiles` is invoked, they are symlinked *from* the home directory *to* the managed prefix.

### Added
- Comprehensive Sphinx-based documentation published to GitHub Pages.
- Native `globstar` enablement for recursive file matching in Bash.
- Automatic integration of `eza` for modernized `ls` aliases when available.
- New `mkcd` command helper in `90-functions.sh`.
- Security enforcement: `secrets.d` and `.ssh/agent.sock` are now guaranteed to generate with restrictive (`700`/`600`) permissions to prevent exposing local credentials to other users on the system.

### Changed
- Massive performance optimization of interactive startup by eliminating multiple `$(brew --prefix <pkg>)` subshells in `.bash_profile` and `.bashrc`.
- Redesigned `install.bash` to safely escape injected variables like `--name` and `--email`, preventing unintended command execution.
- Redesigned `get_bashed_component` to rely on `$BASH_SOURCE` physical paths rather than trusting the `$GET_BASHED_HOME` environment variable.

<!-- Release Please inserts release sections above this line. -->

## [Unreleased]
Copy link
Copy Markdown

@amazon-q-developer amazon-q-developer Bot Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛑 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.

Suggested change
## [Unreleased]

Expand Down
17 changes: 17 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,23 @@ status: current

A modular, portable Bash environment you can install on any machine. get-bashed gives you clean shell defaults, ordered runtime modules, a centralized tool installer, and reproducible configuration — without touching anything you do not explicitly ask it to touch.

## ⚠️ 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.
Copy link

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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.

Copilot uses AI. Check for mistakes.

**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
Comment on lines +28 to +29
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

security-medium medium

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.

Suggested change
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

Copy link

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Suggested change
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

Copilot uses AI. Check for mistakes.
```

To upgrade your environment, simply re-run the installer over your existing setup:
```bash
./install.sh --auto
```

## What it is

- Ordered `bashrc.d/` modules loaded by `bashrc` at shell startup.
Expand Down
12 changes: 12 additions & 0 deletions docs/INSTALLER.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,18 @@

Installer and configurator for get-bashed.

## ⚠️ 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
Comment on lines +13 to +14
Copy link
Copy Markdown

@gemini-code-assist gemini-code-assist Bot Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

security-medium medium

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.

Suggested change
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

Copy link

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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

Copilot uses AI. Check for mistakes.
```

Comment on lines +5 to +16
Copy link

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
## ⚠️ 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
```

Copilot uses AI. Check for mistakes.
## Overview

Supports non-interactive and interactive installation with profiles,
Expand Down
Loading