Godocs

Linking to Godocs

As mentioned in Documentation Guidelines, you can use the :godoc: role, the :atc-godoc: role, and the :to-godoc: role to link to Godocs from the ATC documentation.

Keeping pkg.go.dev from hiding the Apache Traffic Control Godocs

If less than 75% of ATC’s LICENSE file contains OSS licenses according to pkg.go.dev license detection system pkg.go.dev will hide all of ATC’s Godocs for that particular ATC version, saying “Documentation not displayed due to license restrictions.”. Example: https://pkg.go.dev/github.com/apache/trafficcontrol@v5.1.0+incompatible/lib/go-tc

When listing a dependency in the LICENSE file as part of bundling a new dependency, make sure that the license “pointer” adheres to this format:

#128 The atc-dependency.lre license exception from golang.org/x/pkgsite
This product bundles __4__, which
(( is || are ))
available under
(( a || an ))
(( Apache-2.0 || BSD-2-Clause || BSD-3-Clause || MIT ))
license.
__15__
(( /* || .css || .js || .scss ))
(( ./licenses/__4__ || ./vendor/__16__/LICENSE
(( .libyaml || .md || .txt ))??
))
Refer to the above license for the full text.

Example:

#129 An example of a bundled dependency license pointer
This product bundles go-acme/lego, which is available under an MIT license.
@vendor/github.com/go-acme/lego/*
./vendor/github.com/go-acme/lego/LICENSE
Refer to the above license for the full text.

The ATC repository includes a GitHub Actions workflorkflow (.github/workflows/license-file-coverage.yml) to verify that changes to the LICENSE file will not result in pkg.go.dev hiding the Apache Traffic Control Godocs.