Merge branch 'master' into codex/2025-08-24-06-41-42

Author: ReneWerner87

README.md

@@ -14,6 +14,15 @@ go install github.com/gofiber/cli/fiber@latest
 
 ## Commands
 
+The Fiber CLI provides several commands to enhance development workflows:
+
+- `fiber dev` – Rerun the project whenever watched files change
+- `fiber serve` – Serve static files with optional TLS and caching
+- `fiber new` – Generate a new Fiber project from templates
+- `fiber migrate` – Migrate an existing project to a newer Fiber version
+- `fiber upgrade` – Upgrade the CLI itself to the latest release
+- `fiber version` – Print the local and latest available CLI versions
+
 ## fiber
 
 ### Synopsis
@@ -142,6 +151,8 @@ fiber new PROJECT [module name] [flags]
 
 Migrate Fiber project version to a newer version
 
+See the [Migration guide](docs/guide/migrate.md) for more details.
+
 ```bash
 fiber migrate --to 3.0.0
 ```
@@ -152,6 +163,8 @@ fiber migrate --to 3.0.0
   -t, --to string        Migrate to a specific version e.g:3.0.0 Format: X.Y.Z
   -f, --force            Force migration even if already on the version
   -s, --skip_go_mod      Skip running go mod tidy, download and vendor
+      --hash string      Commit hash for Fiber version
+  -v, --verbose          Enable verbose output
   -h, --help             help for migrate
 ```
 

cmd/internal/migrations/common.go

@@ -14,7 +14,7 @@ import (
 )
 
 var (
-	pkgRegex         = regexp.MustCompile(`(github\.com/gofiber/fiber/)(v\d+)( *?)(v[\w.-]+)`)
+	pkgRegex         = regexp.MustCompile(`(?m)^(\s*require\s+)?(github\.com/gofiber/fiber/)(v\d+)(\s+)(v[\w.-]+)$`)
 	fiberImportRegex = regexp.MustCompile(`(^|")github\.com/gofiber/fiber/v\d+`)
 )
 
@@ -37,7 +37,7 @@ func MigrateGoPkgs(cmd *cobra.Command, cwd string, _, target *semver.Version) er
 	// replace old version with new version in go.mod file
 	fileContentStr := pkgRegex.ReplaceAllString(
 		string(fileContent),
-		"${1}v"+strconv.FormatUint(target.Major(), 10)+"${3}v"+target.String(),
+		"${1}${2}v"+strconv.FormatUint(target.Major(), 10)+"${4}v"+target.String(),
 	)
 
 	if fileContentStr != string(fileContent) {

cmd/internal/migrations/lists.go

@@ -30,9 +30,9 @@ type Migration struct {
 // Example structure:
 // {"from": ">=2.0.0", "to": "<=3.*.*", "fn": [MigrateFN, MigrateFN]}
 var Migrations = []Migration{
-	{From: ">=1.0.0", To: ">=0.0.0-0", Functions: []MigrationFn{MigrateGoPkgs, MigrateDependencies}},
+	{From: ">=1.0.0-0", To: ">=0.0.0-0", Functions: []MigrationFn{MigrateGoPkgs, MigrateDependencies}},
 	{
-		From: ">=2.0.0",
+		From: ">=2.0.0-0",
 		To:   "<4.0.0-0",
 		Functions: []MigrationFn{
 			v3migrations.MigrateHandlerSignatures,

cmd/internal/migrations/lists_test.go

@@ -38,8 +38,8 @@ func Test_DoMigration_Verbose(t *testing.T) {
 		cmd.SetOut(&buf)
 		require.NoError(t, migrations.DoMigration(cmd, dir, curr, target, true, true))
 		out := buf.String()
-		assert.Contains(t, out, "Skipping migration from >=1.0.0 to >=0.0.0-0")
-		assert.Contains(t, out, "Skipping migration from >=2.0.0 to <4.0.0-0")
+		assert.Contains(t, out, "Skipping migration from >=1.0.0-0 to >=0.0.0-0")
+		assert.Contains(t, out, "Skipping migration from >=2.0.0-0 to <4.0.0-0")
 	})
 }
 
@@ -67,7 +67,7 @@ require github.com/valyala/fasthttp v1.0.0`
 		require.NoError(t, migrations.DoMigration(cmd, dir, curr, target, true, true))
 		out := buf.String()
 		assert.Contains(t, out, "MigrateGoPkgs: no changes")
-		assert.Contains(t, out, "Skipping migration from >=2.0.0 to <4.0.0-0")
+		assert.Contains(t, out, "Skipping migration from >=2.0.0-0 to <4.0.0-0")
 	})
 
 	t.Run("changes", func(t *testing.T) {
@@ -92,6 +92,6 @@ require github.com/valyala/fasthttp v1.0.0`
 		out := buf.String()
 		assert.Contains(t, out, "Migrating Go packages")
 		assert.Contains(t, out, "MigrateGoPkgs: changed")
-		assert.Contains(t, out, "Skipping migration from >=2.0.0 to <4.0.0-0")
+		assert.Contains(t, out, "Skipping migration from >=2.0.0-0 to <4.0.0-0")
 	})
 }

