docs: add upgrade guide for Log v2 + release notes

[aymanbagabas]

Add v2 upgrade guide

Release notes

What's New in Log v2

We're excited to announce the second major release of Log!

[!NOTE]
If you're looking for technical details on migrating from v1, check out the Upgrade Guide.

❤️ Charm Land Import Path

We've updated our import paths to use vanity domains and our own domain to import Go packages.

// Before
import "github.com/charmbracelet/log"

// After
import "charm.land/log/v2"

🎨 Lip Gloss v2

Log v2 now uses Lip Gloss v2, which brings a pure, streamlined styling experience. No more fighting over i/o! Lip Gloss is now pure, which means Log manages i/o and styling flows smoothly without conflicts.

What does this mean for you? Built-in color downsampling. Your logs will look great in any terminal, automatically downsampling colors to match the terminal's capabilities. No more broken colors in limited color environments.

🌈 Modern Color Profile Support

Log v2 uses the colorprofile library to automatically detect and adapt to your terminal's color capabilities. Your logs will "just work" across all terminals, from basic 16-color setups to true color displays.

Colors are automatically downsampled to the best available profile, so your styled logs never misbehave—whether you're in a fancy modern terminal or a basic SSH session.

🔧 Simpler API

We've cleaned up the API to make working with color profiles more intuitive:

// Set a color profile manually
logger.SetColorProfile(colorprofile.TrueColor)

// The logger automatically handles downsampling

The SetColorProfile method now uses colorprofile.Profile instead of termenv.Profile, giving you direct control over color handling with a modern, well-supported library.

✨ Updated Styles with Lip Gloss v2

All style fields in the Styles struct now use Lip Gloss v2. The styling API remains familiar, but benefits from improved performance and the new pure architecture:

styles := log.DefaultStyles()
styles.Levels[log.ErrorLevel] = lipgloss.NewStyle().
    SetString("ERROR!!").
    Padding(0, 1, 0, 1).
    Background(lipgloss.Color("204")).
    Foreground(lipgloss.Color("0"))

Lip Gloss v2 brings better rendering, improved performance, and a cleaner separation of concerns between styling and i/o.

🚀 Better Performance

With the move to Lip Gloss v2 and colorprofile, Log v2 delivers:

• Faster rendering — Pure Lip Gloss means less overhead
• Smarter color handling — Automatic downsampling reduces unnecessary processing
• Cleaner output — Colors that work correctly in every environment

📦 Smaller Dependency Tree

Log v2 has a streamlined set of dependencies:

• charm.land/lipgloss/v2 — Pure styling, no i/o conflicts
• github.com/charmbracelet/colorprofile — Smart color detection and downsampling
• Removed termenv dependency — Everything handled through modern libraries

🔮 Ready for the Future

The v2 architecture sets Log up for future enhancements. The pure Lip Gloss foundation and modern color handling mean we can add new features without architectural constraints.

🌍 What Stays the Same

All the features you love about Log are still here:

• ✅ Leveled logging (Debug, Info, Warn, Error, Fatal)
• ✅ Structured key-value pairs
• ✅ Customizable styles and colors
• ✅ Multiple formatters (Text, JSON, Logfmt)
• ✅ Sub-loggers with context
• ✅ Slog handler support
• ✅ Standard log adapter
• ✅ Helper functions
• ✅ Timestamp and caller reporting

The core API remains familiar—you're just getting better performance and color handling under the hood.

🌈 More on Log v2

Ready to upgrade? Head over to the Upgrade Guide for the complete migration checklist.

Feedback

Have thoughts on Log v2? We'd love to hear about it. Let us know on…

• Discord
• Matrix
• Email

---

Part of Charm.

Charm热爱开源 • Charm loves open source • نحنُ نحب المصادر المفتوحة