GoToSocial/vendor/github.com/sagikazarmark/slog-shim/README.md

slog shim

Go 1.21 introduced a new structured logging package, log/slog, to the standard library. Although it's been eagerly anticipated by many, widespread adoption isn't expected to occur immediately, especially since updating to Go 1.21 is a decision that most libraries won't make overnight.

Before this package was added to the standard library, there was an experimental version available at golang.org/x/exp/slog. While it's generally advised against using experimental packages in production, this one served as a sort of backport package for the last few years, incorporating new features before they were added to the standard library (like slices, maps or errors).

This package serves as a bridge, helping libraries integrate slog in a backward-compatible way without having to immediately update their Go version requirement to 1.21. On Go 1.21 (and above), it acts as a drop-in replacement for log/slog, while below 1.21 it falls back to golang.org/x/exp/slog.

How does it achieve backwards compatibility?

Although there's no consensus on whether dropping support for older Go versions is considered backward compatible, a majority seems to believe it is. (I don't have scientific proof for this, but it's based on conversations with various individuals across different channels.)

This package adheres to that interpretation of backward compatibility. On Go 1.21, the shim uses type aliases to offer the same API as slog/log. Once a library upgrades its version requirement to Go 1.21, it should be able to discard this shim and use log/slog directly.

For older Go versions, the library might become unstable after removing the shim. However, since those older versions are no longer supported, the promise of backward compatibility remains intact.

Installation

go get github.com/sagikazarmark/slog-shim

Usage

Import this package into your library and use it in your public API:

package mylib

import slog "github.com/sagikazarmark/slog-shim"

func New(logger *slog.Logger) MyLib {
    // ...
}

When using the library, clients can either use log/slog (when on Go 1.21) or golang.org/x/exp/slog (below Go 1.21):

package main

import "log/slog"

// OR

import "golang.org/x/exp/slog"

mylib.New(slog.Default())

Make sure consumers are aware that your API behaves differently on different Go versions.

Once you bump your Go version requirement to Go 1.21, you can drop the shim entirely from your code:

package mylib

- import slog "github.com/sagikazarmark/slog-shim"
+ import "log/slog"

func New(logger *slog.Logger) MyLib {
    // ...
}

License

The project is licensed under a BSD-style license.