Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add golangci-lint integration info #16

Merged
merged 1 commit into from
Oct 25, 2023
Merged

docs: add golangci-lint integration info #16

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 28 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,25 +31,36 @@ The linter has several options, so you can adjust it to your own code style.

## 📦 Install

Download a prebuilt binary from the [Releases][1] page.
`sloglint` is integrated into [`golangci-lint`][1], and this is the recommended way to use it.

## 📋 Usage
To enable the linter, add the following lines to `.golangci.yml`:

```shell
sloglint [flags] ./...
```yaml
linters:
enable:
- sloglint
```

Alternatively, you can download a prebuilt binary from the [Releases][2] page to use `sloglint` standalone.

## 📋 Usage

Run `golangci-lint` with `sloglint` enabled.
See the list of [available options][3] to configure the linter.

When using `sloglint` standalone, pass the options as flags of the same name.

### Key-value pairs only

The `-kv-only` flag causes `sloglint` to report any use of attributes:
The `kv-only` option causes `sloglint` to report any use of attributes:

```go
slog.Info("a user has logged in", slog.Int("user_id", 42)) // sloglint: attributes should not be used
```

### Attributes only

In contrast, the `-attr-only` flag causes `sloglint` to report any use of key-value pairs:
In contrast, the `attr-only` option causes `sloglint` to report any use of key-value pairs:

```go
slog.Info("a user has logged in", "user_id", 42) // sloglint: key-value pairs should not be used
Expand All @@ -59,7 +70,7 @@ slog.Info("a user has logged in", "user_id", 42) // sloglint: key-value pairs sh

Some `slog.Handler` implementations make use of the given `context.Context` (e.g. to access context values).
For them to work properly, you need to pass a context to all logger calls.
The `-context-only` flag causes `sloglint` to report the use of methods without a context:
The `context-only` option causes `sloglint` to report the use of methods without a context:

```go
slog.Info("a user has logged in") // sloglint: methods without a context should not be used
Expand All @@ -74,7 +85,7 @@ slog.InfoContext(ctx, "a user has logged in")
### No raw keys

To prevent typos, you may want to forbid the use of raw keys altogether.
The `-no-raw-keys` flag causes `sloglint` to report the use of strings as keys
The `no-raw-keys` option causes `sloglint` to report the use of strings as keys
(including `slog.Attr` calls, e.g. `slog.Int("user_id", 42)`):

```go
Expand All @@ -97,21 +108,23 @@ func UserId(value int) slog.Attr { return slog.Int("user_id", value) }
slog.Info("a user has logged in", UserId(42))
```

> 💡 Such helpers can be automatically generated for you by the [`sloggen`][2] tool. Give it a try too!
> 💡 Such helpers can be automatically generated for you by the [`sloggen`][4] tool. Give it a try too!

### Key naming convention

To ensure consistency in logs, you may want to enforce a single key naming convention.
The `-key-naming-case=<snake|kebab|camel|pascal>` flag causes `sloglint` to report keys written in a case other than the given one:
The `key-naming-case` option causes `sloglint` to report keys written in a case other than the given one:

```go
slog.Info("a user has logged in", "user-id", 42) // sloglint: keys should be written in snake_case
```

Possible values are `snake`, `kebab`, `camel`, or `pascal`.

### Arguments on separate lines

To improve code readability, you may want to put arguments on separate lines, especially when using key-value pairs.
The `-args-on-sep-lines` flag causes `sloglint` to report 2+ arguments on the same line:
The `args-on-sep-lines` option causes `sloglint` to report 2+ arguments on the same line:

```go
slog.Info("a user has logged in", "user_id", 42, "ip_address", "192.0.2.0") // sloglint: arguments should be put on separate lines
Expand All @@ -126,5 +139,7 @@ slog.Info("a user has logged in",
)
```

[1]: https://github.com/go-simpler/sloglint/releases
[2]: https://github.com/go-simpler/sloggen
[1]: https://golangci-lint.run
[2]: https://github.com/go-simpler/sloglint/releases
[3]: https://golangci-lint.run/usage/linters/#sloglint
[4]: https://github.com/go-simpler/sloggen
Loading