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.

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] Improve documentation for Cargo audit configuration file #942

Open
wants to merge 3 commits into
base: main
Choose a base branch
from

Conversation

p21nc3
Copy link

@p21nc3 p21nc3 commented Aug 14, 2023

Fixes #818

Description

Cargo audit provides flexible controls for which kinds of advisories are reported (e.g. show/hide unmaintained or unsound) and which are considered fatal (i.e. cause non-zero exit code, cause CI to fail) via a config file is to be located in .cargo/audit.toml. However, this file is not discoverable, leading to people complaining that the default doesn't work well for them and asking to change the defaults.

This pull request proposes to add the following to the Cargo audit documentation:

  • A section on the configuration file, including its location and a brief description of the settings that can be configured.
  • A link to the TOML documentation, which provides more detailed information about the TOML format.

This will help users find and understand the configuration file, and make it easier for them to customize the behavior of Cargo audit.

Changes

  • Added advisories (unmaintained, unsound and critical) in .cargo/audit.toml file.
  • Added a section on the configuration file to the Cargo audit documentation.
  • Added a link to the TOML documentation to the Cargo audit documentation.

```
$ cargo audit --ignore RUSTSEC-2017-0001
```

This option can also be configured via the [`audit.toml`](./audit.toml.example) file.

Cargo audit can be configured using a file called [audit.toml](./.cargo/audit.toml) This file is optional, and the default settings will work well for most people.
Copy link
Member

@amousset amousset Aug 27, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The .cargo/audit.toml file in the repository is the file used for the project itself, and is not a documentation file. Documentation (like the line above does) should point to the example file audit.toml.example.

@@ -4,6 +4,9 @@ ignore = [
"RUSTSEC-2020-0159", # `chrono` localtime_r segfault
]

show = ["unmaintained", "unsound"]
fatal = ["critical"]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see where these option names come from, the advisories config section looks like it does not include them.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Better document the configuration
2 participants