cmd/migrate.go

@@ -94,7 +94,7 @@ func migrateRunE(cmd *cobra.Command, opts MigrateOptions) error {
 		}
 	}
 
-	if !targetVersion.GreaterThan(currentVersion) && !(opts.Force && targetVersion.Equal(currentVersion)) {
+	if !targetVersion.GreaterThan(currentVersion) && !opts.Force {
 		return fmt.Errorf("target version v%s is not greater than current version v%s", opts.TargetVersionS, currentVersionS)
 	}
 
@@ -152,12 +152,16 @@ func pseudoVersionFromHash(base *semver.Version, hash string) (string, error) {
 				Date time.Time `json:"date"`
 			} `json:"committer"`
 		} `json:"commit"`
+		SHA string `json:"sha"`
 	}
 	if err := json.NewDecoder(res.Body).Decode(&data); err != nil {
 		return "", fmt.Errorf("decode response: %w", err)
 	}
 
-	short := hash
+	short := data.SHA
+	if short == "" {
+		short = hash
+	}
 	if len(short) > 12 {
 		short = short[:12]
 	}

cmd/migrate_test.go

@@ -356,17 +356,97 @@ func Test_Migrate_WithHash(t *testing.T) {
 	defer func() { require.NoError(t, os.Chdir(cwd)) }()
 
 	hash := "abcdef1234567890abcdef1234567890abcdef12"
+	short := hash[:7]
 	httpmock.Activate()
 	defer httpmock.DeactivateAndReset()
-	commitURL := "https://api.github.com/repos/gofiber/fiber/commits/" + hash
-	httpmock.RegisterResponder(http.MethodGet, commitURL, httpmock.NewBytesResponder(200, []byte(`{"commit":{"committer":{"date":"2020-01-02T03:04:05Z"}}}`)))
+	commitURL := "https://api.github.com/repos/gofiber/fiber/commits/" + short
+	httpmock.RegisterResponder(http.MethodGet, commitURL, httpmock.NewBytesResponder(200, []byte(`{"sha":"`+hash+`","commit":{"committer":{"date":"2020-01-02T03:04:05Z"}}}`)))
 
 	cmd := newMigrateCmd()
 	setupCmd()
 	defer teardownCmd()
-	_, err = runCobraCmd(cmd, "-t=3.0.0", "--hash="+hash)
+	_, err = runCobraCmd(cmd, "-t=3.0.0", "--hash="+short)
 	require.NoError(t, err)
 
 	gm := readFileTB(t, filepath.Join(dir, "go.mod"))
 	assert.Contains(t, gm, "github.com/gofiber/fiber/v3 v3.0.1-0.20200102030405-abcdef123456")
 }
