README.md

Documentation: github.com/sagikazarmark/slog-shim

     1# [slog](https://pkg.go.dev/log/slog) shim
     2
     3[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/sagikazarmark/slog-shim/ci.yaml?style=flat-square)](https://github.com/sagikazarmark/slog-shim/actions/workflows/ci.yaml)
     4[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/mod/github.com/sagikazarmark/slog-shim)
     5![Go Version](https://img.shields.io/badge/go%20version-%3E=1.20-61CFDD.svg?style=flat-square)
     6[![built with nix](https://img.shields.io/badge/builtwith-nix-7d81f7?style=flat-square)](https://builtwithnix.org)
     7
     8Go 1.21 introduced a [new structured logging package](https://golang.org/doc/go1.21#slog), `log/slog`, to the standard library.
     9Although it's been eagerly anticipated by many, widespread adoption isn't expected to occur immediately,
    10especially since updating to Go 1.21 is a decision that most libraries won't make overnight.
    11
    12Before this package was added to the standard library, there was an _experimental_ version available at [golang.org/x/exp/slog](https://pkg.go.dev/golang.org/x/exp/slog).
    13While it's generally advised against using experimental packages in production,
    14this one served as a sort of backport package for the last few years,
    15incorporating new features before they were added to the standard library (like `slices`, `maps` or `errors`).
    16
    17This 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`.
    18
    19**How does it achieve backwards compatibility?**
    20
    21Although there's no consensus on whether dropping support for older Go versions is considered backward compatible, a majority seems to believe it is.
    22(I don't have scientific proof for this, but it's based on conversations with various individuals across different channels.)
    23
    24This 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`.
    25Once a library upgrades its version requirement to Go 1.21, it should be able to discard this shim and use `log/slog` directly.
    26
    27For older Go versions, the library might become unstable after removing the shim.
    28However, since those older versions are no longer supported, the promise of backward compatibility remains intact.
    29
    30## Installation
    31
    32```shell
    33go get github.com/sagikazarmark/slog-shim
    34```
    35
    36## Usage
    37
    38Import this package into your library and use it in your public API:
    39
    40```go
    41package mylib
    42
    43import slog "github.com/sagikazarmark/slog-shim"
    44
    45func New(logger *slog.Logger) MyLib {
    46    // ...
    47}
    48```
    49
    50When using the library, clients can either use `log/slog` (when on Go 1.21) or `golang.org/x/exp/slog` (below Go 1.21):
    51
    52```go
    53package main
    54
    55import "log/slog"
    56
    57// OR
    58
    59import "golang.org/x/exp/slog"
    60
    61mylib.New(slog.Default())
    62```
    63
    64**Make sure consumers are aware that your API behaves differently on different Go versions.**
    65
    66Once you bump your Go version requirement to Go 1.21, you can drop the shim entirely from your code:
    67
    68```diff
    69package mylib
    70
    71- import slog "github.com/sagikazarmark/slog-shim"
    72+ import "log/slog"
    73
    74func New(logger *slog.Logger) MyLib {
    75    // ...
    76}
    77```
    78
    79## License
    80
    81The project is licensed under a [BSD-style license](LICENSE).
View as plain text