Thank you for taking interest in contributing to Trivy!

1. Every Pull Request should have an associated GitHub issue link in the PR description. Note that issues are created by Trivy maintainers based on feedback provided in a GitHub discussion. Please refer to the [issue](./issue.md) and [discussion](./discussion.md) pages for explanation about this process. If you think your change is trivial enough, you can skip the issue and instead add justification and explanation in the PR description.
1. Once you've picked an issue to work on, please check the existing open PRs to make sure no one is already solving it, and leave a comment on the issue saying you're taking it. This lets maintainers assign the issue to you and tells other contributors it's already being worked on, which helps everyone avoid duplicating the same work.
1. Your PR is more likely to be accepted if it focuses on just one change.
1. There's no need to add or tag reviewers.
1. If a reviewer commented on your code or asked for changes, please remember to respond with a comment. Do not mark the discussion as resolved. It's up to the reviewer to mark it resolved (in case the suggested fix addresses the problem properly). PRs with unresolved issues should not be merged (even if the comment is unclear or requires no action from your side).
1. Please include a comment with the results before and after your change.
1. Your PR is more likely to be accepted if it includes tests (We have not historically been very strict about tests, but we would like to improve this!).
1. If your PR affects the user experience in some way, please update the README.md and the CLI help accordingly.

## Development
Install the necessary tools for development by following their respective installation instructions.

- [Go](https://go.dev/doc/install)
- [Mage](https://magefile.org/)

### Build
After making changes to the Go source code, build the project with the following command:

```shell
$ mage build
$ ./trivy -h
```

### Lint
You must pass the linter checks:

```shell
$ mage lint:run
```

Additionally, you need to have run `go mod tidy`, so execute the following command as well:

```shell
$ mage tidy
```

To autofix linters use the following command:
```shell
$ mage lint:fix
```

### Unit tests
Your PR must pass all the unit tests. You can test it as below.

```
$ mage test:unit
```

### Integration tests
Your PR must pass all the integration tests. You can test it as below.

```
$ mage test:integration
```

### Protocol Buffers
If you update protobuf files (`.proto`), you need to regenerate the Go code:

```shell
$ mage protoc:generate
```

You can also format and lint protobuf files:

```shell
$ mage protoc:fmt     # Format protobuf files
$ mage protoc:lint    # Lint protobuf files
$ mage protoc:breaking # Check for breaking changes against main branch
```

### Documentation
If you update CLI flags, you need to generate the CLI references.
The test will fail if they are not up-to-date.

```shell
$ mage docs:generate
```

You can build the documents as below and view it at http://localhost:8000.

```
$ mage docs:serve
```

## Title
It is not that strict, but we use the title conventions in this repository.
Each commit message doesn't have to follow the conventions as long as it is clear and descriptive since it will be squashed and merged.

### Format of the title

```
<type>(<scope>): <subject>
```

The `type` and `scope` should always be lowercase as shown below.

**Allowed `<type>` values:**

- **feat** for a new feature for the user, not a new feature for build script. Such commit will trigger a release bumping a MINOR version.
- **fix** for a bug fix for the user, not a fix to a build script. Such commit will trigger a release bumping a PATCH version.
- **perf** for performance improvements. Such commit will trigger a release bumping a PATCH version.
- **docs** for changes to the documentation.
- **style** for formatting changes, missing semicolons, etc.
- **refactor** for refactoring production code, e.g. renaming a variable.
- **test** for adding missing tests, refactoring tests; no production code change.
- **build** for updating build configuration, development tools or other changes irrelevant to the user.
- **chore** for updates that do not apply to the above, such as dependency updates.
- **ci** for changes to CI configuration files and scripts
- **revert** for revert to a previous commit

**Allowed `<scope>` values:**

checks:

- vuln
- misconf
- secret
- license

mode:

- image
- fs
- repo
- sbom
- k8s
- server
- aws
- vm
- plugin

os:

- alpine
- redhat
- alma
- rocky
- azure
- oracle
- debian
- ubuntu
- amazon
- suse
- photon
- distroless

language:

- ruby
- php
- python
- nodejs
- rust
- dotnet
- java
- go
- elixir
- dart
- julia

vuln:

- os
- lang

config:

- kubernetes
- dockerfile
- terraform
- cloudformation

container

- docker
- podman
- containerd
- oci

cli:

- cli
- flag

SBOM:

- cyclonedx
- spdx
- purl

others:

- helm
- report
- db
- parser
- deps

The `<scope>` can be empty (e.g. if the change is a global or difficult to assign to a single component), in which case the parentheses are omitted.

**Breaking changes**

A PR, introducing a breaking API change, needs to append a `!` after the type/scope.

### Example titles

```
feat(alma): add support for AlmaLinux
```

```
feat(vuln)!: delete the existing CLI flag
```

```
fix(oracle): handle advisories with ksplice versions
```

```
docs(misconf): add comparison with Conftest and TFsec
```

```
chore(deps): bump go.uber.org/zap from 1.19.1 to 1.20.0
```

**NOTE**: please do not use `chore(deps): update fanal` and something like that if you add new features or fix bugs in Trivy-related projects.
The PR title should describe what the PR adds or fixes even though it just updates the dependency in Trivy.

## Commits


## Understand where your pull request belongs

Trivy is composed of several repositories that work together:

- [Trivy](https://github.com/aquasecurity/trivy) is the client-side, user-facing, command line tool.
- [vuln-list](https://github.com/aquasecurity/vuln-list) is a vulnerability database, aggregated from different sources, and normalized for easy consumption. Think of this as the "server" side of the trivy command line tool. **There should be no pull requests to this repo**
- [vuln-list-update](https://github.com/aquasecurity/vuln-list-update) is the code that maintains the vuln-list database.
- [trivy-db](https://github.com/aquasecurity/trivy-db) maintains the vulnerability database pulled by Trivy CLI.