+
+func Test_Migrate_WithHash_UpdatePseudoVersion(t *testing.T) {
+	dir, err := os.MkdirTemp("", "migrate_hash_update")
+	require.NoError(t, err)
+	defer func() { require.NoError(t, os.RemoveAll(dir)) }()
+
+	goMod := "module example\n\n" +
+		"go 1.20\n\n" +
+		"require github.com/gofiber/fiber/v3\tv3.0.1-0.20200102030405-abcdef123456\n"
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "go.mod"), []byte(goMod), 0o600))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "main.go"), []byte("package main"), 0o600))
+
+	cwd, err := os.Getwd()
+	require.NoError(t, err)
+	require.NoError(t, os.Chdir(dir))
+	defer func() { require.NoError(t, os.Chdir(cwd)) }()
+
+	hash := "fedcba654321fedcba654321fedcba654321fedc"
+	short := hash[:7]
+	httpmock.Activate()
+	defer httpmock.DeactivateAndReset()
+	commitURL := "https://api.github.com/repos/gofiber/fiber/commits/" + short
+	httpmock.RegisterResponder(http.MethodGet, commitURL, httpmock.NewBytesResponder(200, []byte(`{"sha":"`+hash+`","commit":{"committer":{"date":"2020-01-03T03:04:05Z"}}}`)))
+
+	cmd := newMigrateCmd()
+	setupCmd()
+	defer teardownCmd()
+	_, err = runCobraCmd(cmd, "-t=3.0.0", "--hash="+short, "-f")
+	require.NoError(t, err)
+
+	gm := readFileTB(t, filepath.Join(dir, "go.mod"))
+	assert.Contains(t, gm, "v3.0.1-0.20200103030405-fedcba654321")
+	assert.NotContains(t, gm, "abcdef123456")
+}
+
+func Test_Migrate_WithHash_DowngradeWithForce(t *testing.T) {
+	dir, err := os.MkdirTemp("", "migrate_hash_downgrade")
+	require.NoError(t, err)
+	defer func() { require.NoError(t, os.RemoveAll(dir)) }()
+
+	goMod := "module example\n\n" +
+		"go 1.20\n\n" +
+		"require github.com/gofiber/fiber/v3\tv3.0.1-0.20200103030405-fedcba654321\n"
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "go.mod"), []byte(goMod), 0o600))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, "main.go"), []byte("package main"), 0o600))
+
+	cwd, err := os.Getwd()
+	require.NoError(t, err)
+	require.NoError(t, os.Chdir(dir))
+	defer func() { require.NoError(t, os.Chdir(cwd)) }()
+
+	hash := "abcdef1234567890abcdef1234567890abcdef12"
+	short := hash[:7]
+	httpmock.Activate()
+	defer httpmock.DeactivateAndReset()
+	commitURL := "https://api.github.com/repos/gofiber/fiber/commits/" + short
+	httpmock.RegisterResponder(http.MethodGet, commitURL, httpmock.NewBytesResponder(200, []byte(`{"sha":"`+hash+`","commit":{"committer":{"date":"2020-01-02T03:04:05Z"}}}`)))
+
+	t.Run("without force", func(t *testing.T) {
+		cmd := newMigrateCmd()
+		setupCmd()
+		defer teardownCmd()
+		out, err := runCobraCmd(cmd, "-t=3.0.0", "--hash="+short)
+		require.Error(t, err)
+		assert.Contains(t, out, "not greater")
+	})
+
+	t.Run("force", func(t *testing.T) {
+		cmd := newMigrateCmd()
+		setupCmd()
+		defer teardownCmd()
+		_, err := runCobraCmd(cmd, "-t=3.0.0", "--hash="+short, "-f")
+		require.NoError(t, err)
+
+		gm := readFileTB(t, filepath.Join(dir, "go.mod"))
+		assert.Contains(t, gm, "v3.0.1-0.20200102030405-abcdef123456")
+		assert.NotContains(t, gm, "fedcba654321")
+	})
+}

cmd/version.go

@@ -40,7 +40,7 @@ func versionRun(cmd *cobra.Command, _ []string) {
 }
 
 var (
-	currentVersionRegexp = regexp.MustCompile(`github\.com/gofiber/fiber[^\n]*? (.*)\n`)
+	currentVersionRegexp = regexp.MustCompile(`github\.com/gofiber/fiber[^\n]*?\s+(.*)\n`)
 	currentVersionFile   = "go.mod"
 )
 

docs/guide/migrate.md

@@ -0,0 +1,62 @@
+---
+id: migrate
+title: "\U0001F501 Migration"
+sidebar_position: 10
+---
+
+The `fiber migrate` command upgrades an existing Fiber project to a newer
+[github.com/gofiber/fiber](https://github.com/gofiber/fiber) release.
+It determines the current version from your `go.mod` file and applies any
+necessary migration steps.
+
+## Usage
+
+```bash
+fiber migrate --to 3.0.0
+```
+
+## Flags
+
+- `-t`, `--to` – Target version to migrate to. Defaults to the latest release
+- `--hash` – Commit hash for the Fiber version when migrating to a pseudo version
+- `-f`, `--force` – Force migration even if already on the target version
+- `-s`, `--skip_go_mod` – Skip running `go mod tidy`, `go mod download`, and `go mod vendor`
+- `-v`, `--verbose` – Enable verbose output during migration
+
+## Examples
+
+Upgrade to the latest Fiber version:
+
+```bash
+fiber migrate
+```
+
+Migrate to a specific release:
+
+```bash
+fiber migrate --to 3.0.0
+```
+
+Use a commit hash for unreleased versions:
+
+```bash
+fiber migrate --to 3.0.0 --hash abcdef123456
+```
+
+Force re-running migrations even if the version matches:
+
+```bash
+fiber migrate --to 3.0.0 --force
+```
+
+Skip `go mod` commands for offline environments:
+
+```bash
+fiber migrate --skip_go_mod
+```
+
+Verbose mode prints detailed progress and executed steps:
+
+```bash
+fiber migrate --verbose
+```