From 2d4ab0b4f14b14fbec2954945a57524099472041 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 1/31] golang: update golang path --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index c1969d9..4836dae 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -1,12 +1,12 @@ = Golang Packaging Guidelines -:last-reviewed: 2019-06-19 +:last-reviewed: 2025-07-17 This document details best practices for packaging Golang packages. Most of it is automated by an extensive use of macros. == go2rpm -https://pagure.io/GoSIG/go2rpm/[go2rpm] is tool that automates many of these steps. +https://gitlab.com/fedora/sigs/go/go2rpm[go2rpm] is tool that automates many of these steps. It is advisable to try `+go2rpm import_path+` first before attempting to write a SPEC by hand. From 8f792ce1360ef27223524e93f5ed2ace305982ee Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 2/31] golang: update go2rpm example command --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 4836dae..c9f3d17 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -7,7 +7,7 @@ is automated by an extensive use of macros. == go2rpm https://gitlab.com/fedora/sigs/go/go2rpm[go2rpm] is tool that automates many of these steps. -It is advisable to try `+go2rpm import_path+` first +It is advisable to try `+go2rpm --name NAME --profile vendor IMPORT_PATH+` first before attempting to write a SPEC by hand. == Import Path From 94800725ddd5791b03183966b6c8d45bc3e94df4 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 3/31] golang: update goipath note In modern Go projects, go.mod is now almost always present and lists the canonical import path. Also, the point about changing the import path later is no longer relevant now that only application packages whose Names follow the standard Fedora Naming Guidelines (and not the old Golang version that was based on import paths) are allowed. --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index c9f3d17..8bbb607 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -26,17 +26,11 @@ value. [NOTE] ==== -*Take the time to identify it accurately.* Changing it later will be -inconvenient. +*Take the time to identify it accurately.* * it may differ from the repository URL; * generally, the correct value will be the one used by the project in its - documentation, coding examples, and build assertions; -* use the gopkg import path for all code states when a project uses it. - -If upstream confused itself after multiple forks and renamings, you will need -to fix references to past names in the Go source files, unit tests included. -Perform this fixing in `+%prep+`. + `+go.mod+` file; ==== == Naming From b26cdbc3efe53f3b9f8a1f430ae9378c9615dcf7 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 4/31] golang: add note about old guidelines At some point, once there are no more golang `-devel` packages in Fedora, we can remove this admonition and the copy of the old Guidelines. --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 8bbb607..44c7e17 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -4,6 +4,19 @@ This document details best practices for packaging Golang packages. Most of it is automated by an extensive use of macros. + +[NOTE] +==== +:vendored-change: https://fedoraproject.org/wiki/Changes/GolangPackagesVendoredByDefault + +The xref:Golang_old.adoc[previous version] of these Guidelines +involved creating separate `+-devel+` packages containing the Go source code +for each library dependency. +As of {vendored-change}[Changes/GolangPackagesVendoredByDefault], +new Go packages MUST be built with vendored dependencies, +as outlined in the current version of the Guidelines. +==== + == go2rpm https://gitlab.com/fedora/sigs/go/go2rpm[go2rpm] is tool that automates many of these steps. diff --git a/guidelines/modules/ROOT/pages/Golang_old.adoc b/guidelines/modules/ROOT/pages/Golang_old.adoc new file mode 100644 index 0000000..ea01eb1 --- /dev/null +++ b/guidelines/modules/ROOT/pages/Golang_old.adoc @@ -0,0 +1,737 @@ += Non-vendored Golang Packaging Guidelines +:last-reviewed: 2019-06-19 + +This document details best practices for packaging Golang packages. Most of it +is automated by an extensive use of macros. + +== go2rpm + +https://pagure.io/GoSIG/go2rpm/[go2rpm] is tool that automates many of these steps. +It is advisable to try `+go2rpm import_path+` first +before attempting to write a SPEC by hand. + +== Import Path + +In Golang, packages are referenced by full URLs. Since this URL is +referenced in several places throughout the rpmspec, set the +base import path as a global define at the top of the spec file + +[source,rpm-spec] +---- +%global goipath github.com/kr/pretty +---- + +All macros, including package name, source URL, will be computed from this +value. + +[NOTE] +==== +*Take the time to identify it accurately.* Changing it later will be +inconvenient. + +* it may differ from the repository URL; +* generally, the correct value will be the one used by the project in its + documentation, coding examples, and build assertions; +* use the gopkg import path for all code states when a project uses it. + +If upstream confused itself after multiple forks and renamings, you will need +to fix references to past names in the Go source files, unit tests included. +Perform this fixing in `+%prep+`. +==== + +== Naming + +=== Source packages (src.rpm) + +* Golang source packages dedicated to providing code MUST be named after their + main import path. + This + process is automated by the `+%{goname}+` macro. + This macro will remove any capitalization, "go" keywords, and any duplication in + the import path. ++ +For example: ++ +-- +** the import path `+github.com/kr/pretty+` will become + `+golang-github-kr-pretty+` +** the import path `+github.com/DATA-DOG/go-txdb+` will become + `+golang-github-data-dog-txdb+` +** the import path `+github.com/gopherjs/gopherjs+` will become + `+golang-github-gopherjs+` +-- + ++ +The filename of spec MUST match the name of the package. + ++ +If you're not sure what will the name processed by the `+%{goname}+` macro be, +simply build the SRPM with: + + + fedpkg --release f31 srpm + ++ +The SRPM filename will be the one to use in your rpmspec and spec filename. + +* Source packages that provide a well-known application such as `+etcd+` + MUST be named after the application. + End users do not care about the language their applications are written in. But + do not name packages after an obscure utility binary that happens to be built by + the package. + + +==== Implementation: `+%{gorpmname}+` + +`+%gometa+` uses the `+%{gorpmname}+` macro to compute the main `+%{goname}+` +from `+%{goipath}+`. + +[NOTE] +==== +*`+%{gorpmname}+` can produce collisions* + +`+%{gorpmname}+` tries to compute human-friendly and rpm-compatible naming from +Go import paths. It simplifies them, removing redundancies and common +qualifiers. +As a result it is possible for two different import paths to produce the same +result. In that case, feel free to adjust this result manually to avoid the +collision. +==== + +=== Go code packages: `+%{goname}-devel+` +==== In a source package dedicated to providing Go code + +Packages that ship Go code in `+%{goipath}+` should be named +`+%{goname}-devel+`. +If your source package is already named `+%{goname}+` then: + +[source,rpm-spec] +---- +%package devel +[…] +%description devel +[…] +%files devel -f devel.file-list +---- + +This has been automated by the `+%{gopkg}+` and `+%{gopdevelkg}+` macros +described in the <> section below. + +==== In a another kind of source package + +If your source package is named something other than `+%{goname}+`, you SHOULD +use: + +[source,rpm-spec] +---- +%package -n %{goname}-devel +[…] +%description -n %{goname}-devel +[…] +%files -n %{goname}-devel -f devel.file-list +---- + +==== Separate code packages + +And, finally, if you wish to split the project Go code in multiple packages, +you can compute the corresponding names with: + +[source,rpm-spec] +---- +%global goname1 %gorpmname importpath1 +[…] +%package -n %{goname1}-devel +[…] +%description -n %{goname1}-devel +[…] +%files -n %{goname1}-devel -f %{goname1}.file-list +---- + +See also the xref:Golang_advanced.adoc#_dealing_with_cyclic_dependencies[Dealing with cyclic dependencies] +chapter. + +Do remember that for Go, each directory is a package. Never separate the .go +files contained in a single directory in different packages. + +==== Import path compatibility packages: `+%{compat-%{oldgoname}-devel}+` + +When a project can be referenced under multiple import paths, due to forks, +renamings, rehostings, organizational changes, or confusing project +documentation, it is possible to generate compatibility sub-packages to +connect code that uses one of the other import paths to the canonical one. + +The canonical import path SHOULD always be the one referenced in the project +documentation. +However some projects do not document import path changes, and rely on HTTPS +redirections (for example https://github.com/docker/docker → +https://github.com/moby/moby). +Such a redirection is a sufficient indicator the canonical import path has +changed (but please make sure with upstream). + +The new import path SHOULD be reflected in `+%{goipath}+` and compatibility +import paths MUST be declared with the `+goaltipaths+` macro: + +[source,rpm-spec] +---- +# A space-separated list of import paths to simulate. +%global goaltipaths +---- + +For example, the Go library `+github.com/Sirupsen/logrus+` was renamed +`+github.com/sirupsen/logrus+` and the documentation reflects this new import +path. +The packager SHOULD thus request a renaming of his package with a new import +path and a compatibility import path: + +[source,rpm-spec] +---- +%global goipath github.com/sirupsen/logrus +%global goaltipaths github.com/Sirupsen/logrus +---- + +If a project has gone through multiple rename, multiple compatibility import +paths can be specified as well. + +[NOTE] +==== +*Never defer renamings* + +Packagers MUST NOT use import path compatibility sub-packages to alias the +canonical import path to one of the previous namings. +Packagers MUST apply upstream renaming choices to the main `+%{goipath}+` spec +variable and +everything that derives from it, such as `+%{goname}+`. +Deferred renamings introduce friction with upstream and other packagers. +==== + +=== Go binary packages + +The binaries produced by your rpmspec SHOULD generally be listed in the main +package. However, if you want a more appropriate name or split binaries among +different packages, you can create additional binary subpackage. +Of course these package MUST NOT be noarch. + +For example we can create the package bbolt that will contain the binary +of the same name: + +[source,rpm-spec] +---- +%package -n bbolt +[…] +%description -n bbolt +[…] +%files -n bbolt +%license LICENSE +%{_bindir}/bbolt +---- + +== Versioning + +Many Go libraries do not use package versions or have regular releases and +are instead maintained in public version control. +In this case, follow the standard Fedora version conventions. This means that +often Go packages will have a version number of `+0+` and a release number like +`+0.10.20190319git27435c6+`. + +Most of this process is automated by macros so that you don't have to specify +the release number yourself. + +You first specify either a Version, tag or commit in the header. + +[source,rpm-spec] +---- +Version: +%global tag +%global commit +---- + +Then use the `+%gometa+` macro: + + %gometa + +The `+%gometa+` macro will automatically process the `+%{?dist}+` tag of the +`+Release+` field to take into account the commit if any. + +[NOTE] +==== +*Commits vs releases* + +You SHOULD package releases in priority. +Please reward the projects that make an effort to identify stable code states. +Only fall back to commits when the project does not release, when the release is +more than six months old, or if +you absolutely need one of the changes of a later commit. +In the later cases please inform the project politely of the reason you needed +to give up on their official releases. +Promoting releases is a way to limit incompatible commit hell. +==== + +== Go Language Architectures + +To compile on various architectures, golang and gcc-go compilers are available. +The golang compiler currently supports x86, x86_64, ppc64le, ppc64 (partially, +see upstream issue#13192), s390x, armv7hl and aarch64. + +Binaries SHOULD set ExclusiveArch so that we only attempt to build packages on +those arches. +This is now automatically added by the `+%gometa+` macro by leveraging the +`+%{golang_arches}+` macro. +Packagers can exclude `+%ix86+` +(see https://fedoraproject.org/wiki/Changes/EncourageI686LeafRemoval[Changes/EncourageI686LeafRemoval]) +by passing `+-f+` to the `+%gometa+` macro. +The `+-f+` flag tells `+%gometa+` to set `+ExclusiveArch: %{golang_arches_future}+` +instead of `+ExclusiveArch: %{golang_arches}+`. +`+%{golang_arches_future}+` includes the same architectures as +`+{golang_arches}+` sans `+%ix86+`. + +== Dependencies + +Packages MUST have `+BuildRequires: go-rpm-macros+`. + +This is automated by the `+%gometa+` macro. + + +=== Automatic Dependency Generation + +Most of the `+golang-*+` packages are source code only. +The `+*-devel+` sub-package that includes the source code should explicitly have +provides for the golang imports that it includes. +These provides are automatically deduced from import paths. + +Binary builds that include these imports will use them in BuildRequires, +for example: + +[source,rpm-spec] +---- +BuildRequires: golang(github.com/gorilla/context) +---- + +=== Bundled or unbundled + +At the moment golang projects packaged in Fedora SHOULD be unbundled by +default. It means projects are built from dependencies packaged in Fedora. + +For some project it can be reasonable to build from bundled dependencies. +Every bundling needs a proper justification. + + +=== BuildRequires + +The BuildRequires of the project contains the dependencies needed by unit tests +and binaries. + +You can gather them manually with `golist`. +For example:[[manual_br]] + +[source,bash] +---- + export GOPATH=/home/user/go + export GO111MODULE=off + export goipath="github.com/sirupsen/logrus" + go get $goipath + (sort -u | xargs -I{} echo "BuildRequires: golang({})") <<< "$( + golist --imported --package-path $goipath --skip-self + golist --imported --package-path $goipath --skip-self --tests + )" +---- + +outputs: + +[source] +---- +BuildRequires: golang(github.com/stretchr/testify/assert) +BuildRequires: golang(github.com/stretchr/testify/require) +BuildRequires: golang(golang.org/x/crypto/ssh/terminal) +---- + +If automatic buildrequires are available on your build target, you can use +the `+%go_generate_buildrequires+` macro in `+%generate_buildrequires+`: + +[source,rpm-spec] +---- +%generate_buildrequires +%go_generate_buildrequires +---- + +This macro leverages `+golist+` to gather build dependencies and tests +dependencies from the package source. + +== Testing + +You MUST run unit tests. +Due to the nature of Go development, especially the lack of use of semantic +versioning, API breakages are frequent.These need to be detected early and dealt +with upstream. + +Some tests may be disabled, especially the following kinds of unit tests are +incompatible with a secure build environment such as mock: + +* tests that call a remote server or API over the Internet, +* tests that attempt to reconfigure the system, +* tests that rely on a specific app running on the system, like a database + or syslog server. + +If a test is broken for some other reason, you can disable it the same way. +However, you SHOULD also report the problem upstream. Remember to trace in a +comment why each check was disabled, with links to eventual upstream problem +reports. + +== Walkthrough + +This chapter will present a typical Go spec file step by step, with comments +and explanations. + +=== Spec preamble: `+%{goipath}+`, `+%{forgeurl}+` and `+%gometa+` + +==== Usual case + +A Go package is identified by its import path. A Go spec file will therefore +start with the `+%{goipath}+` declaration. Don't get it wrong, it will control +the behaviour of the rest of the spec file. + + %global goipath google.golang.org/api + +If your package is hosted on a forge like GitHub, GitLab, Bitbucket or Pagure, +the hosting of the Go package will be automatically deduced from this variable +(typically by prefixing it with \https://). If that is not the case, you need +to declare explicitly the hosting URL with the `+%{forgeurl}+` macro + + %global forgeurl https://github.com/google/google-api-go-client + +The `+%{forgeurl}+` declaration is followed by either `+Version+`, `+commit+` or +`+tag+`. Use the combination that matches your use-case. + + %global commit 2dc3ad4d67ba9a37200c5702d36687a940df1111 + +[NOTE] +==== +You can also define `+date+` to override the mtime of the Source archive. +==== + +Now that we have all the required variables, the `+%gometa+` macro can be run + + %gometa + +It will compute and set the following variables if they are not already set by +the packager: + +goname:: an rpm-compatible package name derived from goipath +gosource:: a URL that can be used as SourceX: value +gourl:: a URL that can be used as URL: value + +It will delegate processing to the `+%forgemeta+` macro for: + +forgesource:: a URL that can be used as SourceX: value +forgesetupargs:: the correct arguments to pass to `+%setup+` for this source +used by `+%forgesetup+` and `+%forgeautosetup+` +archivename:: the source archive filename, without extensions +archiveext:: the source archive filename extensions, without leading dot +archiveurl:: the URL that can be used to download the source archive, +without renaming +topdir:: the source archive top directory (can be empty) +extractdir:: the source directory created inside `+%{_builddir}+` after +using `+%forgesetup+`, `+%forgeautosetup+` or `+%{forgesetupargs}+` +repo:: the repository name +owner:: the repository owner (if used by another computed variable) +shortcommit:: the commit hash clamping used by the forge, if any +scm:: the scm type, when packaging code snapshots: commits or tags +distprefix:: the prefix that needs adding to dist to trace non-release +packaging + +Most of the computed variables are both overridable and optional. + +Now we can add the remaining elements of the preamble. First, we can define a +multiline description block shared between subpackages: + +[source,rpm-spec] +---- +%global common_description %{expand: +cmux is a generic Go library to multiplex connections based on their payload. +Using cmux, you can serve gRPC, SSH, HTTPS, HTTP, Go RPC, and pretty much any +other protocol on the same TCP listener.} +---- + +This description MUST stay within 80 characters per line. + +[NOTE] +==== +If you need specific devel summary and description, you can also define: + +- `+%global godevelsummary+` +- `+%global godeveldescription+` +==== + +Then we MUST specify the license files that will be added to the devel +subpackages: + +`+%global golicenses+`: A space-separated list of shell globs matching the +project license files. + +And the possible documentation that SHOULD be included: + +`+%global godocs+`: A space-separated list of shell globs matching the project +documentation files. The Go rpm macros will pick up “.md” files by default +without this. + +[NOTE] +==== +You can also exclude files from `+%golicense+` and `+%godocs+` with: + +- `+%global golicensesex+` +- `+%global godocsex+` + +For example you might want to exclude `+INSTALL*+` files from `+%godocs+` as +these should not be provided. +==== + +=== Source package metadata: `+%{goname}+`, `+%{gourl}+` and `+%{gosource}+` + +We can declare the usual rpm headers, using the values computed by `+%gometa+`: + +[source,rpm-spec] +---- +Name: %{goname} +# If not set before +Version: +Release: 1%{?dist} +Summary: +License: +URL: %{gourl} +Source: %{gosource} +---- + +You can replace them with manual definitions. +For example, replace `+%{gourl}+` with the project homepage if it exists +separately from the repository URL. +Be careful to only replace `+%{go*}+` variables when it adds value to the +specfile and you understand the consequences. Otherwise you will just add +maintenance-intensive discrepancies in the distribution. + +=== BuildRequires + +If they are not automatically generated, you can now add the dependencies needed +for package building and unit testings: + +[source,rpm-spec] +---- +BuildRequires: golang(github.com/stretchr/testify/assert) +BuildRequires: golang(github.com/stretchr/testify/require) +BuildRequires: golang(golang.org/x/crypto/ssh/terminal) +---- + +See <> on how to get the BuildRequires list manually. + +=== Description + +Now add the main package description: + +[source,rpm-spec] +---- +%description +%{common_description} +---- + +=== Package metadata + +The process of declaring Go code packages has been automated with the +`+%{gopkg}+` macro. It will automatically generate a `+%package+` and +`+%description+` for all primary import paths and compatibility ones. + + %gopkg + +If you only need to generate Go devel subpackages without compat, use: + + %godevelpkg + +If necessary, you can then define one or multiple Go packages that will +contain the binaries being built. See the previous <> +section. + +=== %prep: `+%goprep+` , removing vendoring + +`+%goprep+` unpacks the Go source archives and creates the project “GOPATH” tree +used in the rest of the spec file. It removes vendored (bundled) code: +use the `+-k+` flag if you wish to keep this vendored code, and deal with the +consequences in the rest of the spec. + + %goprep + +`+%goprep+` only performs basic vendoring detection. It will miss inventive ways +to vendor code. Remove manually missed vendor code after the `+%goprep+` line. + +`+%goprep+` will not fix upstream sources for you. Since all the macro calls +that follow `+%goprep+` assume clean problem-free sources, you need to correct +them just after the `+%goprep+` line: + +* replace calls to deprecated import paths with their correct value +* patch code problems +* remove dead code (some upstreams deliberately ship broken source code in + the hope someone will get around to fix it) + +[NOTE] +==== +You SHOULD send fixes and problem reports upstream. Any patch used +SHOULD contain a link to an upstream bug report or merge request. At minimum, +a comment SHOULD be added to explain the patch rationale. +==== + +When you package an import path, that participates in a dependency loop, you +need bootstrapping to manage the initial builds: +https://docs.fedoraproject.org/en-US/packaging-guidelines/#bootstrapping +For Go code, that means your bootstrap section should: + +* remove unit tests that import other parts of the loop +* remove code that imports other parts of the loop + +Sometimes one can resolve dependency loops just by splitting specific +subdirectories in a separate -devel subpackage. See also +xref:Golang_advanced.adoc#_dealing_with_cyclic_dependencies[Dealing with cyclic dependencies]. + +=== Automatic BuildRequires + +If BuildRequires generator are supported, you can now add them to your build: + +[source,rpm-spec] +---- +%generate_buildrequires +%go_generate_buildrequires +---- + +=== Packaging a binary: the %build section + +If your package is a source package only, you can skip this `+%build+` section +entirely. + +Otherwise, you first need to identify manually the project parts that can be +built, and how to name the result. +Practically, it’s any directory containing a main() Go section. Nice projects +put those in `+cmd+` subdirectories named after the command that will be built, +which is what we will document here, but it is not a general rule. Sometimes the +whole `+%goipath+` builds as a single binary. + +[source,rpm-spec] +---- +for cmd in cmd/* ; do + %gobuild -o %{gobuilddir}/bin/$(basename $cmd) %{goipath}/$cmd +done +---- + +=== Installing the packages +==== Source package installation + +If you package a library, `+%gopkginstall+` will perform installation steps +for all primary import paths and compatibility ones. + + %gopkginstall + +If you only need to install Go devel subpackages without compat, use: + + %godevelinstall + +==== Binary package installation + +For binaries, we simply create the `+%{_bindir}+` directory in the buildroot +and install the commands as executable in it: + +[source,rpm-spec] +---- +install -m 0755 -vd %{buildroot}%{_bindir} +install -m 0755 -vp %{gobuilddir}/bin/* %{buildroot}%{_bindir}/ +---- + +[NOTE] +==== +Be wary of command names which might already exist in Fedora. If you have +any doubt, you can check if the command is already provided in Fedora: + +[source,shell] +---- +dnf whatprovides --disablerepo="*" --enablerepo=rawhide "/usr/bin/$cmd" +---- + +If this is the case, use your best judgment to rename the command. +==== + + +=== Running the unit tests: `+%gocheck+` + +As said before, you MUST run unit tests in `+%check+`: + + %gocheck + +However it is often necessary to disable some of them. You have 3 exclusion +flags to do so: + +* `+-d +`: exclude the files contained in `++` + non-recursively (subdirectories are not excluded) +* `+-t +`: exclude the files contained in `++` + recursively (subdirectories are excluded) +* `+-r +`: exclude files matching `++` + +Remember to document why a test has been disabled. + +=== %files declaration +==== When shipping source code + +The `+%gopkgfiles+` will process the file list produced in `+%install+` and add +the necessary license and documentation files: + + %gopkgfiles + +==== When shipping binaries + +Binaries are usually shipped in the main package. This package MUST include +legal files and documentation associated with those binaries. + +[source,rpm-spec] +---- +%files +%license LICENSE +%doc cmd/foo/README.md +%{_bindir}/* +---- + +== Examples + +=== Simple source package + +.golang-github-stretchr-testify.spec +[source,rpm-spec] +---- +include::{examplesdir}/golang/golang-github-stretchr-testify.spec[] +---- + +=== Handling package renames + +.golang-github-sirupsen-logrus.spec +[source,rpm-spec] +---- +include::{examplesdir}/golang/golang-github-sirupsen-logrus.spec[] +---- + +=== Simple binary package + +.golang-github-boltdb-bolt.spec +[source,rpm-spec] +---- +include::{examplesdir}/golang/golang-gopkg-square-jose-2.spec[] +---- + +== Additional resources + +=== Advanced uses cases + +** xref:Golang_advanced.adoc#_shipping_additional_files[Shipping additional files] +** xref:Golang_advanced.adoc#_additional_header_declarations[Additional header declarations] +** xref:Golang_advanced.adoc#_dealing_with_cyclic_dependencie[Dealing with cyclic dependencies] + +=== Additional annotated templates + +** xref:Golang_templates.adoc#_minimal_source_package[Minimal source package] +** xref:Golang_templates.adoc#_full_source_package[Full source package] +** xref:Golang_templates.adoc#_minimal_alternative_import_path[Minimal alternative import path] +** xref:Golang_templates.adoc#_full_alternative_import_path[Full alternative import path] +** xref:Golang_templates.adoc#_minimal_binary[Minimal binary] +** xref:Golang_templates.adoc#_full_binary[Full binary] +** xref:Golang_templates.adoc#_multi_package[Multi package] +** xref:Golang_templates.adoc#_manual_package_deprecated[Manual package (deprecated)] From 7648aa10facb8c8143d2a8e770bf842d86bfb580 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 5/31] golang: update Naming section --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 44c7e17..2946cbe 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -48,189 +48,11 @@ value. == Naming -=== Source packages (src.rpm) - -* Golang source packages dedicated to providing code MUST be named after their - main import path. - This - process is automated by the `+%{goname}+` macro. - This macro will remove any capitalization, "go" keywords, and any duplication in - the import path. -+ -For example: -+ --- -** the import path `+github.com/kr/pretty+` will become - `+golang-github-kr-pretty+` -** the import path `+github.com/DATA-DOG/go-txdb+` will become - `+golang-github-data-dog-txdb+` -** the import path `+github.com/gopherjs/gopherjs+` will become - `+golang-github-gopherjs+` --- - -+ -The filename of spec MUST match the name of the package. - -+ -If you're not sure what will the name processed by the `+%{goname}+` macro be, -simply build the SRPM with: - - - fedpkg --release f31 srpm - -+ -The SRPM filename will be the one to use in your rpmspec and spec filename. - -* Source packages that provide a well-known application such as `+etcd+` - MUST be named after the application. - End users do not care about the language their applications are written in. But - do not name packages after an obscure utility binary that happens to be built by - the package. - - -==== Implementation: `+%{gorpmname}+` - -`+%gometa+` uses the `+%{gorpmname}+` macro to compute the main `+%{goname}+` -from `+%{goipath}+`. - -[NOTE] -==== -*`+%{gorpmname}+` can produce collisions* - -`+%{gorpmname}+` tries to compute human-friendly and rpm-compatible naming from -Go import paths. It simplifies them, removing redundancies and common -qualifiers. -As a result it is possible for two different import paths to produce the same -result. In that case, feel free to adjust this result manually to avoid the -collision. -==== - -=== Go code packages: `+%{goname}-devel+` -==== In a source package dedicated to providing Go code - -Packages that ship Go code in `+%{goipath}+` should be named -`+%{goname}-devel+`. -If your source package is already named `+%{goname}+` then: - -[source,rpm-spec] ----- -%package devel -[…] -%description devel -[…] -%files devel -f devel.file-list ----- - -This has been automated by the `+%{gopkg}+` and `+%{gopdevelkg}+` macros -described in the <> section below. - -==== In a another kind of source package - -If your source package is named something other than `+%{goname}+`, you SHOULD -use: - -[source,rpm-spec] ----- -%package -n %{goname}-devel -[…] -%description -n %{goname}-devel -[…] -%files -n %{goname}-devel -f devel.file-list ----- - -==== Separate code packages - -And, finally, if you wish to split the project Go code in multiple packages, -you can compute the corresponding names with: - -[source,rpm-spec] ----- -%global goname1 %gorpmname importpath1 -[…] -%package -n %{goname1}-devel -[…] -%description -n %{goname1}-devel -[…] -%files -n %{goname1}-devel -f %{goname1}.file-list ----- - -See also the xref:Golang_advanced.adoc#_dealing_with_cyclic_dependencies[Dealing with cyclic dependencies] -chapter. - -Do remember that for Go, each directory is a package. Never separate the .go -files contained in a single directory in different packages. - -==== Import path compatibility packages: `+%{compat-%{oldgoname}-devel}+` - -When a project can be referenced under multiple import paths, due to forks, -renamings, rehostings, organizational changes, or confusing project -documentation, it is possible to generate compatibility sub-packages to -connect code that uses one of the other import paths to the canonical one. - -The canonical import path SHOULD always be the one referenced in the project -documentation. -However some projects do not document import path changes, and rely on HTTPS -redirections (for example https://github.com/docker/docker → -https://github.com/moby/moby). -Such a redirection is a sufficient indicator the canonical import path has -changed (but please make sure with upstream). - -The new import path SHOULD be reflected in `+%{goipath}+` and compatibility -import paths MUST be declared with the `+goaltipaths+` macro: - -[source,rpm-spec] ----- -# A space-separated list of import paths to simulate. -%global goaltipaths ----- - -For example, the Go library `+github.com/Sirupsen/logrus+` was renamed -`+github.com/sirupsen/logrus+` and the documentation reflects this new import -path. -The packager SHOULD thus request a renaming of his package with a new import -path and a compatibility import path: - -[source,rpm-spec] ----- -%global goipath github.com/sirupsen/logrus -%global goaltipaths github.com/Sirupsen/logrus ----- - -If a project has gone through multiple rename, multiple compatibility import -paths can be specified as well. - -[NOTE] -==== -*Never defer renamings* - -Packagers MUST NOT use import path compatibility sub-packages to alias the -canonical import path to one of the previous namings. -Packagers MUST apply upstream renaming choices to the main `+%{goipath}+` spec -variable and -everything that derives from it, such as `+%{goname}+`. -Deferred renamings introduce friction with upstream and other packagers. -==== - -=== Go binary packages - -The binaries produced by your rpmspec SHOULD generally be listed in the main -package. However, if you want a more appropriate name or split binaries among -different packages, you can create additional binary subpackage. -Of course these package MUST NOT be noarch. - -For example we can create the package bbolt that will contain the binary -of the same name: - -[source,rpm-spec] ----- -%package -n bbolt -[…] -%description -n bbolt -[…] -%files -n bbolt -%license LICENSE -%{_bindir}/bbolt ----- +New Golang library packages are no longer allowed, +so all Golang packages are user-facing applications that MUST be named +according to the standard Naming Guidelines. +In particular, vendored Go packages MUST NOT have a `+golang-+` prefix, +unless that is part of the upstream name of the project. == Versioning From 9bb1a1c00558bbf3e07a22d87ace5ffd2b992cad Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 6/31] golang: adjust forge macros usage I added TODOs for some other things I still need to think about. I replaced the examples with Docker that includes an application instead of a library that should no longer be packaged. --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 2946cbe..2931a74 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -205,6 +205,8 @@ However, you SHOULD also report the problem upstream. Remember to trace in a comment why each check was disabled, with links to eventual upstream problem reports. +// TODO(gotmax23): Consider more thoroughly refactoring of this section. +// This should be written like a Guidelines document, not a tutorial. == Walkthrough This chapter will present a typical Go spec file step by step, with comments @@ -214,27 +216,50 @@ and explanations. ==== Usual case +// TODO(gotmax23): The forge macros remain coupled with the Go macros. +// Some people have "opinions" about that. +// Go packagers are used to them and go2rpm relies on the forge macros +// integration when generating specfiles and downloading sources. +// It makes sense to use them since there is no Go package registry; it's just +// git (and the Go Proxy on top of it). +// I added this NOTE here, but it should probably be moved to the bottom if +// it's kept at all. +// At least, detailed documentation about the different forge macros should +// probably be moved somewhere else. +[NOTE] +==== +Historically, all Go packages have used a custom flavor of the Forge macros +that handles versioning and sets up the appropriate `+$GOPATH+` structure +for Go packages. +// Link to the gomodulesmode of the guidelines +Packages that enable Go modules mode and don't use `+%gocheck+` may opt-out of +using `+%gometa+` and `+%goprep+` and handle `+Source+` definitions and +`+%autosetup+` invocations manually. +==== + A Go package is identified by its import path. A Go spec file will therefore start with the `+%{goipath}+` declaration. Don't get it wrong, it will control the behaviour of the rest of the spec file. - %global goipath google.golang.org/api + %global goipath github.com/docker/docker If your package is hosted on a forge like GitHub, GitLab, Bitbucket or Pagure, the hosting of the Go package will be automatically deduced from this variable (typically by prefixing it with \https://). If that is not the case, you need to declare explicitly the hosting URL with the `+%{forgeurl}+` macro - %global forgeurl https://github.com/google/google-api-go-client + %global forgeurl https://github.com/moby/moby + +The `+%{forgeurl}+` declaration is followed by either `+Version+`, `+%commit+` or +`+%tag+`. Use the combination that matches your use-case. -The `+%{forgeurl}+` declaration is followed by either `+Version+`, `+commit+` or -`+tag+`. Use the combination that matches your use-case. + Version: 28.0.0 - %global commit 2dc3ad4d67ba9a37200c5702d36687a940df1111 [NOTE] ==== -You can also define `+date+` to override the mtime of the Source archive. +You MUST set `+%date+` in the `+YYYYMMDD+` format that corresponds to the commit +when using the `+%commit+` macro. ==== Now that we have all the required variables, the `+%gometa+` macro can be run From 601098371b0ec525227e17caeb5d981575ba5b3b Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 7/31] wip golang: quick passthrough to remove irrelevant sections --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 2931a74..31fc644 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -119,78 +119,20 @@ Packages MUST have `+BuildRequires: go-rpm-macros+`. This is automated by the `+%gometa+` macro. - -=== Automatic Dependency Generation - -Most of the `+golang-*+` packages are source code only. -The `+*-devel+` sub-package that includes the source code should explicitly have -provides for the golang imports that it includes. -These provides are automatically deduced from import paths. - -Binary builds that include these imports will use them in BuildRequires, -for example: - -[source,rpm-spec] ----- -BuildRequires: golang(github.com/gorilla/context) ----- +// TODO: go-vendor-tools === Bundled or unbundled -At the moment golang projects packaged in Fedora SHOULD be unbundled by -default. It means projects are built from dependencies packaged in Fedora. - -For some project it can be reasonable to build from bundled dependencies. -Every bundling needs a proper justification. +// TODO: Update === BuildRequires -The BuildRequires of the project contains the dependencies needed by unit tests -and binaries. - -You can gather them manually with `golist`. -For example:[[manual_br]] - -[source,bash] ----- - export GOPATH=/home/user/go - export GO111MODULE=off - export goipath="github.com/sirupsen/logrus" - go get $goipath - (sort -u | xargs -I{} echo "BuildRequires: golang({})") <<< "$( - golist --imported --package-path $goipath --skip-self - golist --imported --package-path $goipath --skip-self --tests - )" ----- - -outputs: - -[source] ----- -BuildRequires: golang(github.com/stretchr/testify/assert) -BuildRequires: golang(github.com/stretchr/testify/require) -BuildRequires: golang(golang.org/x/crypto/ssh/terminal) ----- - -If automatic buildrequires are available on your build target, you can use -the `+%go_generate_buildrequires+` macro in `+%generate_buildrequires+`: - -[source,rpm-spec] ----- -%generate_buildrequires -%go_generate_buildrequires ----- - -This macro leverages `+golist+` to gather build dependencies and tests -dependencies from the package source. +// TODO: Update == Testing You MUST run unit tests. -Due to the nature of Go development, especially the lack of use of semantic -versioning, API breakages are frequent.These need to be detected early and dealt -with upstream. Some tests may be disabled, especially the following kinds of unit tests are incompatible with a secure build environment such as mock: @@ -294,49 +236,7 @@ packaging Most of the computed variables are both overridable and optional. -Now we can add the remaining elements of the preamble. First, we can define a -multiline description block shared between subpackages: - -[source,rpm-spec] ----- -%global common_description %{expand: -cmux is a generic Go library to multiplex connections based on their payload. -Using cmux, you can serve gRPC, SSH, HTTPS, HTTP, Go RPC, and pretty much any -other protocol on the same TCP listener.} ----- - -This description MUST stay within 80 characters per line. - -[NOTE] -==== -If you need specific devel summary and description, you can also define: - -- `+%global godevelsummary+` -- `+%global godeveldescription+` -==== - -Then we MUST specify the license files that will be added to the devel -subpackages: - -`+%global golicenses+`: A space-separated list of shell globs matching the -project license files. - -And the possible documentation that SHOULD be included: - -`+%global godocs+`: A space-separated list of shell globs matching the project -documentation files. The Go rpm macros will pick up “.md” files by default -without this. - -[NOTE] -==== -You can also exclude files from `+%golicense+` and `+%godocs+` with: - -- `+%global golicensesex+` -- `+%global godocsex+` - -For example you might want to exclude `+INSTALL*+` files from `+%godocs+` as -these should not be provided. -==== +Now we can add the remaining elements of the preamble. === Source package metadata: `+%{goname}+`, `+%{gourl}+` and `+%{gosource}+` @@ -363,93 +263,25 @@ maintenance-intensive discrepancies in the distribution. === BuildRequires -If they are not automatically generated, you can now add the dependencies needed -for package building and unit testings: - -[source,rpm-spec] ----- -BuildRequires: golang(github.com/stretchr/testify/assert) -BuildRequires: golang(github.com/stretchr/testify/require) -BuildRequires: golang(golang.org/x/crypto/ssh/terminal) ----- - -See <> on how to get the BuildRequires list manually. - -=== Description - -Now add the main package description: - -[source,rpm-spec] ----- -%description -%{common_description} ----- - -=== Package metadata - -The process of declaring Go code packages has been automated with the -`+%{gopkg}+` macro. It will automatically generate a `+%package+` and -`+%description+` for all primary import paths and compatibility ones. - - %gopkg - -If you only need to generate Go devel subpackages without compat, use: - - %godevelpkg +// TODO: go-vendor-tools -If necessary, you can then define one or multiple Go packages that will -contain the binaries being built. See the previous <> -section. - -=== %prep: `+%goprep+` , removing vendoring +=== %prep: `+%goprep+` `+%goprep+` unpacks the Go source archives and creates the project “GOPATH” tree -used in the rest of the spec file. It removes vendored (bundled) code: -use the `+-k+` flag if you wish to keep this vendored code, and deal with the -consequences in the rest of the spec. +used in the rest of the spec file. It removes vendored (bundled) code in the +upstream archive. +// TODO: Link to section on security updates +Projects SHOULD regenerate vendored sources using `+go_vendor_tools+` +even if projects include a vendor directory. +This makes it easier to apply security updates. +Use the `+-k+` flag if you wish to keep any `+vendor+` directory included in +the upstream sourcess. %goprep -`+%goprep+` only performs basic vendoring detection. It will miss inventive ways -to vendor code. Remove manually missed vendor code after the `+%goprep+` line. - -`+%goprep+` will not fix upstream sources for you. Since all the macro calls -that follow `+%goprep+` assume clean problem-free sources, you need to correct -them just after the `+%goprep+` line: - -* replace calls to deprecated import paths with their correct value -* patch code problems -* remove dead code (some upstreams deliberately ship broken source code in - the hope someone will get around to fix it) - -[NOTE] -==== -You SHOULD send fixes and problem reports upstream. Any patch used -SHOULD contain a link to an upstream bug report or merge request. At minimum, -a comment SHOULD be added to explain the patch rationale. -==== - -When you package an import path, that participates in a dependency loop, you -need bootstrapping to manage the initial builds: -https://docs.fedoraproject.org/en-US/packaging-guidelines/#bootstrapping -For Go code, that means your bootstrap section should: - -* remove unit tests that import other parts of the loop -* remove code that imports other parts of the loop - -Sometimes one can resolve dependency loops just by splitting specific -subdirectories in a separate -devel subpackage. See also -xref:Golang_advanced.adoc#_dealing_with_cyclic_dependencies[Dealing with cyclic dependencies]. - === Automatic BuildRequires -If BuildRequires generator are supported, you can now add them to your build: - -[source,rpm-spec] ----- -%generate_buildrequires -%go_generate_buildrequires ----- +// TODO: go-vendor-tools === Packaging a binary: the %build section @@ -471,20 +303,8 @@ done ---- === Installing the packages -==== Source package installation - -If you package a library, `+%gopkginstall+` will perform installation steps -for all primary import paths and compatibility ones. - - %gopkginstall - -If you only need to install Go devel subpackages without compat, use: - - %godevelinstall -==== Binary package installation - -For binaries, we simply create the `+%{_bindir}+` directory in the buildroot +We simply create the `+%{_bindir}+` directory in the buildroot and install the commands as executable in it: [source,rpm-spec] @@ -493,20 +313,15 @@ install -m 0755 -vd %{buildroot}%{_bindir} install -m 0755 -vp %{gobuilddir}/bin/* %{buildroot}%{_bindir}/ ---- -[NOTE] -==== -Be wary of command names which might already exist in Fedora. If you have -any doubt, you can check if the command is already provided in Fedora: -[source,shell] ----- -dnf whatprovides --disablerepo="*" --enablerepo=rawhide "/usr/bin/$cmd" ----- +=== Installing and checking license files -If this is the case, use your best judgment to rename the command. -==== +// TODO: %go_vendor_license_install and %go_vendor_license_check +// TODO: We want to consider getting rid of %gocheck or rewriting it. +// See discussion in +// https://gitlab.com/fedora/sigs/go/go2rpm/-/merge_requests/22#note_2626091103. === Running the unit tests: `+%gocheck+` As said before, you MUST run unit tests in `+%check+`: @@ -525,67 +340,24 @@ flags to do so: Remember to document why a test has been disabled. === %files declaration -==== When shipping source code - -The `+%gopkgfiles+` will process the file list produced in `+%install+` and add -the necessary license and documentation files: - - %gopkgfiles - -==== When shipping binaries Binaries are usually shipped in the main package. This package MUST include legal files and documentation associated with those binaries. +// TODO: Explain vendor/modules.txt and bundled provides. [source,rpm-spec] ---- -%files -%license LICENSE -%doc cmd/foo/README.md -%{_bindir}/* +%files -f %{go_vendor_files} +%license vendor/modules.txt +%doc README.md +%{_bindir}/NAME ---- == Examples -=== Simple source package - -.golang-github-stretchr-testify.spec -[source,rpm-spec] ----- -include::{examplesdir}/golang/golang-github-stretchr-testify.spec[] ----- -=== Handling package renames - -.golang-github-sirupsen-logrus.spec -[source,rpm-spec] ----- -include::{examplesdir}/golang/golang-github-sirupsen-logrus.spec[] ----- - -=== Simple binary package - -.golang-github-boltdb-bolt.spec -[source,rpm-spec] ----- -include::{examplesdir}/golang/golang-gopkg-square-jose-2.spec[] ----- +// TODO: Updated examples == Additional resources -=== Advanced uses cases - -** xref:Golang_advanced.adoc#_shipping_additional_files[Shipping additional files] -** xref:Golang_advanced.adoc#_additional_header_declarations[Additional header declarations] -** xref:Golang_advanced.adoc#_dealing_with_cyclic_dependencie[Dealing with cyclic dependencies] - -=== Additional annotated templates - -** xref:Golang_templates.adoc#_minimal_source_package[Minimal source package] -** xref:Golang_templates.adoc#_full_source_package[Full source package] -** xref:Golang_templates.adoc#_minimal_alternative_import_path[Minimal alternative import path] -** xref:Golang_templates.adoc#_full_alternative_import_path[Full alternative import path] -** xref:Golang_templates.adoc#_minimal_binary[Minimal binary] -** xref:Golang_templates.adoc#_full_binary[Full binary] -** xref:Golang_templates.adoc#_multi_package[Multi package] -** xref:Golang_templates.adoc#_manual_package_deprecated[Manual package (deprecated)] +// TODO: Include links to go-vendor-tools documentations and other rewsources. From afeda9df9bc949e5aa8a16c61d067ade2a914c74 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 8/31] nav: update for new golang guidelines --- diff --git a/guidelines/modules/ROOT/nav.adoc b/guidelines/modules/ROOT/nav.adoc index ed12e57..e6ad7e8 100644 --- a/guidelines/modules/ROOT/nav.adoc +++ b/guidelines/modules/ROOT/nav.adoc @@ -45,8 +45,9 @@ ** xref:D.adoc[D] ** xref:Fortran.adoc[Fortran] ** xref:Golang.adoc[Golang] -*** xref:Golang_advanced.adoc[Advanced uses cases] -*** xref:Golang_templates.adoc[Additional annotated templates] +*** xref:Golang_old.adoc[Legacy guidelines] +**** xref:Golang_advanced.adoc[Advanced uses cases] +**** xref:Golang_templates.adoc[Additional annotated templates] ** xref:Haskell.adoc[Haskell] ** xref:Java.adoc[Java] *** xref:java-packaging-howto::index.adoc[Java Packaging HOWTO] From 219909a487612bfec83a33ec520f0bb1fc3f3c54 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 9/31] golang: update go2rpm section --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 31fc644..a0df17f 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -19,9 +19,16 @@ as outlined in the current version of the Guidelines. == go2rpm -https://gitlab.com/fedora/sigs/go/go2rpm[go2rpm] is tool that automates many of these steps. +https://gitlab.com/fedora/sigs/go/go2rpm[go2rpm] is a tool that automates many of these steps. It is advisable to try `+go2rpm --name NAME --profile vendor IMPORT_PATH+` first before attempting to write a SPEC by hand. +go2rpm will generate a Guidelines-compliant spec file, +download the upstream sources, +create a vendor archive using `+go_vendor_archive+` from Go Vendor Tools +and then use `+go_vendor_license+` to +scan the upstream sources and vendored dependencies for license files, +prompt the user for any licenses it could not detect, +and then generate a cumulative SPDX expression. == Import Path From 725e447d6b7535335b83afc7f98ea0f575d97473 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 10/31] golang: remove Versioning and expand Naming These Versioning details are only relevant to the peculiarities of Go libraries. The Naming changes seek to clarify the prohibition on golang-* prefixes. --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index a0df17f..df9565f 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -54,53 +54,22 @@ value. ==== == Naming +:rename-policy: xref:index.adoc#renaming-or-replacing-existing-packages New Golang library packages are no longer allowed, so all Golang packages are user-facing applications that MUST be named -according to the standard Naming Guidelines. +according to the standard xref:Naming.adoc[Naming Guidelines]. In particular, vendored Go packages MUST NOT have a `+golang-+` prefix, unless that is part of the upstream name of the project. -== Versioning - -Many Go libraries do not use package versions or have regular releases and -are instead maintained in public version control. -In this case, follow the standard Fedora version conventions. This means that -often Go packages will have a version number of `+0+` and a release number like -`+0.10.20190319git27435c6+`. - -Most of this process is automated by macros so that you don't have to specify -the release number yourself. - -You first specify either a Version, tag or commit in the header. - -[source,rpm-spec] ----- -Version: -%global tag -%global commit ----- - -Then use the `+%gometa+` macro: - - %gometa - -The `+%gometa+` macro will automatically process the `+%{?dist}+` tag of the -`+Release+` field to take into account the commit if any. - -[NOTE] -==== -*Commits vs releases* - -You SHOULD package releases in priority. -Please reward the projects that make an effort to identify stable code states. -Only fall back to commits when the project does not release, when the release is -more than six months old, or if -you absolutely need one of the changes of a later commit. -In the later cases please inform the project politely of the reason you needed -to give up on their official releases. -Promoting releases is a way to limit incompatible commit hell. -==== +This also applies to existing packages. +When converting a package with a `+golang-+` prefix to use vendored dependencies +that was created under the old guidelines, +the package MUST go through the {rename-policy}[package rename process]. +This guideline seeks to create a clear separation between packages created under +the old approach and the new vendored method +and to avoid cases where `+-devel+` subpackages are removed from existing `+golang-+` +packages and then merged back to stable branches. == Go Language Architectures From 73cd4f30339ffeda89d4a95fe6dab7ab44338189 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 11/31] golang: add section on compiler flags This guideline is not directly related to vendoring but was notably absent from the previous guidelines. --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index df9565f..60c96f5 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -89,6 +89,79 @@ instead of `+ExclusiveArch: %{golang_arches}+`. `+%{golang_arches_future}+` includes the same architectures as `+{golang_arches}+` sans `+%ix86+`. +== Go compiler flags + +:macros-go-compilers: https://gitlab.com/fedora/sigs/go/go-rpm-macros/-/blob/main/rpm/macros.d/macros.go-compilers-golang?ref_type=heads + +=== Preserve compiler flags + +Packages MUST preserve the Fedora golang compiler flags +by using the `+%gobuild+` macro or by passing the appropriate `+%gobuild_*flags+` macros to an upstream build script. + +[source, rpm-spec] +---- +# Using %gobuild +%gobuild -o %{gobuilddir}/bin/%{name} %{goipath} + +# Using a simple upstream build script +%make_build BUILD_OPTS=%{gobuild_baseflags_shescaped} + +# Using an upstream build script that provides separate options for ldflags +%make_build \ + BUILD_OPTS=%{gobuild_baseflags_shescaped} \ + GO_LDFLAGS=%{gobuild_ldflags_shescaped} +---- + +See the inline comments in {macros-go-compilers}[macros.go-compilers-golang] +for more information on passing the compiler flags to an upstream build script. + +[TIP] +==== +It is recommended to use the `+%gobuild+` macro if possible. +Some upstream build scripts may not provide a proper way to pass +additional flags to the compiler or have other issues that can be a source of bugs. +When using `+%gobuild+`, make sure to set the appropriate linker flags and build tags +as described below. +==== + +=== Passing additional flags + +Go supports passing additional linker flags +(for example, to enable `+--version+` functionality) +and build tags for conditional compilation. +When using an upstream build script, these may be set automatically. +Otherwise, you can set them manually. + +==== Linker flags + +In some cases, it may be necessary to pass additional flags to the Go linker. +This can be accomplished by setting the `+$GO_LDFLAGS+` environment variable +which will then be read by the macros. + +[source, rpm-spec] +---- +# The correct value to pass to -X differs between projects; this is an example. +GO_LDFLAGS="-X %{goipath}/internal.Version=%{version}" +---- + +Packages MUST NOT set Go linker flags using the `+$LDFLAGS+` environment variable. +This is supported for backwards compatibility, but it is deprecated. +`+$LDFLAGS+` should only be used for passing C linker flags. + +==== Build tags + +Go supports build tags to conditionally include or exclude code from the build. +To pass build tags to the Go compiler, set `+$GO_BUILDTAGS+` to a +space-separated list of tags. + +[source, rpm-spec] +---- +# These tags are just examples. Each project has its own. +GO_BUILDTAGS="systemd selinux" +---- + +Packages MUST NOT set Go tags using the `+$BUILDTAGS+` environment variable. + == Dependencies Packages MUST have `+BuildRequires: go-rpm-macros+`. From 01d0f2b6af479c684df5d80f8fdc70d658026b51 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 12/31] golang: add initial guidelines about vendored modules --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 60c96f5..1ab7662 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -170,14 +170,37 @@ This is automated by the `+%gometa+` macro. // TODO: go-vendor-tools -=== Bundled or unbundled +=== Vendored dependencies -// TODO: Update +:gvt-security: https://fedora.gitlab.io/sigs/go/go-vendor-tools/scenarios/#security-updates +Packages MUST vendor their Go module dependencies. +Packagers SHOULD use the `+go_vendor_archive+` command from Go Vendor Tools to +generate a reproducible vendor archive. +Packages that do not use Go Vendor Tools must include a script or other +standardized, documented procedure to download sources with +`go mod vendor` and reproducibly produce a tarball. +Packagers SHOULD regenerate vendor archives themselves, +even if upstreams include a vendor directory in their upstream sources. +// TODO: Potentially link to further guidelines about security updates. +This allows for easier {gvt-security}[security updates using Go Vendor Tools]. -=== BuildRequires +=== Bundled provides +:go_mod_vendor.attr: https://gitlab.com/fedora/sigs/go/go-rpm-macros/-/blob/main/rpm/fileattrs/go_mod_vendor.attr?ref_type=heads + +Packages MUST include `+bundled()+` Provides for all vendored Go modules. +This is handled automatically by a dependency generator. +Simply mark the `+vendor/modules.txt+` file with `+%license+` in `+%files+`, +and then the generator will scan the file and create the `+bundled()+` Provides. + +[source, rpm-spec] +---- +%license vendor/modules.txt +---- + +== Licensing -// TODO: Update +// TODO == Testing From fc876ebeade82c3b2adb6de9d6ddf432dcc37545 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 13/31] golang: spelling fixes --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 1ab7662..fac0e8f 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -253,7 +253,7 @@ using `+%gometa+` and `+%goprep+` and handle `+Source+` definitions and A Go package is identified by its import path. A Go spec file will therefore start with the `+%{goipath}+` declaration. Don't get it wrong, it will control -the behaviour of the rest of the spec file. +the behavior of the rest of the spec file. %global goipath github.com/docker/docker @@ -347,7 +347,7 @@ Projects SHOULD regenerate vendored sources using `+go_vendor_tools+` even if projects include a vendor directory. This makes it easier to apply security updates. Use the `+-k+` flag if you wish to keep any `+vendor+` directory included in -the upstream sourcess. +the upstream sources. %goprep @@ -432,4 +432,5 @@ legal files and documentation associated with those binaries. == Additional resources -// TODO: Include links to go-vendor-tools documentations and other rewsources. +// TODO: Include links to go-vendor-tools documentations and other resources. +- {gvt}[Go Vendor Tools documentation] From 6e94424fc4933c5a4c7e4cb697b5e505a4a68c56 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 14/31] golang: add TODO banner --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index fac0e8f..09431b0 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -1,5 +1,11 @@ = Golang Packaging Guidelines :last-reviewed: 2025-07-17 +:gvt: https://fedora.gitlab.io/sigs/go/go-vendor-tools/ + +//// +XXX: This document is a WIP and being updated according to +https://gitlab.com/fedora/sigs/go/go-vendor-tools/-/issues/76 +//// This document details best practices for packaging Golang packages. Most of it is automated by an extensive use of macros. From e2588254bd0f33fa21e8582a3bda9d684b4b99d6 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 15/31] golang: add core Go Vendor Tools guidelines --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 09431b0..51b4dff 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -181,7 +181,7 @@ This is automated by the `+%gometa+` macro. :gvt-security: https://fedora.gitlab.io/sigs/go/go-vendor-tools/scenarios/#security-updates Packages MUST vendor their Go module dependencies. -Packagers SHOULD use the `+go_vendor_archive+` command from Go Vendor Tools to +Packagers SHOULD use the `+go_vendor_archive+` command from {gvt}[Go Vendor Tools] to generate a reproducible vendor archive. Packages that do not use Go Vendor Tools must include a script or other standardized, documented procedure to download sources with @@ -191,10 +191,28 @@ even if upstreams include a vendor directory in their upstream sources. // TODO: Potentially link to further guidelines about security updates. This allows for easier {gvt-security}[security updates using Go Vendor Tools]. +Conventionally, `+Source0+` in the specfile is the primary archive, +and `+Source1+` is the vendor archive, +and the values are automatically filled in using the forge macros. + +[source, rpm-spec] +---- +Source0: %{forgesource} +# %%archivename is the basename as the archive provided +# by %%forgesource without the extension. +Source1: %{archivename}-vendor.tar.bz2 +# go-vendor-tools configuration generated by go2rpm +Source2: go-vendor-tools.toml +---- + +Then, simply run `+go_vendor_archive create .spec+` to create a +vendor tarball. + === Bundled provides :go_mod_vendor.attr: https://gitlab.com/fedora/sigs/go/go-rpm-macros/-/blob/main/rpm/fileattrs/go_mod_vendor.attr?ref_type=heads -Packages MUST include `+bundled()+` Provides for all vendored Go modules. +Packages MUST include `+bundled(golang(IMPORT_PATH)) = VERSION+` Provides for +all vendored Go modules. This is handled automatically by a dependency generator. Simply mark the `+vendor/modules.txt+` file with `+%license+` in `+%files+`, and then the generator will scan the file and create the `+bundled()+` Provides. @@ -206,7 +224,167 @@ and then the generator will scan the file and create the `+bundled()+` Provides. == Licensing -// TODO +:generate-go2rpm: https://fedora.gitlab.io/sigs/go/go-vendor-tools/scenarios/#generate-go2rpm +:manual-update: https://fedora.gitlab.io/sigs/go/go-vendor-tools/scenarios/#manual-update +:post_commands: https://fedora.gitlab.io/sigs/go/go-vendor-tools/config/#archive--post_commands +:metaPrefixes: https://github.com/golang/go/blob/ac94297758f3d83fca5ffa16cd179bb098bbd914/src/cmd/go/internal/modcmd/vendor.go#L398-L415 + + +Packages must follow the xref:LicensingGuidelines.adoc[Fedora Licensing Guidelines]. +For vendored Go packages, this means that the license files of the main +project as well as all of the vendored Go modules MUST be included in the package +and marked with `+%license++`. +Each vendored Go module MUST include a license file; +Go modules that are missing license files MUST NOT be included in vendored +archives until the licensing is clarified. + +Additionally, the package's `+License:+` tag MUST include a cumulative SPDX +expression encompassing both the main package and the vendored Go modules. + +In rare cases, `+go mod vendor+` may fail to download a project's license file, +even if it exists for the equivalent version in the upstream repository. +This is usually because of the license files have non-standard names or because +the licenses are installed in a subdirectory instead of the root of the module. +In the former case, `+go_vendor_archive+` MAY be configured using +{post_commands}[post_commands] to download the license file from the upstream +repository as a temporary measure, but packagers MUST report this to upstream +and ask it to rename the license file to +{metaPrefixes}[a format supported by `+go mod vendor+`]. +If the license file is included in the `+vendor+` directory but not in the root +directory of a module, the file should be copied to the root directory to satisfy +the Go Vendor Tools license checker. + + +== Licensing with Go Vendor Tools + +:licensing-config: https://fedora.gitlab.io/sigs/go/go-vendor-tools/config/#licensing +:manual-detection: https://fedora.gitlab.io/sigs/go/go-vendor-tools/scenarios/#manually-detecting-licenses + +{gvt}[Go Vendor Tools] provides the `+go_vendor_license+` command and macros +for determining the correct `+License:+` expression and installing license files. + +Packagers MUST run `+go_vendor_license report+` (either directly, through go2rpm, or +using the `+%go_vendor_license_check+` macro in a _local_ mock build) +and double check its output before uploading sources to the lookaside cache. +Any errors MUST be addressed. +If any part of the output is wrong, `+go_vendor_license+` 's behavior can be modifed +in {licensing-config}[the licensing section of the Go Vendor Tools config file]. + +Go Vendor Tools scans the upstream sources and vendored libraries for license files +and generates a cumulative SPDX expression. + +This document only outlines the standard usage of Go Vendor Tools needed to comply +with the Guidelines — consult the {gvt}[Go Vendor Tools documentation] for +details on advanced usage. +Packagers can follow the scenarios documentation to +{generate-go2rpm}[generate a new specfile with go2rpm] or +{manual-update}[update existing specfiles for new upstream versions] +to run `+go_vendor_license+` and make sure that the License is valid and +automatically update it if necessary before running a full build. + +[WARNING] +==== +While Go Vendor tools provide facilities to scan for licenses and generate SPDX +expressions, +it is still the packager's responsibility to perform a basic check of the +output and ensure adherence to the Fedora Licensing Guidelines, including +ensuring that all keys in the License tag are allowed licenses in Fedora, +before uploading any sources to the lookaside cache. + +If necessary, the license expression for individual files can be +overriden in the config file, {manual-detection}[as outlined in the scenarios documentation]. +==== + +=== go-vendor-tools.toml + +:config-reference: https://fedora.gitlab.io/sigs/go/go-vendor-tools/config/ + +Packages MUST include a `+go-vendor-tools.toml+` file to specify the license +detector backend and other configuration options. +See the {config-reference}[configuration reference] for more information. +The recommended approach is to use `+go2rpm+` that automatically creates +a valid `+go-vendor-tools.toml+`. +At least, all packages MUST have a minimal `+go-vendor-tools.toml+` that +specifies a license detector backend. + +[source,toml] +---- +[licensing] +detector = "askalono" +---- + +This file is used by the macros and is conventionally included in the specfile +as `+Source2:+`, just below the upstream archive and the +`+go_vendor_archive+`-generated tarball. +In this document, `+%{S:2}+` (expands to the path to `+Source2+`) will be used +to represent the path to the Go Vendor Tools config file. + + +=== Installing go-vendor-tools + +:go-vendor-license-buildrequires: https://fedora.gitlab.io/sigs/go/go-vendor-tools/man/rpm_macros/#go_vendor_license_buildrequires + +Packages that use the Go Vendor Tools macros MUST have `+BuildRequires: +go-vendor-tools+` and use the `+%go_vendor_license_buildrequires+` macro +to generate generate requirements needed for the selected license detector backend. + +[source,rpm-spec] +---- +BuildRequires: go-vendor-tools +---- + +[source,rpm-spec] +---- +%generate_buildrequires +%go_vendor_license_buildrequires -c %{S:2} +---- + +=== Installing licenses + +:go-vendor-license-install: https://fedora.gitlab.io/sigs/go/go-vendor-tools/man/rpm_macros/#go_vendor_license_install +:go-vendor-license-filelist: https://fedora.gitlab.io/sigs/go/go-vendor-tools/man/rpm_macros/#go_vendor_license_filelist + +// TODO: Should this be MUST or SHOULD? Installing all license files is a MUST +// (see the previous section), but should doing that _using GVT_ be a MUST? + +Packagers SHOULD use the +{go-vendor-license-install}[%go_vendor_license_install] macro to install +license files of the main project and all vendored Go modules. +By default, this macro will install the license files into main packages license directory. + +[source,rpm-spec] +---- +# Install into the main package's license directory +%go_vendor_license_install -c %{S:2} +---- + +Then, the macro will populate +{go-vendor-license-filelist}[%{go_vendor_license_filelist}] with a list of +files that can be passed to `+%files -f+`. + +[source,rpm-spec] +---- +%files -f %{go_vendor_license_filelist} +%license vendor/modules.txt +---- + +=== Checking licenses + +:go-vendor-license-check: https://fedora.gitlab.io/sigs/go/go-vendor-tools/man/rpm_macros/#go_vendor_license_check + +As stated, packagers MUST check licenses using Go Vendor Tools before uploading +sources to the lookaside cache. +Any errors raised by `+go_vendor_license+` MUST be addressed. + +As an additional measure, the +{go-vendor-license-check}[%go_vendor_license_check macro] runs the same license +scan as the `+go_vendor_license report+` command. +Packages SHOULD run `+go_vendor_license_check+` in `+%check+` so the package +build will fail if there are any license errors. +Go Vendor Tools scans the upstream sources and vendored libraries for license files +and generates a cummulative SPDX expression. +The command will error if any Go module is missing a license file. + == Testing @@ -225,10 +403,22 @@ However, you SHOULD also report the problem upstream. Remember to trace in a comment why each check was disabled, with links to eventual upstream problem reports. -// TODO(gotmax23): Consider more thoroughly refactoring of this section. -// This should be written like a Guidelines document, not a tutorial. +== Go modules mode + +CAUTION: TODO. Wait until we figure out `+%gocheck+`. + +== Security updates + +CAUTION: TODO. See notes in https://gitlab.com/fedora/sigs/go/go-vendor-tools/-/issues/76. + == Walkthrough +[CAUTION] +==== + TODO(gotmax23): Consider more thoroughly refactoring of the Walkthrough section. +This should be written like a Guidelines document, not a tutorial. +==== + This chapter will present a typical Go spec file step by step, with comments and explanations. @@ -339,10 +529,6 @@ Be careful to only replace `+%{go*}+` variables when it adds value to the specfile and you understand the consequences. Otherwise you will just add maintenance-intensive discrepancies in the distribution. -=== BuildRequires - -// TODO: go-vendor-tools - === %prep: `+%goprep+` `+%goprep+` unpacks the Go source archives and creates the project “GOPATH” tree @@ -357,9 +543,6 @@ the upstream sources. %goprep -=== Automatic BuildRequires - -// TODO: go-vendor-tools === Packaging a binary: the %build section @@ -392,11 +575,6 @@ install -m 0755 -vp %{gobuilddir}/bin/* %{buildroot}%{_bindir}/ ---- -=== Installing and checking license files - -// TODO: %go_vendor_license_install and %go_vendor_license_check - - // TODO: We want to consider getting rid of %gocheck or rewriting it. // See discussion in // https://gitlab.com/fedora/sigs/go/go2rpm/-/merge_requests/22#note_2626091103. @@ -422,10 +600,9 @@ Remember to document why a test has been disabled. Binaries are usually shipped in the main package. This package MUST include legal files and documentation associated with those binaries. -// TODO: Explain vendor/modules.txt and bundled provides. [source,rpm-spec] ---- -%files -f %{go_vendor_files} +%files -f %{go_vendor_license_filelist} %license vendor/modules.txt %doc README.md %{_bindir}/NAME @@ -438,5 +615,4 @@ legal files and documentation associated with those binaries. == Additional resources -// TODO: Include links to go-vendor-tools documentations and other resources. - {gvt}[Go Vendor Tools documentation] From a4f591547971d9ab69d602c12a373417303e5d0a Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 16/31] wip golang: make TODOs show up in the docs source This will make it easier for folks viewing the rendered preview to provide feedback. --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 51b4dff..3e749c8 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -2,10 +2,11 @@ :last-reviewed: 2025-07-17 :gvt: https://fedora.gitlab.io/sigs/go/go-vendor-tools/ -//// +[CAUTION] +==== XXX: This document is a WIP and being updated according to https://gitlab.com/fedora/sigs/go/go-vendor-tools/-/issues/76 -//// +==== This document details best practices for packaging Golang packages. Most of it is automated by an extensive use of macros. @@ -438,7 +439,7 @@ and explanations. // probably be moved somewhere else. [NOTE] ==== -Historically, all Go packages have used a custom flavor of the Forge macros +Historically, Go packages have used a custom flavor of the Forge macros that handles versioning and sets up the appropriate `+$GOPATH+` structure for Go packages. // Link to the gomodulesmode of the guidelines @@ -466,6 +467,8 @@ The `+%{forgeurl}+` declaration is followed by either `+Version+`, `+%commit+` o Version: 28.0.0 +// TODO: Update go2rpm template. +// See https://gitlab.com/fedora/sigs/go/go2rpm/-/merge_requests/25/commits. [NOTE] ==== You MUST set `+%date+` in the `+YYYYMMDD+` format that corresponds to the commit From b52b32dda45a0f019a916208be4f73fdeefe806f Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 17/31] Remove comment about extensive use of macros My goal with this and future changes to Go packaging is to avoid the overuse of magical macros, so let's reflect that here. --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 3e749c8..a1efec4 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -9,7 +9,7 @@ https://gitlab.com/fedora/sigs/go/go-vendor-tools/-/issues/76 ==== This document details best practices for packaging Golang packages. Most of it -is automated by an extensive use of macros. +is automated by macros. [NOTE] From 46d973bce32530214223ba2250880f1304df991a Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 18/31] golang: finalize new guidelines --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index a1efec4..7dfca0c 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -1,16 +1,9 @@ = Golang Packaging Guidelines -:last-reviewed: 2025-07-17 +:last-reviewed: 2025-10-15 :gvt: https://fedora.gitlab.io/sigs/go/go-vendor-tools/ -[CAUTION] -==== -XXX: This document is a WIP and being updated according to -https://gitlab.com/fedora/sigs/go/go-vendor-tools/-/issues/76 -==== - -This document details best practices for packaging Golang packages. Most of it -is automated by macros. +This document details best practices for packaging Golang packages. [NOTE] ==== @@ -39,27 +32,13 @@ and then generate a cumulative SPDX expression. == Import Path -In Golang, packages are referenced by full URLs. Since this URL is -referenced in several places throughout the rpmspec, set the -base import path as a global define at the top of the spec file +In Golang, packages are referenced by full URLs listed in the project's `+go.mod+` file. [source,rpm-spec] ---- %global goipath github.com/kr/pretty ---- -All macros, including package name, source URL, will be computed from this -value. - -[NOTE] -==== -*Take the time to identify it accurately.* - -* it may differ from the repository URL; -* generally, the correct value will be the one used by the project in its - `+go.mod+` file; -==== - == Naming :rename-policy: xref:index.adoc#renaming-or-replacing-existing-packages @@ -70,8 +49,8 @@ In particular, vendored Go packages MUST NOT have a `+golang-+` prefix, unless that is part of the upstream name of the project. This also applies to existing packages. -When converting a package with a `+golang-+` prefix to use vendored dependencies -that was created under the old guidelines, +When converting a package with a `+golang-+` prefix that was created under the +old guidelines to use vendored dependencies, the package MUST go through the {rename-policy}[package rename process]. This guideline seeks to create a clear separation between packages created under the old approach and the new vendored method @@ -148,12 +127,11 @@ which will then be read by the macros. [source, rpm-spec] ---- # The correct value to pass to -X differs between projects; this is an example. -GO_LDFLAGS="-X %{goipath}/internal.Version=%{version}" +export GO_LDFLAGS="-X %{goipath}/internal.Version=%{version}" ---- Packages MUST NOT set Go linker flags using the `+$LDFLAGS+` environment variable. This is supported for backwards compatibility, but it is deprecated. -`+$LDFLAGS+` should only be used for passing C linker flags. ==== Build tags @@ -164,20 +142,22 @@ space-separated list of tags. [source, rpm-spec] ---- # These tags are just examples. Each project has its own. -GO_BUILDTAGS="systemd selinux" +export GO_BUILDTAGS="systemd selinux" ---- Packages MUST NOT set Go tags using the `+$BUILDTAGS+` environment variable. -== Dependencies +== Macro dependencies -Packages MUST have `+BuildRequires: go-rpm-macros+`. +Packages MUST have `+BuildRequires: go-rpm-macros+` to pull in the Go macros and +compiler. This is automated by the `+%gometa+` macro. -// TODO: go-vendor-tools +Packages that use the `+%go_vendor_license_*+` macros MUST have +`+BuildRequires: go-vendor-tools+`. -=== Vendored dependencies +== Vendored dependencies :gvt-security: https://fedora.gitlab.io/sigs/go/go-vendor-tools/scenarios/#security-updates @@ -189,7 +169,6 @@ standardized, documented procedure to download sources with `go mod vendor` and reproducibly produce a tarball. Packagers SHOULD regenerate vendor archives themselves, even if upstreams include a vendor directory in their upstream sources. -// TODO: Potentially link to further guidelines about security updates. This allows for easier {gvt-security}[security updates using Go Vendor Tools]. Conventionally, `+Source0+` in the specfile is the primary archive, @@ -198,9 +177,9 @@ and the values are automatically filled in using the forge macros. [source, rpm-spec] ---- -Source0: %{forgesource} +Source0: %{gosource} # %%archivename is the basename as the archive provided -# by %%forgesource without the extension. +# by %%gosource without the extension. Source1: %{archivename}-vendor.tar.bz2 # go-vendor-tools configuration generated by go2rpm Source2: go-vendor-tools.toml @@ -227,14 +206,14 @@ and then the generator will scan the file and create the `+bundled()+` Provides. :generate-go2rpm: https://fedora.gitlab.io/sigs/go/go-vendor-tools/scenarios/#generate-go2rpm :manual-update: https://fedora.gitlab.io/sigs/go/go-vendor-tools/scenarios/#manual-update -:post_commands: https://fedora.gitlab.io/sigs/go/go-vendor-tools/config/#archive--post_commands +:post_commands: https://fedora.gitlab.io/sigs/go/go-vendor-tools/config/#archive--post_commands :metaPrefixes: https://github.com/golang/go/blob/ac94297758f3d83fca5ffa16cd179bb098bbd914/src/cmd/go/internal/modcmd/vendor.go#L398-L415 Packages must follow the xref:LicensingGuidelines.adoc[Fedora Licensing Guidelines]. For vendored Go packages, this means that the license files of the main project as well as all of the vendored Go modules MUST be included in the package -and marked with `+%license++`. +and marked with `+%license+`. Each vendored Go module MUST include a license file; Go modules that are missing license files MUST NOT be included in vendored archives until the licensing is clarified. @@ -242,38 +221,25 @@ archives until the licensing is clarified. Additionally, the package's `+License:+` tag MUST include a cumulative SPDX expression encompassing both the main package and the vendored Go modules. -In rare cases, `+go mod vendor+` may fail to download a project's license file, -even if it exists for the equivalent version in the upstream repository. -This is usually because of the license files have non-standard names or because -the licenses are installed in a subdirectory instead of the root of the module. -In the former case, `+go_vendor_archive+` MAY be configured using -{post_commands}[post_commands] to download the license file from the upstream -repository as a temporary measure, but packagers MUST report this to upstream -and ask it to rename the license file to -{metaPrefixes}[a format supported by `+go mod vendor+`]. -If the license file is included in the `+vendor+` directory but not in the root -directory of a module, the file should be copied to the root directory to satisfy -the Go Vendor Tools license checker. - - +[#go-vendor-tools-licensing] == Licensing with Go Vendor Tools :licensing-config: https://fedora.gitlab.io/sigs/go/go-vendor-tools/config/#licensing :manual-detection: https://fedora.gitlab.io/sigs/go/go-vendor-tools/scenarios/#manually-detecting-licenses +:go-vendor-license-check: https://fedora.gitlab.io/sigs/go/go-vendor-tools/man/rpm_macros/#go_vendor_license_check {gvt}[Go Vendor Tools] provides the `+go_vendor_license+` command and macros for determining the correct `+License:+` expression and installing license files. +Packagers SHOULD use the Go Vendor Tools macros in order to satisfy the +guidelines listed in the previous section. Packagers MUST run `+go_vendor_license report+` (either directly, through go2rpm, or -using the `+%go_vendor_license_check+` macro in a _local_ mock build) +using the {go-vendor-license-check}[%go_vendor_license_check] macro in a _local_ mock build) and double check its output before uploading sources to the lookaside cache. Any errors MUST be addressed. -If any part of the output is wrong, `+go_vendor_license+` 's behavior can be modifed +If any part of the output is wrong, `+go_vendor_license+` 's behavior can be modified in {licensing-config}[the licensing section of the Go Vendor Tools config file]. -Go Vendor Tools scans the upstream sources and vendored libraries for license files -and generates a cumulative SPDX expression. - This document only outlines the standard usage of Go Vendor Tools needed to comply with the Guidelines — consult the {gvt}[Go Vendor Tools documentation] for details on advanced usage. @@ -293,7 +259,7 @@ ensuring that all keys in the License tag are allowed licenses in Fedora, before uploading any sources to the lookaside cache. If necessary, the license expression for individual files can be -overriden in the config file, {manual-detection}[as outlined in the scenarios documentation]. +overridden in the config file, {manual-detection}[as outlined in the scenarios documentation]. ==== === go-vendor-tools.toml @@ -326,7 +292,8 @@ to represent the path to the Go Vendor Tools config file. :go-vendor-license-buildrequires: https://fedora.gitlab.io/sigs/go/go-vendor-tools/man/rpm_macros/#go_vendor_license_buildrequires Packages that use the Go Vendor Tools macros MUST have `+BuildRequires: -go-vendor-tools+` and use the `+%go_vendor_license_buildrequires+` macro +go-vendor-tools+` and use the +{go-vendor-license-buildrequires}[%go_vendor_license_buildrequires] macro to generate generate requirements needed for the selected license detector backend. [source,rpm-spec] @@ -345,9 +312,6 @@ BuildRequires: go-vendor-tools :go-vendor-license-install: https://fedora.gitlab.io/sigs/go/go-vendor-tools/man/rpm_macros/#go_vendor_license_install :go-vendor-license-filelist: https://fedora.gitlab.io/sigs/go/go-vendor-tools/man/rpm_macros/#go_vendor_license_filelist -// TODO: Should this be MUST or SHOULD? Installing all license files is a MUST -// (see the previous section), but should doing that _using GVT_ be a MUST? - Packagers SHOULD use the {go-vendor-license-install}[%go_vendor_license_install] macro to install license files of the main project and all vendored Go modules. @@ -360,7 +324,7 @@ By default, this macro will install the license files into main packages license ---- Then, the macro will populate -{go-vendor-license-filelist}[%{go_vendor_license_filelist}] with a list of +{go-vendor-license-filelist}[%\{go_vendor_license_filelist}] with a list of files that can be passed to `+%files -f+`. [source,rpm-spec] @@ -380,16 +344,48 @@ Any errors raised by `+go_vendor_license+` MUST be addressed. As an additional measure, the {go-vendor-license-check}[%go_vendor_license_check macro] runs the same license scan as the `+go_vendor_license report+` command. -Packages SHOULD run `+go_vendor_license_check+` in `+%check+` so the package +Packages SHOULD use `+go_vendor_license_check+` in `+%check+` so the package build will fail if there are any license errors. Go Vendor Tools scans the upstream sources and vendored libraries for license files -and generates a cummulative SPDX expression. -The command will error if any Go module is missing a license file. +and generates a cumulative SPDX expression. +Also, the macro checks that the expression in the package's License tag is +equivalent (regardless of order or possible expression simplification) +to what `+go_vendor_license report+` expects. +[source,rpm-spec] +---- +# Scan licenses and verify that the License tag is equivalent to what +# go_vendor_license calculates. +%go_vendor_license_check -c %{S:2} + +# The macro can also compare a license expression stored in a macro with +# go_vendor_license's output. +%go_vendor_license_check -c %{S:2} %{go_licenses} +---- + +=== In case of missing licenses + +`+go_vendor_license+` checks if any Go module is missing a license file. +Again, Go modules that are missing license files MUST NOT be included in +vendored archives until the situation is fixed upstream. + +In some cases, `+go mod vendor+` may fail to download a project's license file, +even if it exists for the equivalent version in the upstream repository. +This is usually because the license files have non-standard names or because +the licenses are installed in a subdirectory instead of the root of the module. +In the former case, `+go_vendor_archive+` MAY be configured using +{post_commands}[post_commands] to download the license file from the upstream +repository as a temporary measure, but packagers MUST report this to upstream +and ask it to rename the license file to +{metaPrefixes}[a format supported by `+go mod vendor+`]. +If the license file is included in a subdirectory of a module, the file should +be copied to the root directory to satisfy the Go Vendor Tools license checker. == Testing -You MUST run unit tests. +:gocheck2: https://fedora.gitlab.io/sigs/go/go-vendor-tools/man/rpm_macros/#gocheck2 + +You SHOULD run unit tests. Some tests may be disabled, especially the following kinds of unit tests are incompatible with a secure build environment such as mock: @@ -404,218 +400,271 @@ However, you SHOULD also report the problem upstream. Remember to trace in a comment why each check was disabled, with links to eventual upstream problem reports. -== Go modules mode - -CAUTION: TODO. Wait until we figure out `+%gocheck+`. - -== Security updates - -CAUTION: TODO. See notes in https://gitlab.com/fedora/sigs/go/go-vendor-tools/-/issues/76. - -== Walkthrough - -[CAUTION] -==== - TODO(gotmax23): Consider more thoroughly refactoring of the Walkthrough section. -This should be written like a Guidelines document, not a tutorial. -==== +Tests can be run using {gocheck2}[the %gocheck2 macro] which calls `+go test+` +internally while preserving the Fedora build flags and providing additional +options to skip certain tests. -This chapter will present a typical Go spec file step by step, with comments -and explanations. +== Go modules mode -=== Spec preamble: `+%{goipath}+`, `+%{forgeurl}+` and `+%gometa+` +Packages SHOULD opt in to Go modules mode by including +`+%global gomodulesmode GO111MODULE=on+` in the specfile. +Customarily, this is done at the beginning of `+%build+` for the `+%gobuild+` invocation. +Go modules mode is disabled by default for legacy reasons but it is the default behavior upstream. +Modules mode should be used so the go command will read modules metadata and +include extra metadata about modules used to build the package in the binary. -==== Usual case +== Macros -// TODO(gotmax23): The forge macros remain coupled with the Go macros. -// Some people have "opinions" about that. -// Go packagers are used to them and go2rpm relies on the forge macros -// integration when generating specfiles and downloading sources. -// It makes sense to use them since there is no Go package registry; it's just -// git (and the Go Proxy on top of it). -// I added this NOTE here, but it should probably be moved to the bottom if -// it's kept at all. -// At least, detailed documentation about the different forge macros should -// probably be moved somewhere else. -[NOTE] -==== -Historically, Go packages have used a custom flavor of the Forge macros -that handles versioning and sets up the appropriate `+$GOPATH+` structure -for Go packages. -// Link to the gomodulesmode of the guidelines -Packages that enable Go modules mode and don't use `+%gocheck+` may opt-out of -using `+%gometa+` and `+%goprep+` and handle `+Source+` definitions and -`+%autosetup+` invocations manually. -==== +:gvt-macros: https://fedora.gitlab.io/sigs/go/go-vendor-tools/man/rpm_macros/ +:forge-srpm-macros: https://git.sr.ht/~gotmax23/forge-srpm-macros/ +:macros-go-rpm: https://gitlab.com/fedora/sigs/go/go-rpm-macros/-/blob/main/rpm/macros.d/macros.go-rpm +:macros-go-srpm: https://gitlab.com/fedora/sigs/go/go-srpm-macros/-/blob/main/srpm/macros.d/macros.go-srpm +:forge-wrappers: https://gitlab.com/fedora/sigs/go/go-rpm-macros/-/blob/main/doc/forge-wrappers.adoc?ref_type=heads -A Go package is identified by its import path. A Go spec file will therefore -start with the `+%{goipath}+` declaration. Don't get it wrong, it will control -the behavior of the rest of the spec file. +The RPM macros provided by `+go-vendor-tools+` are used to validate and install licenses. +See {gvt-macros}[Go Vendor Tools RPM Macros docs] and <>. - %global goipath github.com/docker/docker +`+go-rpm-macros+` is primarily responsible for the `+%gobuild+` macro that calls +`+go build+` with Fedora's build flags. -If your package is hosted on a forge like GitHub, GitLab, Bitbucket or Pagure, -the hosting of the Go package will be automatically deduced from this variable -(typically by prefixing it with \https://). If that is not the case, you need -to declare explicitly the hosting URL with the `+%{forgeurl}+` macro +`+go-rpm-macros+` also provides wrappers around the +xref:SourceURL.adoc[Forge macros] from the {forge-srpm-macros}[forge-srpm-macros] package +that makes it easier to specify the Source URL and unpack sources for Go projects +hosted on common software forges like Github. +Packagers are recommended to use these macros instead of specifying sources and calling +`+%autosetup+` / `+%setup+` manually. +See {forge-wrappers}[the standalone docs] and example specfile in these +guidelines for more information. - %global forgeurl https://github.com/moby/moby +== Example -The `+%{forgeurl}+` declaration is followed by either `+Version+`, `+%commit+` or -`+%tag+`. Use the combination that matches your use-case. - Version: 28.0.0 +=== go-vendor-tools configuration +These entries were generated automatically by go2rpm. +All Go packages MUST have a go-vendor-tools.toml file +committed to distgit alongside the specfile. -// TODO: Update go2rpm template. -// See https://gitlab.com/fedora/sigs/go/go2rpm/-/merge_requests/25/commits. -[NOTE] -==== -You MUST set `+%date+` in the `+YYYYMMDD+` format that corresponds to the commit -when using the `+%commit+` macro. -==== +[source,toml] +.go-vendor-tools.toml +---- +[archive] -Now that we have all the required variables, the `+%gometa+` macro can be run +[licensing] +detector = "askalono" - %gometa +[[licensing.licenses]] +path = "vendor/github.com/google/shlex/COPYING" +sha256sum = "cfc7749b96f63bd31c3c42b5c471bf756814053e847c10f3eb003417bc523d30" +expression = "Apache-2.0" + +[[licensing.licenses]] +path = "vendor/github.com/jwalton/gchalk/LICENSE-chalk" +sha256sum = "44e453533edb9f1c037cb260c58f66f1d9b2e7823a07407cd6d04320e3925fea" +expression = "MIT" + +[[licensing.licenses]] +path = "vendor/github.com/jwalton/gchalk/pkg/ansistyles/LICENSE-ansi-styles" +sha256sum = "310f4b4de77142b34acc5a58de93558fde5dea75891c7822b4086f71372ec983" +expression = "MIT" + +[[licensing.licenses]] +path = "vendor/github.com/jwalton/go-supportscolor/LICENSE" +sha256sum = "892282511d65ac08025fbabcd8af330d0aa94e459d81a818251ff5a934383816" +expression = "MIT" + +[[licensing.licenses]] +path = "vendor/gopkg.in/yaml.v3/LICENSE" +sha256sum = "d18f6323b71b0b768bb5e9616e36da390fbd39369a81807cca352de4e4e6aa0b" +expression = "MIT AND (MIT AND Apache-2.0)" +---- -It will compute and set the following variables if they are not already set by -the packager: -goname:: an rpm-compatible package name derived from goipath -gosource:: a URL that can be used as SourceX: value -gourl:: a URL that can be used as URL: value +=== Specfile with forge macro wrappers -It will delegate processing to the `+%forgemeta+` macro for: +This is the default method used by go2rpm and is the convention for Go +packages. -forgesource:: a URL that can be used as SourceX: value -forgesetupargs:: the correct arguments to pass to `+%setup+` for this source -used by `+%forgesetup+` and `+%forgeautosetup+` -archivename:: the source archive filename, without extensions -archiveext:: the source archive filename extensions, without leading dot -archiveurl:: the URL that can be used to download the source archive, -without renaming -topdir:: the source archive top directory (can be empty) -extractdir:: the source directory created inside `+%{_builddir}+` after -using `+%forgesetup+`, `+%forgeautosetup+` or `+%{forgesetupargs}+` -repo:: the repository name -owner:: the repository owner (if used by another computed variable) -shortcommit:: the commit hash clamping used by the forge, if any -scm:: the scm type, when packaging code snapshots: commits or tags -distprefix:: the prefix that needs adding to dist to trace non-release -packaging +[source,rpm-spec] +.ov.spec +---- +# Generated by go2rpm 1.17.1 (with extra code comments added manually) +%bcond check 1 -Most of the computed variables are both overridable and optional. +# https://github.com/noborus/ov +%global goipath github.com/noborus/ov +Version: 0.43.0 -Now we can add the remaining elements of the preamble. +%gometa -L -f -=== Source package metadata: `+%{goname}+`, `+%{gourl}+` and `+%{gosource}+` +Name: ov +Release: %autorelease +Summary: Feature-rich terminal-based text viewer -We can declare the usual rpm headers, using the values computed by `+%gometa+`: +# Generated by go-vendor-tools +License: Apache-2.0 AND BSD-3-Clause AND MIT AND MPL-2.0 +URL: %{gourl} +Source0: %{gosource} +# Generated by go-vendor-tools +Source1: %{archivename}-vendor.tar.bz2 +# Go Vendor Tools configuration generated by go2rpm +Source2: go-vendor-tools.toml -[source,rpm-spec] ----- -Name: %{goname} -# If not set before -Version: -Release: 1%{?dist} -Summary: -License: -URL: %{gourl} -Source: %{gosource} ----- +BuildRequires: go-vendor-tools -You can replace them with manual definitions. -For example, replace `+%{gourl}+` with the project homepage if it exists -separately from the repository URL. -Be careful to only replace `+%{go*}+` variables when it adds value to the -specfile and you understand the consequences. Otherwise you will just add -maintenance-intensive discrepancies in the distribution. +%description +Feature-rich terminal-based text viewer. It is a so-called terminal pager. -=== %prep: `+%goprep+` +%prep +# Unpack upstream sources (Source0) and apply patches if they exist. +# This also creates the %%{gobuilddir} directory used to store the binary built +# during %%build. +%goprep -p1 +# Unpack the vendor archive in Source1. +%setup -q -T -D -a1 %{forgesetupargs} -`+%goprep+` unpacks the Go source archives and creates the project “GOPATH” tree -used in the rest of the spec file. It removes vendored (bundled) code in the -upstream archive. -// TODO: Link to section on security updates -Projects SHOULD regenerate vendored sources using `+go_vendor_tools+` -even if projects include a vendor directory. -This makes it easier to apply security updates. -Use the `+-k+` flag if you wish to keep any `+vendor+` directory included in -the upstream sources. +%generate_buildrequires +# Install license scanner dependencies. +%go_vendor_license_buildrequires -c %{S:2} - %goprep +%build +# Enable Go modules mode as required by the Guidelines. +%global gomodulesmode GO111MODULE=on +# Set version in binary. The exact value to pass to -X differs by project. +export GO_LDFLAGS="-X main.Version=%{version}" +# Build the binary +%gobuild -o %{gobuilddir}/bin/ov %{goipath} +# Generate shell completions +%{gobuilddir}/bin/%{name} --completion bash > %{name}.bash +%{gobuilddir}/bin/%{name} --completion fish > %{name}.fish +%{gobuilddir}/bin/%{name} --completion zsh > %{name}.zsh + +%install +# Install license files +%go_vendor_license_install -c %{S:2} +# Install binaries built during %%build +install -m 0755 -vd %{buildroot}%{_bindir} +install -m 0755 -vp %{gobuilddir}/bin/* %{buildroot}%{_bindir}/ -=== Packaging a binary: the %build section +# Install shell completions generated during %%build +install -Dpm 0644 %{name}.bash %{buildroot}%{bash_completions_dir}/%{name} +install -Dpm 0644 %{name}.fish %{buildroot}%{fish_completions_dir}/%{name}.fish +install -Dpm 0644 %{name}.zsh %{buildroot}%{zsh_completions_dir}/_%{name} -If your package is a source package only, you can skip this `+%build+` section -entirely. +%check +# Perform license check +%go_vendor_license_check -c %{S:2} +# Run Go unit tests +%if %{with check} +%gocheck2 +%endif -Otherwise, you first need to identify manually the project parts that can be -built, and how to name the result. -Practically, it’s any directory containing a main() Go section. Nice projects -put those in `+cmd+` subdirectories named after the command that will be built, -which is what we will document here, but it is not a general rule. Sometimes the -whole `+%goipath+` builds as a single binary. +%files -f %{go_vendor_license_filelist} +# Include modules.txt used to generate automatic bundled() Provides +%license vendor/modules.txt +%doc README.md +%{_bindir}/ov +%{bash_completions_dir}/%{name} +%{fish_completions_dir}/%{name}.fish +%{zsh_completions_dir}/_%{name} -[source,rpm-spec] ----- -for cmd in cmd/* ; do - %gobuild -o %{gobuilddir}/bin/$(basename $cmd) %{goipath}/$cmd -done +%changelog +%autochangelog ---- +=== Specfile with manual defintions -=== Installing the packages - -We simply create the `+%{_bindir}+` directory in the buildroot -and install the commands as executable in it: +This above approach is recommended and used by default in go2rpm but Go +packages MAY be built without the forge macros. +Be sure to include the manual dependency on `+go-rpm-macros+` and the +appropriate ExclusiveArch invocation. [source,rpm-spec] +.ov.spec ---- -install -m 0755 -vd %{buildroot}%{_bindir} -install -m 0755 -vp %{gobuilddir}/bin/* %{buildroot}%{_bindir}/ ----- - +%bcond check 1 + +Name: ov +Version: 0.43.0 +Release: %autorelease +Summary: Feature-rich terminal-based text viewer +# Generated by go-vendor-tools +License: Apache-2.0 AND BSD-3-Clause AND MIT AND MPL-2.0 +URL: https://github.com/noborus/ov +Source0: %{url}/archive/v%{version}/ov-%{version}.tar.gz +# Generated by go-vendor-tools +Source1: ov-%{version}-vendor.tar.bz2 +Source2: go-vendor-tools.toml -// TODO: We want to consider getting rid of %gocheck or rewriting it. -// See discussion in -// https://gitlab.com/fedora/sigs/go/go2rpm/-/merge_requests/22#note_2626091103. -=== Running the unit tests: `+%gocheck+` +ExclusiveArch: %{golang_arches_future} +BuildRequires: go-rpm-macros +BuildRequires: go-vendor-tools -As said before, you MUST run unit tests in `+%check+`: +%description +Feature-rich terminal-based text viewer. It is a so-called terminal pager. - %gocheck +%prep +# Unpack upstream sources (Source0) and apply patches if they exist. +# This also creates the %%{gobuilddir} directory used to store the binary built +# during %%build. +%autosetup -p1 +# Unpack the vendor archive in Source1. +%setup -q -T -D -a1 -However it is often necessary to disable some of them. You have 3 exclusion -flags to do so: +%generate_buildrequires +# Install license scanner dependencies. +%go_vendor_license_buildrequires -c %{S:2} -* `+-d +`: exclude the files contained in `++` - non-recursively (subdirectories are not excluded) -* `+-t +`: exclude the files contained in `++` - recursively (subdirectories are excluded) -* `+-r +`: exclude files matching `++` +%build +# Enable Go modules mode as required by the Guidelines. +%global gomodulesmode GO111MODULE=on +# Set version in binary. The exact value to pass to -X differs by project. +export GO_LDFLAGS="-X main.Version=%{version}" +# Build the binary +%gobuild -o ov . +# Generate shell completions +./ov --completion bash > %{name}.bash +./ov --completion fish > %{name}.fish +./ov --completion zsh > %{name}.zsh + +%install +# Install license files +%go_vendor_license_install -c %{S:2} -Remember to document why a test has been disabled. +# Install binaries built during %%build +install -Dp ./ov -t %{buildroot}%{_bindir} -=== %files declaration +# Install shell completions generated during %%build +install -Dpm 0644 %{name}.bash %{buildroot}%{bash_completions_dir}/%{name} +install -Dpm 0644 %{name}.fish %{buildroot}%{fish_completions_dir}/%{name}.fish +install -Dpm 0644 %{name}.zsh %{buildroot}%{zsh_completions_dir}/_%{name} -Binaries are usually shipped in the main package. This package MUST include -legal files and documentation associated with those binaries. +%check +# Perform license check +%go_vendor_license_check -c %{S:2} +# Run Go unit tests +%if %{with check} +%gocheck2 +%endif -[source,rpm-spec] ----- %files -f %{go_vendor_license_filelist} +# Include modules.txt used to generate automatic bundled() Provides %license vendor/modules.txt %doc README.md -%{_bindir}/NAME ----- - -== Examples - +%{_bindir}/ov +%{bash_completions_dir}/%{name} +%{fish_completions_dir}/%{name}.fish +%{zsh_completions_dir}/_%{name} -// TODO: Updated examples +%changelog +%autochangelog +---- == Additional resources +:go-rpm-macros-docs: https://gitlab.com/fedora/sigs/go/go-rpm-macros/-/tree/main/doc?ref_type=heads +:go2rpm: https://gitlab.com/fedora/sigs/go/go2rpm + - {gvt}[Go Vendor Tools documentation] +- {go-rpm-macros-docs}[Go RPM Macros documentation] +- {go2rpm}[go2rpm project on Gitlab] From 3b5dbb6ac0a3e39c26fb35fc7e786e1e5b5e98f8 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 19/31] golang: clarify extra compiler flags section --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 7dfca0c..2d167b0 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -116,7 +116,15 @@ Go supports passing additional linker flags (for example, to enable `+--version+` functionality) and build tags for conditional compilation. When using an upstream build script, these may be set automatically. -Otherwise, you can set them manually. +Otherwise, the packager should set them manually. + +[IMPORTANT] +==== +Make sure to consult the upstream build process and documentation to determine +what linker flags you may need to include to properly encode the version into +the binary for projects that provide a flag like `+--version+` or what build +tags to select to enable additional optional features. +==== ==== Linker flags From a858b3bb3e15d1eae20d417b537d75c5a06f2723 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 20/31] golang: explicitly forbid gocheck --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 2d167b0..0359c97 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -412,6 +412,8 @@ Tests can be run using {gocheck2}[the %gocheck2 macro] which calls `+go test+` internally while preserving the Fedora build flags and providing additional options to skip certain tests. +Packages MUST NOT use the deprecated legacy `+%gocheck+` macro. + == Go modules mode Packages SHOULD opt in to Go modules mode by including From 1b6121c1697116d1b6362864326fdb52b03ce624 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 21/31] golang: remove "simply" --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 0359c97..81fe4b5 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -193,7 +193,7 @@ Source1: %{archivename}-vendor.tar.bz2 Source2: go-vendor-tools.toml ---- -Then, simply run `+go_vendor_archive create .spec+` to create a +Then, run `+go_vendor_archive create .spec+` to create a vendor tarball. === Bundled provides @@ -202,7 +202,7 @@ vendor tarball. Packages MUST include `+bundled(golang(IMPORT_PATH)) = VERSION+` Provides for all vendored Go modules. This is handled automatically by a dependency generator. -Simply mark the `+vendor/modules.txt+` file with `+%license+` in `+%files+`, +Mark the `+vendor/modules.txt+` file with `+%license+` in `+%files+`, and then the generator will scan the file and create the `+bundled()+` Provides. [source, rpm-spec] From dfbd69b6e0ffe23129de785a0a0886542c624dd7 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 22/31] golang: fix overly verbose go-vendor-tools.toml guideline --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 81fe4b5..38ea9e5 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -279,8 +279,7 @@ detector backend and other configuration options. See the {config-reference}[configuration reference] for more information. The recommended approach is to use `+go2rpm+` that automatically creates a valid `+go-vendor-tools.toml+`. -At least, all packages MUST have a minimal `+go-vendor-tools.toml+` that -specifies a license detector backend. +A minimal configuration looks like this: [source,toml] ---- From 5c25f91301243593801a9f9e28e680224be1b445 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 23/31] golang: fix typo --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 38ea9e5..4ae7fd7 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -301,7 +301,7 @@ to represent the path to the Go Vendor Tools config file. Packages that use the Go Vendor Tools macros MUST have `+BuildRequires: go-vendor-tools+` and use the {go-vendor-license-buildrequires}[%go_vendor_license_buildrequires] macro -to generate generate requirements needed for the selected license detector backend. +to generate requirements needed for the selected license detector backend. [source,rpm-spec] ---- From 6bea23435bff41154c8aeac9c7646327396793a7 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 24/31] golang: fix another typo --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 4ae7fd7..5b43873 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -322,7 +322,7 @@ BuildRequires: go-vendor-tools Packagers SHOULD use the {go-vendor-license-install}[%go_vendor_license_install] macro to install license files of the main project and all vendored Go modules. -By default, this macro will install the license files into main packages license directory. +By default, this macro will install the license files into main package's license directory. [source,rpm-spec] ---- From d0f06890a19365018e024a49375b97524a13bd3a Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 25/31] golang: remove confusing sentance about Go Vendor Tools macros --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 5b43873..560d843 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -237,9 +237,8 @@ expression encompassing both the main package and the vendored Go modules. :go-vendor-license-check: https://fedora.gitlab.io/sigs/go/go-vendor-tools/man/rpm_macros/#go_vendor_license_check {gvt}[Go Vendor Tools] provides the `+go_vendor_license+` command and macros -for determining the correct `+License:+` expression and installing license files. -Packagers SHOULD use the Go Vendor Tools macros in order to satisfy the -guidelines listed in the previous section. +to help determine the correct `+License:+` expression and install license files +as mandated by the previous section. Packagers MUST run `+go_vendor_license report+` (either directly, through go2rpm, or using the {go-vendor-license-check}[%go_vendor_license_check] macro in a _local_ mock build) From a4c23eaf170b60bb7667d63ea0aa4d034084edb3 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 26/31] golang: clarify go modules guideline --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 560d843..696b8f5 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -414,12 +414,30 @@ Packages MUST NOT use the deprecated legacy `+%gocheck+` macro. == Go modules mode -Packages SHOULD opt in to Go modules mode by including -`+%global gomodulesmode GO111MODULE=on+` in the specfile. -Customarily, this is done at the beginning of `+%build+` for the `+%gobuild+` invocation. -Go modules mode is disabled by default for legacy reasons but it is the default behavior upstream. -Modules mode should be used so the go command will read modules metadata and -include extra metadata about modules used to build the package in the binary. +:gomod: https://go.dev/ref/mod +:go111module: https://go.dev/ref/mod#mod-commands +:embed: https://pkg.go.dev/embed + +Packages SHOULD enable Go modules mode by including +`+%global gomodulesmode GO111MODULE=on+` in the specfile +to set the `+GO111MODULE+` environment variable. +Customarily, this definition is included at the beginning of `+%build+` +before the `+%gobuild+` invocation. + +[NOTE] +==== +{gomod}[Go modules] are the system `+go+` uses to manage dependencies. +Go modules mode replaces `+$GOPATH+` mode (the previous dependency management system). +Go can be configured to use modules or `+$GOPATH+` mode by setting the +{go111module}[$GO111MODULE environment variable] to `+on+`, `+off+`, or `+auto+`. +`+auto+` is the upstream default. +By default, `+%gobuild+` in Fedora sets `+GO111MODULE=off+` for compatibility +with the legacy Golang Packaging Guidelines but this approach is not +recommended for new packages built with vendored dependencies. +Modules mode should be used so `+%gobuild+` will read modules metadata and +include metadata about package dependencies in the binary +and to make sure {embed}[Go embed] works properly. +==== == Macros From e1f11817e06e8e84d46c4692e7bddde85ff2d15a Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 27/31] golang: add admonition to legacy guidelines Suggested-by: churchyard --- diff --git a/guidelines/modules/ROOT/pages/Golang_old.adoc b/guidelines/modules/ROOT/pages/Golang_old.adoc index ea01eb1..afdcd03 100644 --- a/guidelines/modules/ROOT/pages/Golang_old.adoc +++ b/guidelines/modules/ROOT/pages/Golang_old.adoc @@ -1,6 +1,13 @@ -= Non-vendored Golang Packaging Guidelines += Legacy Golang Packaging Guidelines :last-reviewed: 2019-06-19 +[IMPORTANT] +==== +These guidelines were replaced by xref:Golang.adoc[a newer version]. + +They exist as a historical reference for packages that don't follow the new guidelines yet. +==== + This document details best practices for packaging Golang packages. Most of it is automated by an extensive use of macros. From 0ccd6d52dff0f0523edd2d3644c23e0d0bd2046f Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 28/31] golang: update "Bundled provides" and "Example" - Reflect that `%go_vendor_license_install` copies modules.txt - Remove inconsistent %{name} usage - Replace overly complicated %setup invocations with simple tar commands --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 696b8f5..f76b10d 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -196,14 +196,18 @@ Source2: go-vendor-tools.toml Then, run `+go_vendor_archive create .spec+` to create a vendor tarball. +[#bundled-provides] === Bundled provides -:go_mod_vendor.attr: https://gitlab.com/fedora/sigs/go/go-rpm-macros/-/blob/main/rpm/fileattrs/go_mod_vendor.attr?ref_type=heads +:go_mod_vendor_attr: https://gitlab.com/fedora/sigs/go/go-rpm-macros/-/blob/main/rpm/fileattrs/go_mod_vendor.attr?ref_type=heads Packages MUST include `+bundled(golang(IMPORT_PATH)) = VERSION+` Provides for all vendored Go modules. -This is handled automatically by a dependency generator. +This is handled automatically by {go_mod_vendor_attr}[a dependency generator]. +It runs on any `+modules.txt+` file in a license directory. Mark the `+vendor/modules.txt+` file with `+%license+` in `+%files+`, and then the generator will scan the file and create the `+bundled()+` Provides. +`+vendor/modules.txt+` is included in `+go_vendor_license_filelist+` by default +(see <>) so most packages will not need to do this manually. [source, rpm-spec] ---- @@ -313,6 +317,7 @@ BuildRequires: go-vendor-tools %go_vendor_license_buildrequires -c %{S:2} ---- +[#installing-licenses] === Installing licenses :go-vendor-license-install: https://fedora.gitlab.io/sigs/go/go-vendor-tools/man/rpm_macros/#go_vendor_license_install @@ -322,6 +327,8 @@ Packagers SHOULD use the {go-vendor-license-install}[%go_vendor_license_install] macro to install license files of the main project and all vendored Go modules. By default, this macro will install the license files into main package's license directory. +The macro also copies the `+vendor/modules.txt+` file to the license directory to +enable the Golang `+bundled()+` generator (see <>). [source,rpm-spec] ---- @@ -547,7 +554,7 @@ Feature-rich terminal-based text viewer. It is a so-called terminal pager. # during %%build. %goprep -p1 # Unpack the vendor archive in Source1. -%setup -q -T -D -a1 %{forgesetupargs} +tar -xf %{S:1} %generate_buildrequires # Install license scanner dependencies. @@ -574,9 +581,9 @@ install -m 0755 -vd %{buildroot}%{_bindir} install -m 0755 -vp %{gobuilddir}/bin/* %{buildroot}%{_bindir}/ # Install shell completions generated during %%build -install -Dpm 0644 %{name}.bash %{buildroot}%{bash_completions_dir}/%{name} -install -Dpm 0644 %{name}.fish %{buildroot}%{fish_completions_dir}/%{name}.fish -install -Dpm 0644 %{name}.zsh %{buildroot}%{zsh_completions_dir}/_%{name} +install -Dpm 0644 ov.bash %{buildroot}%{bash_completions_dir}/ov +install -Dpm 0644 ov.fish %{buildroot}%{fish_completions_dir}/ov.fish +install -Dpm 0644 ov.zsh %{buildroot}%{zsh_completions_dir}/_ov %check # Perform license check @@ -587,13 +594,11 @@ install -Dpm 0644 %{name}.zsh %{buildroot}%{zsh_completions_dir}/_%{name} %endif %files -f %{go_vendor_license_filelist} -# Include modules.txt used to generate automatic bundled() Provides -%license vendor/modules.txt %doc README.md %{_bindir}/ov -%{bash_completions_dir}/%{name} -%{fish_completions_dir}/%{name}.fish -%{zsh_completions_dir}/_%{name} +%{bash_completions_dir}/ov +%{fish_completions_dir}/ov.fish +%{zsh_completions_dir}/_ov %changelog %autochangelog @@ -635,7 +640,7 @@ Feature-rich terminal-based text viewer. It is a so-called terminal pager. # during %%build. %autosetup -p1 # Unpack the vendor archive in Source1. -%setup -q -T -D -a1 +tar -xf %{S:1} %generate_buildrequires # Install license scanner dependencies. @@ -649,9 +654,9 @@ export GO_LDFLAGS="-X main.Version=%{version}" # Build the binary %gobuild -o ov . # Generate shell completions -./ov --completion bash > %{name}.bash -./ov --completion fish > %{name}.fish -./ov --completion zsh > %{name}.zsh +./ov --completion bash > ov.bash +./ov --completion fish > ov.fish +./ov --completion zsh > ov.zsh %install # Install license files @@ -661,9 +666,9 @@ export GO_LDFLAGS="-X main.Version=%{version}" install -Dp ./ov -t %{buildroot}%{_bindir} # Install shell completions generated during %%build -install -Dpm 0644 %{name}.bash %{buildroot}%{bash_completions_dir}/%{name} -install -Dpm 0644 %{name}.fish %{buildroot}%{fish_completions_dir}/%{name}.fish -install -Dpm 0644 %{name}.zsh %{buildroot}%{zsh_completions_dir}/_%{name} +install -Dpm 0644 ov.bash %{buildroot}%{bash_completions_dir}/ov +install -Dpm 0644 ov.fish %{buildroot}%{fish_completions_dir}/ov.fish +install -Dpm 0644 ov.zsh %{buildroot}%{zsh_completions_dir}/_ov %check # Perform license check @@ -674,13 +679,11 @@ install -Dpm 0644 %{name}.zsh %{buildroot}%{zsh_completions_dir}/_%{name} %endif %files -f %{go_vendor_license_filelist} -# Include modules.txt used to generate automatic bundled() Provides -%license vendor/modules.txt %doc README.md %{_bindir}/ov -%{bash_completions_dir}/%{name} -%{fish_completions_dir}/%{name}.fish -%{zsh_completions_dir}/_%{name} +%{bash_completions_dir}/ov +%{fish_completions_dir}/ov.fish +%{zsh_completions_dir}/_ov %changelog %autochangelog From 0ae97d392b67b94f5222e7c3b91a4e4d04625ba4 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 29/31] golang: add another sentence about forge macro wrappers --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index f76b10d..5b37db0 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -464,7 +464,8 @@ See {gvt-macros}[Go Vendor Tools RPM Macros docs] and < Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 30/31] golang: make example less prescriptive about forge macros We show the forge macro example first to follow after go2rpm, but we don't need to declare it as "recommended." --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 5b37db0..35ffa45 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -516,7 +516,7 @@ expression = "MIT AND (MIT AND Apache-2.0)" === Specfile with forge macro wrappers -This is the default method used by go2rpm and is the convention for Go +This is the default method used by go2rpm and is the current convention for Go packages. [source,rpm-spec] @@ -606,8 +606,8 @@ install -Dpm 0644 ov.zsh %{buildroot}%{zsh_completions_dir}/_ov ---- === Specfile with manual defintions -This above approach is recommended and used by default in go2rpm but Go -packages MAY be built without the forge macros. +This above approach is used by default in go2rpm but Go +packages can also be built without the forge macros. Be sure to include the manual dependency on `+go-rpm-macros+` and the appropriate ExclusiveArch invocation. From ce9fe7dab0bc77d24726784118547bd2dd9601d1 Mon Sep 17 00:00:00 2001 From: Maxwell G Date: Oct 31 2025 21:16:38 +0000 Subject: [PATCH 31/31] golang: fix-copy-paste error in non-gometa example The %{gobuilddir} part only applies to the first example that uses goprep. --- diff --git a/guidelines/modules/ROOT/pages/Golang.adoc b/guidelines/modules/ROOT/pages/Golang.adoc index 35ffa45..a2f031f 100644 --- a/guidelines/modules/ROOT/pages/Golang.adoc +++ b/guidelines/modules/ROOT/pages/Golang.adoc @@ -637,8 +637,6 @@ Feature-rich terminal-based text viewer. It is a so-called terminal pager. %prep # Unpack upstream sources (Source0) and apply patches if they exist. -# This also creates the %%{gobuilddir} directory used to store the binary built -# during %%build. %autosetup -p1 # Unpack the vendor archive in Source1. tar -xf %{S:1}