From a3af5f6f707d52c1f3f6049032b8f934a8d45c55 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 15 Feb 2026 04:30:52 +0000 Subject: [PATCH 1/3] Initial plan From 247e56cdc7c2835b419413abfa9598c01b151d4f Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 15 Feb 2026 04:32:55 +0000 Subject: [PATCH 2/3] fix: rename module from instrospection to introspection (typo fix) Co-authored-by: aretw0 <14055273+aretw0@users.noreply.github.com> --- README.md | 8 ++++---- example_test.go | 2 +- examples/basic/main.go | 2 +- examples/generic/main.go | 2 +- go.mod | 2 +- 5 files changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 1680ecd..8e3cdeb 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # Introspection -[![Go Report Card](https://goreportcard.com/badge/github.com/aretw0/instrospection)](https://goreportcard.com/report/github.com/aretw0/instrospection) -[![Go Reference](https://pkg.go.dev/badge/github.com/aretw0/instrospection.svg)](https://pkg.go.dev/github.com/aretw0/instrospection) +[![Go Report Card](https://goreportcard.com/badge/github.com/aretw0/introspection)](https://goreportcard.com/report/github.com/aretw0/introspection) +[![Go Reference](https://pkg.go.dev/badge/github.com/aretw0/introspection.svg)](https://pkg.go.dev/github.com/aretw0/introspection) [![License](https://img.shields.io/github/license/aretw0/introspection.svg?color=red)](./LICENSE) [![Release](https://img.shields.io/github/release/aretw0/introspection.svg?branch=main)](https://github.com/aretw0/introspection/releases) @@ -95,7 +95,7 @@ stateMachine := introspection.StateMachineDiagram(state, smConfig) ## Installation ```bash -go get github.com/aretw0/instrospection +go get github.com/aretw0/introspection ``` ## Quick Start @@ -106,7 +106,7 @@ package main import ( "context" "fmt" - "github.com/aretw0/instrospection" + "github.com/aretw0/introspection" ) // Define your component's state diff --git a/example_test.go b/example_test.go index fecbe94..b99d580 100644 --- a/example_test.go +++ b/example_test.go @@ -5,7 +5,7 @@ import ( "fmt" "time" - introspection "github.com/aretw0/instrospection" + introspection "github.com/aretw0/introspection" ) // Example demonstrates basic usage of the introspection package diff --git a/examples/basic/main.go b/examples/basic/main.go index febcee0..3e806a8 100644 --- a/examples/basic/main.go +++ b/examples/basic/main.go @@ -5,7 +5,7 @@ import ( "fmt" "time" - "github.com/aretw0/instrospection" + "github.com/aretw0/introspection" ) // WorkerState represents the state of a worker component. diff --git a/examples/generic/main.go b/examples/generic/main.go index 0a87ab2..3952828 100644 --- a/examples/generic/main.go +++ b/examples/generic/main.go @@ -5,7 +5,7 @@ import ( "fmt" "time" - "github.com/aretw0/instrospection" + "github.com/aretw0/introspection" ) // Example using a Task Scheduling domain (not worker/signal) diff --git a/go.mod b/go.mod index 084d736..dc21ff7 100644 --- a/go.mod +++ b/go.mod @@ -1,3 +1,3 @@ -module github.com/aretw0/instrospection +module github.com/aretw0/introspection go 1.24.13 From e63dace926bc6a224b748ae0efdab8054fb1b122 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 15 Feb 2026 04:42:59 +0000 Subject: [PATCH 3/3] docs: add post-merge steps for module rename and decision record Co-authored-by: aretw0 <14055273+aretw0@users.noreply.github.com> --- VERSION | 2 +- docs/DECISIONS.md | 44 +++++++++++++++ docs/MODULE_RENAME.md | 125 ++++++++++++++++++++++++++++++++++++++++++ docs/PLANNING.md | 11 +++- 4 files changed, 180 insertions(+), 2 deletions(-) create mode 100644 docs/MODULE_RENAME.md diff --git a/VERSION b/VERSION index 6da28dd..8294c18 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.1.1 \ No newline at end of file +0.1.2 \ No newline at end of file diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index c0d45e3..8136a9f 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -13,6 +13,7 @@ This document captures key architectural and design decisions made for the intro 7. [Backward Compatibility](#7-backward-compatibility) 8. [Ubuntu-Only CI Testing](#8-ubuntu-only-ci-testing) 9. [CI Workflow Optimization - Avoid Duplicate Runs](#9-ci-workflow-optimization---avoid-duplicate-runs) +10. [Module Path Rename - instrospection → introspection](#10-module-path-rename---instrospection--introspection) --- @@ -475,6 +476,49 @@ For a typical development cycle: --- +## 10. Module Path Rename - instrospection → introspection + +### Decision + +Fix the Go module path from `github.com/aretw0/instrospection` to `github.com/aretw0/introspection`, delete old tags/releases, and publish a new version (`v0.1.2`). + +### Rationale + +**Problem**: The Go module was published with a typo in the module path (`instrospection` instead of `introspection`). This made the module path inconsistent with the GitHub repository URL, preventing `go get` from resolving the module correctly. + +**Options Considered**: +1. **Rewrite git history**: Use `git filter-branch` or `git filter-repo` to fix the typo across all commits, then force-push and re-tag +2. **New version with fix**: Fix the typo in a new commit, delete old tags, and publish a new version +3. **New major version**: Start a `v2` module path with the correct spelling + +**Decision**: Option 2 — New version with fix + +### Trade-offs + +✅ **Pros**: +- Clean fix without disrupting git history +- Safe for Go module proxy and checksum database +- Minimal disruption to any existing consumers +- Old versions can be retracted + +❌ **Cons**: +- Old tags/releases must be manually deleted +- Requires manual steps after merging (see `docs/MODULE_RENAME.md`) + +### Why Not Rewrite History? + +Go modules have unique constraints that make history rewriting ineffective: + +1. **Module proxy caching**: `proxy.golang.org` permanently caches published versions +2. **Checksum database**: `sum.golang.org` records hashes; changed hashes cause verification failures +3. **Force push risks**: Breaks other contributors' local clones and CI + +### Post-Merge Steps + +See [`docs/MODULE_RENAME.md`](MODULE_RENAME.md) for the complete checklist of manual steps required after merging the fix. + +--- + ## Future Decisions These are questions we'll need to answer in future versions: diff --git a/docs/MODULE_RENAME.md b/docs/MODULE_RENAME.md new file mode 100644 index 0000000..ff2eafe --- /dev/null +++ b/docs/MODULE_RENAME.md @@ -0,0 +1,125 @@ +# Module Rename: instrospection → introspection + +This document describes the steps required after merging the module rename PR that fixes the typo `instrospection` → `introspection` in the Go module path. + +## Context + +The Go module was originally published as `github.com/aretw0/instrospection` (with an extra `r`). Since the GitHub repository has always been named `introspection`, the module path was inconsistent with the repository URL. + +PR #6 fixes the typo in `go.mod`, all import paths, and documentation. However, because Go modules are immutable once published, additional manual steps are required after merging. + +## Post-Merge Steps + +### 1. Delete Old Tags and Releases + +The existing tags (`v0.1.0`, `v0.1.1`) point to commits with the old (incorrect) module path. They must be removed and recreated so that `pkg.go.dev` and `go get` resolve the correct module. + +```bash +# Delete remote tags +git push origin :refs/tags/v0.1.0 +git push origin :refs/tags/v0.1.1 + +# Delete local tags +git tag -d v0.1.0 +git tag -d v0.1.1 +``` + +Then delete the corresponding GitHub Releases via the GitHub UI: + +1. Go to https://github.com/aretw0/introspection/releases +2. Delete the `v0.1.0` and `v0.1.1` releases + +### 2. Retract Old Versions (Optional but Recommended) + +If any users already consumed the old module path, add a `retract` directive to `go.mod` to signal that the old versions should not be used: + +```go +module github.com/aretw0/introspection + +go 1.24.13 + +retract ( + v0.1.0 // Published with incorrect module path (instrospection) + v0.1.1 // Published with incorrect module path (instrospection) +) +``` + +> **Note**: The `retract` directive only takes effect when a version **higher** than the retracted versions is published. It will be processed when `v0.1.2` (or later) is tagged. + +### 3. Bump Version and Re-Tag + +After the PR is merged into `main`, create a new release with the corrected module path: + +```bash +# Ensure VERSION is updated +echo "0.1.2" > VERSION +git add VERSION +git commit -m "Bump version to 0.1.2" +git push origin main + +# Create and push the new tag +git tag -a v0.1.2 -m "Release v0.1.2 - Fix module path typo" +git push origin v0.1.2 +``` + +This will trigger GoReleaser via GitHub Actions to create the release automatically. + +### 4. Verify pkg.go.dev + +After the new tag is pushed: + +1. Visit https://pkg.go.dev/github.com/aretw0/introspection +2. If the page doesn't appear automatically, request indexing: + ``` + https://pkg.go.dev/github.com/aretw0/introspection@v0.1.2 + ``` +3. You can also trigger indexing via the Go module proxy: + ```bash + curl https://proxy.golang.org/github.com/aretw0/introspection/@v/v0.1.2.info + ``` +4. Verify the module documentation renders correctly + +### 5. Verify Go Report Card + +1. Visit https://goreportcard.com/report/github.com/aretw0/introspection +2. Trigger a new report if needed + +### 6. Update Downstream Consumers + +If any other projects (e.g., `lifecycle`) depend on this module, update their imports: + +```bash +# In the downstream project +go get github.com/aretw0/introspection@v0.1.2 +``` + +## Important Notes + +### Why Not Rewrite Git History? + +While the original issue mentions git history rewriting, this is **not recommended** for published Go modules because: + +1. **Go module proxy caching**: The Go module proxy (`proxy.golang.org`) caches module versions permanently. Rewriting history doesn't change what's cached. +2. **Checksum database**: The Go checksum database (`sum.golang.org`) has recorded hashes for published versions. Changed hashes would cause verification failures. +3. **Force push risks**: Force-pushing to `main` can break other contributors' local clones and CI pipelines. + +The **correct approach** for Go modules is to: +- Delete the old tags/releases +- Publish a new version with the fix +- Optionally retract the old versions + +### Go Module Path vs Repository URL + +In Go, the module path in `go.mod` must match the repository URL for the module proxy to resolve it correctly. The old path `github.com/aretw0/instrospection` could never be fetched via `go get` since the repository is `github.com/aretw0/introspection`. + +## Checklist + +- [ ] Delete old tags (`v0.1.0`, `v0.1.1`) from remote +- [ ] Delete old GitHub Releases +- [ ] Optionally add `retract` directives to `go.mod` +- [ ] Bump VERSION to `0.1.2` +- [ ] Create and push `v0.1.2` tag +- [ ] Verify GoReleaser creates the release +- [ ] Verify pkg.go.dev indexes the correct module +- [ ] Verify Go Report Card +- [ ] Update downstream consumers (if any) diff --git a/docs/PLANNING.md b/docs/PLANNING.md index 487749b..e34618c 100644 --- a/docs/PLANNING.md +++ b/docs/PLANNING.md @@ -1,6 +1,6 @@ # Planning & Roadmap: Introspection -## Current Version: 0.1.0 +## Current Version: 0.1.2 This document outlines the current state and future direction of the introspection package. @@ -48,6 +48,15 @@ This document outlines the current state and future direction of the introspecti - [x] Add pkg.go.dev example_test.go. +### 🔄 In Progress (v0.1.2) + +- [x] Fix module path typo: `instrospection` → `introspection` (PR #6) +- [x] Document post-merge steps for re-tagging and pkg.go.dev (`docs/MODULE_RENAME.md`) +- [x] Add decision record for module rename (`docs/DECISIONS.md` #10) +- [ ] Delete old tags and releases (manual, post-merge) +- [ ] Re-tag as `v0.1.2` (manual, post-merge) +- [ ] Verify pkg.go.dev indexing (manual, post-merge) + ## Roadmap ### 🎯 v0.2.0 - Enhanced Visualization