v3: changes to get this module ready for release

- Update CI to test v3

- Update v3 dependencies to recent versions

- Move compat layer out into its own package/module

- Add documentation explaining what changed

- fix CONTRIBUTORS and remove duplicate file

- run gofmt and check in the results

- remove the 'term' package from v3

Author: kevinburke

.github/workflows/ci.yml

@@ -4,24 +4,28 @@ jobs:
   test:
     strategy:
       matrix:
-        go-version: [1.18.x, 1.19.x]
+        go-version: [1.23.x, 1.24.x]
     runs-on: ubuntu-latest
     steps:
     - name: Install Go
-      uses: actions/setup-go@v3
+      uses: actions/setup-go@v5
       with:
         go-version: ${{ matrix.go-version }}
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
       with:
          path: './src/github.com/inconshreveable/log15'
-    # staticcheck needs this for GOPATH
-    - run: |
-        echo "GOPATH=$GITHUB_WORKSPACE" >> $GITHUB_ENV
-        echo "GO111MODULE=off" >> $GITHUB_ENV
-        echo "PATH=$GITHUB_WORKSPACE/bin:$PATH" >> $GITHUB_ENV
-    - name: Run tests
+    - name: Run tests for v3
       run: |
-        go get -t -d ./...
-        go vet ./...
-        go test -race ./...
+        go vet -trimpath ./...
+        go test -trimpath -race ./...
+      working-directory: './src/github.com/inconshreveable/log15/v3'
+    - name: Run tests for compat
+      run: |
+        go vet -trimpath ./...
+        go test -trimpath -race ./...
+      working-directory: './src/github.com/inconshreveable/log15/compat'
+    - name: Run tests for v2
+      run: |
+        go vet -trimpath ./...
+        go test -trimpath ./...
       working-directory: './src/github.com/inconshreveable/log15'

.mailmap

@@ -9,7 +9,8 @@ Evan Shaw <edsrzf@gmail.com>
 Gonzalo Serrano <boikot@gmail.com>
 Jeremy <jrbudnack@starkandwayne.com>
 Jonathan Rudenberg <jonathan@titanous.com>
-Kevin Burke <kev@inburke.com>
+Kevin Burke <kevin@burke.dev> <kev@inburke.com>
+Nikolay Petrov <nikolay@ngrok.com> <45884158+nikolay-ngrok@users.noreply.github.com>
 Marc Abramowitz <marc@marc-abramowitz.com>
 Nathan Baulch <nathan.baulch@gmail.com>
 NotZippy <notzippy@gmail.com>

CONTRIBUTORS

@@ -6,15 +6,18 @@ Carl Veazey <Carl_Veazey@cable.comcast.com>
 Chris Hines <github@cs-guy.com>
 Christoph Hack <christoph@tux21b.org>
 Ciaran Downey <me@ciarand.me>
+Devendranath Thadi <devendranath.thadi3@gmail.com>
 Dmitry Chestnykh <dmitry@codingrobots.com>
 Evan Shaw <edsrzf@gmail.com>
 Gonzalo Serrano <boikot@gmail.com>
 Jeremy <jrbudnack@starkandwayne.com>
 Jonathan Rudenberg <jonathan@titanous.com>
+Josh Robson Chase <josh@robsonchase.com>
 Kang Seong-Min <kang.seongmin@gmail.com>
-Kevin Burke <kev@inburke.com>
+Kevin Burke <kevin@burke.dev>
 Marc Abramowitz <marc@marc-abramowitz.com>
 Nathan Baulch <nathan.baulch@gmail.com>
+Nikolay Petrov <nikolay@ngrok.com>
 NotZippy <notzippy@gmail.com>
 Péter Szilágyi <peterke@gmail.com>
 Robert Egorov <robert.egorov@gmail.com>

Makefile

@@ -0,0 +1,4 @@
+force: ;
+
+CONTRIBUTORS: force
+	go run github.com/kevinburke/write_mailmap > CONTRIBUTORS

