Skip to content

Commit

Permalink
docs(go): formattings
Browse files Browse the repository at this point in the history
  • Loading branch information
@annaowens
annaowens committed Sep 29, 2023
1 parent 8f6d619 commit 03095cb
Showing 1 changed file with 88 additions and 84 deletions.
172 changes: 88 additions & 84 deletions docs/detectors/go.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,43 +4,41 @@

Go detection runs when one of the following files is found in the project:

- `go.mod` or `go.sum`
- `go.mod` or `go.sum`

## Default Detection strategy

Default Go detection depends on the following to successfully run:

- Go v1.11+.
- Go v1.11+.

Full dependency graph generation is supported if Go v1.11+ is present
on the build agent. If no Go v1.11+ is present, fallback detection
strategy is performed.

Go detection is performed by parsing output from executing
[go list -mod=readonly -m -json all](1). To generate the graph, the command
[go mod graph](2) is executed. This only adds edges between the components
Go detection is performed by parsing output from executing
[go list -mod=readonly -m -json all](1). To generate the graph, the command
[go mod graph](2) is executed. This only adds edges between the components
that were already registered by `go list`.

## Fallback Detection strategy

The fallback detections trategy is known to overreport (see the
[known limitations](#known-limitations)). Read through the
The fallback detections trategy is known to overreport (see the
[known limitations](#known-limitations)). Read through the
[troubleshooting section](#troubleshooting-failures-to-run-the-default-go-detection-strategy)
for tips on how to ensure that the newer, more accurate default
detection strategy runs successfully.
for tips on how to ensure that the newer, more accurate default
detection strategy runs successfully.

To force the fallback detection strategy, set the environment
To force the fallback detection strategy, set the environment
variable: `DisableGoCliScan=true`

### `go.mod` before go 1.17

Go detection is performed by parsing any `go.mod` or `go.sum` found
under the scan directory.

Only root dependency information is generated in the fallback detection
strategy. The full graph is not detected. Given a dependency tree `A->B->C`,
only `A`, `C`'s root dependency, is detected.

Only root dependency information is generated in the fallback detection
strategy. The full graph is not detected.

### `go.mod` after 1.17

Expand All @@ -51,96 +49,102 @@ dependencies, including transitive ones. [^3]
Similarly, no graph is generated.

## Troubleshooting failures to run the default Go detection strategy
The fallback detection strategy is known to overreport by nature of
parsing `go.sum` files which contain historical component information.

If you are experiencing overdetection from `go.sum` files or have
otherwise been made aware that you are using the fallback Go detection
strategy, search Component Detection output for the following to determine
what action is needed:

| CD output | Solution |
| --------------------------------------------- | ---------------------------------------------------------------------- |
| `Go CLI was not found in the system` | [Ensure that Go v1.17+ is installed](#ensure-that-go-v117-is-installed-on-the-build-agent) |
| `#[error]Go CLI command "go list -m -json all" failed with error:` | [Resolve `go list` errors](#resolve-go-list-errors) |
| `Go cli scan was manually disabled, fallback strategy performed.` | [Remove the `DisableGoCliScan` environment variable](#remove-the-disablegocliscan-environment-variable) |
| _Timeouts in Go detection_ | [Fetch Go modules](#fetch-go-modules-before-the-component-detection-build-task-runs) |

The fallback detection strategy is known to overreport by nature of
parsing `go.sum` files which contain historical component information.

If you do not believe that Go is used in your project but Go detection is running,
If you are experiencing overdetection from `go.sum` files or have
otherwise been made aware that you are using the fallback Go detection
strategy, search Component Detection output for the following to determine
what action is needed:

| CD output | Solution |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `Go CLI was not found in the system` | [Ensure that Go v1.17+ is installed](#ensure-that-go-v117-is-installed-on-the-build-agent) |
| `#[error]Go CLI command "go list -m -json all" failed with error:` | [Resolve `go list` errors](#resolve-go-list-errors) |
| `Go cli scan was manually disabled, fallback strategy performed.` | [Remove the `DisableGoCliScan` environment variable](#remove-the-disablegocliscan-environment-variable) |
| _Timeouts in Go detection_ | [Fetch Go modules](#fetch-go-modules-before-the-component-detection-build-task-runs) |

If you do not believe that Go is used in your project but Go detection is running,
it is likely that you need to [clean up extraneous build files](#clean-up-extraneous-build-files).

### Ensure that Go v1.17+ is installed on the build agent
Install Go CLI tools v1.17+ and ensure that it is available at the
Component Detection step.

If Go CLI tools are installed in a prior build step but
Component Detection is not finding them, ensure that they
are not cleaned up or installed inside a container.
Install Go CLI tools v1.17+ and ensure that it is available at the
Component Detection step.

If Go CLI tools are installed in a prior build step but
Component Detection is not finding them, ensure that they
are not cleaned up or installed inside a container.

### Resolve `go list` errors.
### Resolve `go list` errors.

Errors are logged in the Component Detection build task output and begin with
`#[error]Go CLI command "go list -m -json all" failed with error:`. These errors
are typically caused by version resolution problems or incorrectly formatted `go.mod`
files.
Errors are logged in the Component Detection build task output and begin with
`#[error]Go CLI command "go list -m -json all" failed with error:`. These errors
are typically caused by version resolution problems or incorrectly formatted `go.mod`
files.

### Remove the `DisableGoCliScan` environment variable

The variable should not be set or should be set to `false`.

### Fetch Go modules before the Component Detection build task runs.
If modules are not fetched, `go list` will pull the modules and may
negatively impact performance at detection time.
### Fetch Go modules before the Component Detection build task runs.

If modules are not fetched, `go list` will pull the modules and may
negatively impact performance at detection time.

If you are still experiencing timouts, the fallback strategy might be more
appropriate for your project:

If you are still experiencing timouts, the fallback strategy might be more
appropriate for your project:
1. Set `DisableGoCli=true`.
1. Run `go mod tidy` to clean your `go.mod` and `go.sum`s to reduce overreporting.
1. Install Go v1.17+ to bypass go.sum scanning.

### Clean up extraneous build files
Go detection runs when a `go.sum` or `go.mod` file is encountered. If
you do not use Go in your project, search for the following in Component
Detection build output to find the paths to the Go files CD has detected.
Component Detection must be running in debug mode to see these logs:

`##[debug]Found Go.mod:` or

Go detection runs when a `go.sum` or `go.mod` file is encountered. If
you do not use Go in your project, search for the following in Component
Detection build output to find the paths to the Go files CD has detected.
Component Detection must be running in debug mode to see these logs:

`##[debug]Found Go.mod:` or
`##[debug]Found Go.sum:`

When you have found the affected files, you may:
When you have found the affected files, you may:

1. Delete the files if they exist but are not necessary in your project.
2. Add a clean-up step to your build to remove the files if they are
generated prior to the Component Detection build step but are not related
to your project.
3. [Exclude the directory](../detector-arguments.md) if it should not be scanned by Component
Detection.
2. Add a clean-up step to your build to remove the files if they are
generated prior to the Component Detection build step but are not related
to your project.
3. [Exclude the directory](../detector-arguments.md) if it should not be scanned by Component
Detection.

## Known limitations

- If the default strategy is used and go modules are not present in
the system before the detector is executed, the go cli will fetch all
modules to generate the dependency graph. This will incur additional
detector time execution.
- If the default strategy is used and go modules are not present in
the system before the detector is executed, the go cli will fetch all
modules to generate the dependency graph. This will incur additional
detector time execution.

- Dev dependency tagging is not supported.
- Dev dependency tagging is not supported.

- Go detection will fallback if no Go v1.11+ is present.
- Go detection will fallback if no Go v1.11+ is present.

- (Prior to Go 1.17) Due to the nature of `go.sum` containing
references for all dependencies, including historical,
no-longer-needed dependencies; the fallback strategy can result in
over detection. Executing [go mod
tidy](https://go.dev/ref/mod#go-mod-tidy) before detection via the
fallback strategy is encouraged.
- (Prior to Go 1.17) Due to the nature of `go.sum` containing
references for all dependencies, including historical,
no-longer-needed dependencies; the fallback strategy can result in
over detection. Executing [go mod
tidy](https://go.dev/ref/mod#go-mod-tidy) before detection via the
fallback strategy is encouraged.

- Some legacy dependencies may report stale transitive dependencies in
their manifests, in this case you can remove them safely from your
binaries by using [exclude
directive](https://go.dev/doc/modules/gomod-ref#exclude).
- Some legacy dependencies may report stale transitive dependencies in
their manifests, in this case you can remove them safely from your
binaries by using [exclude
directive](https://go.dev/doc/modules/gomod-ref#exclude).

## Environment Variables

If the environment variable `DisableGoCliScan` is set to `true`, the
If the environment variable `DisableGoCliScan` is set to `true`, the
Go detector forcibly executes the [fallback strategy](#fallback-detection-strategy).

## Go Overview
Expand Down Expand Up @@ -168,20 +172,20 @@ of Go's module system.[^4] It serves several crucial purposes:
Dependencies are listed with their module paths and version
constraints.

```
go module example.com/myproject
```
go module example.com/myproject
go 1.17
go 1.17
require (
github.com/somepackage v1.2.3 golang.org/x/someotherpackage v0.4.0
)
require (
github.com/somepackage v1.2.3 golang.org/x/someotherpackage v0.4.0
)
```
```
Here, `github.com/somepackage` and `golang.org/x/someotherpackage`
are declared as project dependencies with specific version
constraints.
Here, `github.com/somepackage` and `golang.org/x/someotherpackage`
are declared as project dependencies with specific version
constraints.
3. **Semantic Versioning**: Go uses Semantic Versioning (Semver) to
specify version constraints for dependencies. You can specify
Expand Down Expand Up @@ -342,7 +346,7 @@ The main change for the go detector was not in the parsing of the
go.mod files, but rather simply filtering `go.sum` files if an
adjacent `go.mod` file specified a version higher than 1.17.
[1]: https://go.dev/ref/mod#go-list-m
[1]: https://go.dev/ref/mod#go-list-m
[2]: https://go.dev/ref/mod#go-mod-graph
[3]: https://go.dev/doc/modules/gomod-ref#go-notes
[4]: https://go.dev/doc/modules/gomod-ref
Expand Down

0 comments on commit 03095cb

Please sign in to comment.