Gogs/docs/dev/flamego_migration_checklist.md

Flamego Migration Checklist

This checklist provides a step-by-step guide for executing the migration from Macaron to Flamego.

Pre-Migration

1. Team Preparation

• Review migration guide with entire team
• Ensure all developers understand Flamego basics
• Allocate 3-4 weeks for migration effort
• Schedule regular sync meetings during migration
• Identify rollback champion

2. Documentation Review

• Read Flamego documentation
• Review migration examples
• Review middleware documentation
• Understand Flamego's dependency injection

3. Environment Setup

• Create feature branch: feature/flamego-migration
• Set up local development environment
• Verify current tests pass: go test ./...
• Document current test coverage: go test -cover ./...
• Benchmark current performance (optional)

4. Backup and Safety

• Tag current stable version: git tag v0.14.0-pre-flamego
• Create backup branch: git branch backup/before-flamego
• Document current behavior (screenshots, videos)
• Ensure CI/CD can roll back quickly

Phase 1: Dependencies (Day 1)

1.1 Update go.mod

• Add Flamego core

  go get github.com/flamego/flamego@latest
  

• Add Flamego middleware

  go get github.com/flamego/binding@latest
  go get github.com/flamego/cache@latest
  go get github.com/flamego/captcha@latest
  go get github.com/flamego/csrf@latest
  go get github.com/flamego/gzip@latest
  go get github.com/flamego/i18n@latest
  go get github.com/flamego/session@latest
  go get github.com/flamego/template@latest
  

• Run go mod tidy

• Verify no conflicts

• Commit: git commit -m "Add Flamego dependencies"

1.2 Import Updates

• Create find-and-replace script
• Test script on sample file
• Document import mapping

Phase 2: Core Framework (Days 2-3)

2.1 Main Application Setup

File: internal/cmd/web.go

• Update imports

  // Remove
  "gopkg.in/macaron.v1"
  "github.com/go-macaron/*"
  
  // Add
  "github.com/flamego/flamego"
  "github.com/flamego/session"
  "github.com/flamego/csrf"
  // etc...
  

• Rename function: newMacaron() → newFlamego()

• Update initialization: macaron.New() → flamego.New()

• Update logger: macaron.Logger() → flamego.Logger()

• Update recovery: macaron.Recovery() → flamego.Recovery()

• Update gzip: Keep similar pattern

• Update static file serving

  // Change from macaron.Static() to flamego.Static()
  f.Use(flamego.Static(...))
  

• Update renderer setup

  // Change from macaron.Renderer() to template.Templater()
  f.Use(template.Templater(template.Options{...}))
  

• Test compilation: go build

• Fix any compilation errors

• Commit: git commit -m "Migrate main app setup to Flamego"

2.2 Middleware Configuration

Still in internal/cmd/web.go:

• Update i18n middleware

  • Change Langs → Languages
  • Change DefaultLang → DefaultLanguage
  • Change SubURL → URLPrefix

• Update cache middleware

  • Change from string adapter to config struct
  • Update method calls: Put() → Set()

• Update captcha middleware

  • Verify options compatibility
  • Test captcha generation

• Update toolbox functionality

  • Remove toolbox middleware
  • Create custom health check endpoint

  f.Get("/-/health", func(c flamego.Context) {
      if err := database.Ping(); err != nil {
          c.ResponseWriter().WriteHeader(500)
          return
      }
      c.ResponseWriter().WriteHeader(200)
  })
  

• Update session middleware

  • Change Provider → Use config structs
  • Change interface: session.Store → session.Session
  • Test session persistence

• Update CSRF middleware

  • Verify options compatibility
  • Test token generation
  • Update method calls: GetToken() → Token()

• Test server starts: go run gogs.go web

• Verify middleware loads in correct order

• Commit: git commit -m "Migrate middleware to Flamego"

2.3 Route Definitions

Still in internal/cmd/web.go:

• Update basic routes: :param → <param>
• Update regex routes: ^:name(a|b)$ → <name:a|b>
• Test route compilation
• Verify route pattern matching

Routes to update:

• Home route: /