README.md

@@ -4,6 +4,40 @@
 
 Package log15 provides an opinionated, simple toolkit for best-practice logging in Go (golang) that is both human and machine readable. It is modeled after the Go standard library's [`io`](http://golang.org/pkg/io/) and [`net/http`](http://golang.org/pkg/net/http/) packages and is an alternative to the standard library's [`log`](http://golang.org/pkg/log/) package.
 
+## v3 upgrade
+
+Version 3 compiles with Go modules. It also provides some basic simplifications:
+
+- For performance, the `Call` property has been removed from a `log15.Record`.
+
+- The CallerStackHandler, CallerFuncHandler, and CallerFileHandler
+  have been removed (all three relied on the `Call` property).
+
+- The `term` subpackage has been removed (there are multiple better replacements
+  you can use now).
+
+In most cases, however, it should be sufficient to just change your import path:
+
+```patch
+- import log "github.com/inconshreveable/log15"
++ import log "github.com/inconshreveable/log15/v3"
+```
+
+A lot has happened since log15 was released; you may find the `log/slog` package
+in the standard library to be a better fit for your use case.
+
+Development of the `v3` branch happens in the `v3` subdirectory.
+
+We also added a compatibility layer, which allows existing code to use the v3
+library, so you can incrementally migrate.
+
+```go
+import compat "github.com/inconshreveable/log15/compat"
+```
+
+- `compat.CompatHandler` takes a v3 Handler, and returns a legacy log15 Handler.
+- `compat.CompatLogger` does the same with the Logger type.
+
 ## Features
 - A simple, easy-to-understand API
 - Promotes structured logging by encouraging use of key/value pairs

bench_test.go

@@ -1,3 +1,4 @@
+//go:build go1.3
 // +build go1.3
 
 package log15
@@ -31,33 +32,49 @@ func BenchmarkDiscard(b *testing.B) {
 	}
 }
 
+func BenchmarkCallerFileHandler(b *testing.B) {
+	lg := New()
+	lg.SetHandler(CallerFileHandler(DiscardHandler()))
+
+	for i := 0; i < b.N; i++ {
+		lg.Info("test message")
+	}
+}
+
+func BenchmarkCallerFuncHandler(b *testing.B) {
+	lg := New()
+	lg.SetHandler(CallerFuncHandler(DiscardHandler()))
+
+	for i := 0; i < b.N; i++ {
+		lg.Info("test message")
+	}
+}
+
 func BenchmarkLogfmtNoCtx(b *testing.B) {
 	r := Record{
-		Time:     time.Now(),
-		Lvl:      LvlInfo,
-		Msg:      "test message",
-		Ctx:      []interface{}{},
-		KeyNames: DefaultRecordKeyNames,
+		Time: time.Now(),
+		Lvl:  LvlInfo,
+		Msg:  "test message",
+		Ctx:  []interface{}{},
 	}
 
 	logfmt := LogfmtFormat()
 	for i := 0; i < b.N; i++ {
-		logfmt.Format(r)
+		logfmt.Format(&r)
 	}
 }
 
 func BenchmarkJsonNoCtx(b *testing.B) {
 	r := Record{
-		Time:     time.Now(),
-		Lvl:      LvlInfo,
-		Msg:      "test message",
-		Ctx:      []interface{}{},
-		KeyNames: DefaultRecordKeyNames,
+		Time: time.Now(),
+		Lvl:  LvlInfo,
+		Msg:  "test message",
+		Ctx:  []interface{}{},
 	}
 
 	jsonfmt := JsonFormat()
 	for i := 0; i < b.N; i++ {
-		jsonfmt.Format(r)
+		jsonfmt.Format(&r)
 	}
 }
 
@@ -189,32 +206,3 @@ func BenchmarkLog15WithoutFields(b *testing.B) {
 		}
 	})
 }
