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.