• Explore routes: /explore/*

• Install routes: /install

• User routes: /user/*

• Admin routes: /admin/*

• Org routes: /org/*

• Repo routes: /:username/:reponame/*

• API routes: /api/*

• Commit: git commit -m "Update route syntax to Flamego"

Phase 3: Context System (Days 4-5)

3.1 Context Wrapper

File: internal/context/context.go

• Update imports

  "github.com/flamego/flamego"
  "github.com/flamego/cache"
  "github.com/flamego/csrf"
  "github.com/flamego/session"
  

• Update Context struct

  type Context struct {
      flamego.Context  // Embedded interface
      cache   cache.Cache
      csrf    csrf.CSRF
      flash   *session.Flash
      session session.Session
      // ... other fields
  }
  

• Add accessor methods

  func (c *Context) Cache() cache.Cache { return c.cache }
  func (c *Context) CSRF() csrf.CSRF { return c.csrf }
  func (c *Context) Session() session.Session { return c.session }
  

• Update Contexter middleware signature

  func Contexter(store Store) flamego.Handler {
      return func(
          ctx flamego.Context,
          cache cache.Cache,
          sess session.Session,
          // ... other injectables
      ) {
          // ...
      }
  }
  

• Update response methods

  • c.HTML() - needs template parameter or stored reference
  • c.JSON() - use ResponseWriter directly
  • c.Redirect() - should work as-is
  • c.PlainText() - use ResponseWriter
  • c.ServeContent() - use ResponseWriter

• Update parameter access

  • All c.Params(":name") → c.Param("name")

• Test compilation: go build

• Commit: git commit -m "Migrate Context wrapper to Flamego"

3.2 Other Context Files

Files in internal/context/:

• auth.go - Update handler signatures
• api.go - Update APIContext
• user.go - Update user context helpers
• repo.go - Update repository context
  • Fix all c.Params() calls
  • Update middleware signatures
• org.go - Update organization context
• go_get.go - Update go-get handler

For each file:

• Update imports

• Change macaron.Handler → flamego.Handler

• Change *macaron.Context → flamego.Context or *Context

• Update c.Params(":name") → c.Param("name")

• Fix compilation errors

• Commit after each file or group

• Final commit: git commit -m "Complete context system migration"

Phase 4: Form Binding (Days 6-7)

4.1 Form Package

File: internal/form/form.go

• Update imports

  "github.com/flamego/binding"
  

• Update custom validators

  // Register custom validators with go-playground/validator
  binding.RegisterValidation("alphaDashDot", validatorFunc)
  

• Update SetNameMapper if used

• Test validator registration

4.2 Form Structs

Files: internal/form/*.go

For each file:

• auth.go - Update auth forms
• admin.go - Update admin forms
• user.go - Update user forms
• repo.go - Update repo forms
• org.go - Update org forms

For each form:

• Change binding:"Required" → validate:"required"
• Change binding:"MaxSize(100)" → validate:"max=100"
• Change binding:"MinSize(5)" → validate:"min=5"
• Update custom validators
• Test form validation

Pattern replacements:

• binding:"Required" → validate:"required"

• binding:"AlphaDashDot" → validate:"alphaDashDot"

• binding:"MaxSize(N)" → validate:"max=N"

• binding:"MinSize(N)" → validate:"min=N"

• binding:"Email" → validate:"email"

• binding:"Url" → validate:"url"

• Commit: git commit -m "Migrate form binding to Flamego"

Phase 5: Route Handlers (Days 8-14)

5.1 User Routes

Files: internal/route/user/*.go

• user.go - Basic user handlers

  • Update handler signatures
  • Add template parameters
  • Fix parameter access

• auth.go - Login/logout handlers

  • Update session access: sess.Get() etc.
  • Fix CSRF token access

• setting.go - User settings

  • Update form binding usage
  • Fix template rendering

• Test user flows:

  • User registration
  • User login
  • User logout
  • Profile view
  • Settings update

• Commit: git commit -m "Migrate user routes to Flamego"

5.2 Repository Routes

Files: internal/route/repo/*.go

Priority files:

• repo.go - Main repo handler
• home.go - Repository home
• issue.go - Issue management
• pull.go - Pull requests
• release.go - Releases
• webhook.go - Webhooks
• setting.go - Repo settings
• http.go - HTTP Git operations

For each file:

• Update imports

• Update handler signatures

• Add template parameters where needed

• Fix c.Params() calls

• Update form binding calls

• Test repository flows:

  • Create repository
  • View repository
  • Create issue
  • Create pull request
  • Push via HTTP

• Commit: git commit -m "Migrate repository routes to Flamego"

5.3 Admin Routes

Files: internal/route/admin/*.go

• admin.go - Admin dashboard

• user.go - User management

• org.go - Organization management

• repo.go - Repository management

• auth.go - Auth source management

• notice.go - System notices

• Test admin flows:

  • Admin dashboard
  • Create user
  • Delete user
  • Manage auth sources

• Commit: git commit -m "Migrate admin routes to Flamego"

5.4 Organization Routes

Files: internal/route/org/*.go

• org.go - Organization handlers

• team.go - Team management

• setting.go - Org settings

• Test organization flows:

  • Create organization
  • Manage teams
  • Org settings

• Commit: git commit -m "Migrate organization routes to Flamego"

5.5 API Routes

Files: internal/route/api/v1/*.go

• api.go - API router setup
• user/*.go - User API endpoints
• repo/*.go - Repository API endpoints
• org/*.go - Organization API endpoints
• admin/*.go - Admin API endpoints

For API handlers:

• Update JSON response methods

• Ensure authentication works

• Test error responses

• Test API endpoints:

  • GET /api/v1/user
  • GET /api/v1/users/:username
  • GET /api/v1/repos/:owner/:repo
  • Create/Update operations

• Commit: git commit -m "Migrate API routes to Flamego"

5.6 LFS Routes

Files: internal/route/lfs/*.go

• route.go - LFS router

• basic.go - Basic auth

• batch.go - Batch API

• Update tests in *_test.go

• Test LFS operations

• Commit: git commit -m "Migrate LFS routes to Flamego"

5.7 Other Routes

Files: internal/route/*.go

• home.go - Home page

• install.go - Installation

• dev/*.go - Development tools

• Commit: git commit -m "Migrate remaining routes to Flamego"

Phase 6: Testing (Days 15-18)

6.1 Unit Tests

• Update test helpers

  • Create mock flamego.Context
  • Update test fixtures

• Run unit tests: go test ./internal/context/...

• Run unit tests: go test ./internal/form/...

• Run unit tests: go test ./internal/route/...

• Fix failing tests one by one

• Document test changes

• Commit: git commit -m "Fix unit tests for Flamego"

6.2 Integration Tests

• Update integration test setup

• Test complete user flows

  • Registration → Login → Create Repo → Push → Pull

• Test admin flows

  • Admin login → User management

• Test API flows

  • Token auth → API calls

• Commit: git commit -m "Fix integration tests for Flamego"

6.3 Manual Testing

Create test plan document covering:

Web UI:

• Homepage loads
• User registration works
• User login works
• User logout works
• Profile viewing works
• Repository creation works
• Repository viewing works
• Issue creation works
• Issue commenting works
• Pull request creation works
• Pull request merging works
• Webhooks work
• LFS operations work
• File uploads work
• Avatar uploads work
• Admin panel works
• Organization creation works
• Team management works

Git Operations:

• HTTP clone works
• HTTP push works
• HTTP pull works
• SSH clone works
• SSH push works
• SSH pull works

API:

• Authentication works
• All v1 endpoints work
• Error responses correct

Security:

• CSRF protection works
• Session security works
• Auth required endpoints protected

Localization:

• Language switching works

• Translations load correctly

• Document any issues found

• Create issues for bugs

• Commit fixes as they're made

6.4 Performance Testing

• Benchmark homepage
• Benchmark repository view
• Benchmark API endpoints
• Compare with pre-migration benchmarks
• Document performance differences
• Optimize if needed

Phase 7: Cleanup (Days 19-20)

7.1 Remove Old Code

• Remove all Macaron imports

  grep -r "gopkg.in/macaron.v1" .
  grep -r "github.com/go-macaron/" .
  

• Remove from go.mod

  go mod edit -droprequire gopkg.in/macaron.v1
  go mod edit -droprequire github.com/go-macaron/binding
  # etc...
  

• Run go mod tidy

• Verify unused dependencies removed

• Commit: git commit -m "Remove Macaron dependencies"

7.2 Code Quality

• Run linter: golangci-lint run
• Fix linter issues
• Run go fmt ./...
• Run go vet ./...
• Check for TODO/FIXME comments
• Commit: git commit -m "Code quality improvements"

7.3 Documentation

• Update README.md if needed
• Update CONTRIBUTING.md if needed
• Update development documentation
• Document migration in CHANGELOG.md
• Create migration announcement
• Commit: git commit -m "Update documentation for Flamego"

7.4 Final Review

• Review all changes
• Ensure no debug code left
• Verify test coverage maintained
• Check for security issues
• Run final test suite: go test ./...
• Run final manual tests

Phase 8: Deployment (Days 21-22)

8.1 Pre-Deployment

• Create release candidate tag
• Deploy to staging environment
• Run smoke tests on staging
• Performance test on staging
• Security scan
• Get team approval

8.2 Deployment

• Schedule deployment window
• Notify users of maintenance
• Take backup of production
• Deploy new version
• Monitor logs
• Run smoke tests on production
• Monitor performance metrics

8.3 Post-Deployment

• Monitor for issues (24-48 hours)
• Check error rates
• Verify all features working
• Collect user feedback
• Address any urgent issues

Rollback Procedure

If critical issues occur:

Quick Rollback

1. Stop application
2. Restore from backup
3. Start application
4. Verify functionality
5. Notify users

Git Rollback

1. Identify last good commit
2. git revert <commit-range>
3. git push
4. Deploy reverted version

Issues to Watch For

• Session persistence issues
• CSRF token validation failures
• Form validation errors
• Template rendering errors
• Performance degradation
• Memory leaks
• Authentication bypass

Success Criteria

Migration is successful when:

• All tests pass
• All manual test cases pass
• Performance is equal or better
• No security regressions
• No functionality lost
• Code quality maintained
• Documentation updated
• Team trained on new code

Notes Section

Use this section to track:

• Issues encountered
• Solutions found
• Time spent on each phase
• Lessons learned
• Tips for future migrations

---

Migration Started: _____________
Migration Completed: _____________
Total Time: _____________
Team Members: _____________
Issues Created: _____________
Issues Resolved: _____________