-
-func BenchmarkDefaultWarn(b *testing.B) {
-	logger := New("source", "default", "partition", 3)
-	logger.SetHandler(newHandler())
-	b.ReportAllocs()
-	b.ResetTimer()
-	b.RunParallel(func(pb *testing.PB) {
-		for pb.Next() {
-			logger.Warn("warn message")
-		}
-	})
-}
-func BenchmarkDefaultDebug(b *testing.B) {
-	logger := New("source", "default", "partition", 3)
-	logger.SetHandler(newHandler())
-	b.ReportAllocs()
-	b.ResetTimer()
-	b.RunParallel(func(pb *testing.PB) {
-		for pb.Next() {
-			logger.Debug("debug message")
-		}
-	})
-}
-func newHandler() Handler {
-	lvl := LvlWarn
-	logformat := LogfmtFormat()
-	handler := StreamHandler(ioutil.Discard, logformat)
-	return LvlFilterHandler(lvl, handler)
-}

v3/compat.go compat/compat.gov3/compat.go renamed to compat/compat.go

@@ -1,29 +1,44 @@
-package log15
+// This file provides backwards compatibility with pre-v3 log15 code.
+//
+// The compatibility layer allows existing code that uses the legacy log15 API
+// to work seamlessly with the v3 version. It provides adapter types and functions
+// that translate between the old and new interfaces, enabling incremental migration
+// from legacy code to the new v3 API.
+//
+// Users may want this when:
+//   - Migrating existing applications to use v3 gradually
+//   - Working with third-party libraries that still use the legacy log15 API
+//   - Maintaining backwards compatibility while adopting new v3 features
+//
+// Use CompatHandler() and CompatLogger() to wrap v3 types for legacy code.
+
+package compat
 
 import (
 	legacy "github.com/inconshreveable/log15"
+	"github.com/inconshreveable/log15/v3"
 )
 
 type compat struct {
-	Handler
-	Logger
+	log15.Handler
+	log15.Logger
 }
 
-func fromLegacyRecord(r *legacy.Record) Record {
-	return Record{
+func fromLegacyRecord(r *legacy.Record) log15.Record {
+	return log15.Record{
 		Time: r.Time,
-		Lvl:  Lvl(r.Lvl),
+		Lvl:  log15.Lvl(r.Lvl),
 		Msg:  r.Msg,
 		Ctx:  r.Ctx,
-		KeyNames: &RecordKeyNames{
+		KeyNames: &log15.RecordKeyNames{
 			Lvl:  r.KeyNames.Lvl,
 			Msg:  r.KeyNames.Msg,
 			Time: r.KeyNames.Time,
 		},
 	}
 }
 
-func toLegacyRecord(r Record) *legacy.Record {
+func toLegacyRecord(r log15.Record) *legacy.Record {
 	var keyNames legacy.RecordKeyNames
 	if r.KeyNames != nil {
 		keyNames.Lvl = r.KeyNames.Lvl
@@ -48,7 +63,7 @@ func (c *compat) GetHandler() legacy.Handler {
 }
 
 func (c *compat) SetHandler(h legacy.Handler) {
-	c.Logger.SetHandler(FuncHandler(func(r Record) error {
+	c.Logger.SetHandler(log15.FuncHandler(func(r log15.Record) error {
 		return h.Log(toLegacyRecord(r))
 	}))
 }
@@ -58,12 +73,12 @@ func (c *compat) New(args ...interface{}) legacy.Logger {
 }
 
 // CompatHandler wraps a handler for use with pre-v3 log15.Handler consumers.
-func CompatHandler(h Handler) legacy.Handler {
+func CompatHandler(h log15.Handler) legacy.Handler {
 	return &compat{Handler: h}
 }
 
 // CompatLogger wraps a Logger for use with pre-v3 log15.Logger consumers.
-func CompatLogger(l Logger) legacy.Logger {
+func CompatLogger(l log15.Logger) legacy.Logger {
 	return &compat{Logger: l}
 }