From 2c44cbe09e2b640bd3f1722e535f2209d028c47f Mon Sep 17 00:00:00 2001 From: Dave Collins Date: Tue, 12 Sep 2023 03:57:10 -0500 Subject: [PATCH] version: Support single override and add git hash. This reworks the way versions are handled internally to match other Decred projects such as dcrd and dcrwallet. Namely, it reverse the semantics such that the individual semver components (major, minor, patch, prerelease, and buildmetadata) are parsed from a full string and exported at init time. Also, since the version is now parsed and verified to be accurate, it updates the pre-release parsing to properly support dots as required by the spec. Finally, starting with Go version 1.18, it adds the git commit hash to the version string as buildmetadata when no buildmetadata is otherwise specified. This provides a few main benefits: - Allows a single linker override to fully specify the version string instead of having separate ones that can only override the prerelease and build metadata portions - Provides run-time checks to ensure the full version string is valid per the semver spec regardless of whether it was specified directly in the source or provided via the linker - The exact commit used to build non-release versions will be in the version string by default Finally, while here, add some comments regarding the release process to help maintainers and add the `-V` short flag for the version to match other projects for consistency. --- config.go | 4 +- dcrpool.go | 6 +- version.go | 191 ++++++++++++++++++++++++++--------------- version_buildinfo.go | 35 ++++++++ version_nobuildinfo.go | 14 +++ 5 files changed, 174 insertions(+), 76 deletions(-) create mode 100644 version_buildinfo.go create mode 100644 version_nobuildinfo.go diff --git a/config.go b/config.go index 38258f7e..1bf4185c 100644 --- a/config.go +++ b/config.go @@ -87,7 +87,7 @@ var ( // config defines the configuration options for the pool. type config struct { - ShowVersion bool `long:"version" no-ini:"true" description:"Display version information and exit."` + ShowVersion bool `short:"V" long:"version" no-ini:"true" description:"Display version information and exit."` HomeDir string `long:"appdata" ini-name:"appdata" description:"Path to application home directory."` ConfigFile string `long:"configfile" ini-name:"configfile" description:"Path to configuration file."` DataDir string `long:"datadir" ini-name:"datadir" description:"The data directory."` @@ -396,7 +396,7 @@ func loadConfig(appName string) (*config, []string, error) { // Show the version and exit if the version flag was specified. if preCfg.ShowVersion { fmt.Printf("%s version %s (Go version %s %s/%s)\n", appName, - version(), runtime.Version(), runtime.GOOS, runtime.GOARCH) + Version, runtime.Version(), runtime.GOOS, runtime.GOARCH) os.Exit(0) } diff --git a/dcrpool.go b/dcrpool.go index 345090a9..999f1b17 100644 --- a/dcrpool.go +++ b/dcrpool.go @@ -200,10 +200,10 @@ func realMain() error { }() } - mpLog.Infof("Version: %s", version()) - mpLog.Infof("Runtime: Go version %s", runtime.Version()) + mpLog.Infof("%s version %s (Go version %s %s/%s)", appName, + Version, runtime.Version(), runtime.GOOS, runtime.GOARCH) mpLog.Infof("Home dir: %s", cfg.HomeDir) - mpLog.Infof("Started dcrpool.") + mpLog.Infof("Started dcrpool") go func() { select { diff --git a/version.go b/version.go index 4648ea41..415f4519 100644 --- a/version.go +++ b/version.go @@ -1,99 +1,148 @@ // Copyright (c) 2013-2014 The btcsuite developers -// Copyright (c) 2015-2021 The Decred developers +// Copyright (c) 2015-2023 The Decred developers // Use of this source code is governed by an ISC // license that can be found in the LICENSE file. package main import ( - "bytes" "fmt" + "regexp" + "strconv" "strings" ) const ( - // semanticAlphabet defines the allowed characters for the pre-release - // portion of a semantic version string. - semanticAlphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-" - - // semanticBuildAlphabet defines the allowed characters for the build - // portion of a semantic version string. - semanticBuildAlphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-." + // semanticAlphabet defines the allowed characters for the pre-release and + // build metadata portions of a semantic version string. + semanticAlphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-." ) -// These constants define the application version and follow the semantic -// versioning 2.0.0 spec (http://semver.org/). -const ( - appMajor uint = 1 - appMinor uint = 2 - appPatch uint = 0 -) +// semverRE is a regular expression used to parse a semantic version string into +// its constituent parts. +var semverRE = regexp.MustCompile(`^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)` + + `(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*` + + `[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$`) +// These variables define the application version and follow the semantic +// versioning 2.0.0 spec (https://semver.org/). var ( - // appPreRelease is defined as a variable so it can be overridden during - // the build process with '-ldflags "-X main.appPreRelease=foo"' if - // needed. It MUST only contain characters from semanticAlphabet per - // the semantic versioning spec. - appPreRelease = "" - - // appBuild is defined as a variable so it can be overridden during the - // build process with '-ldflags "-X main.appBuild=foo"' if needed. It - // MUST only contain characters from semanticBuildAlphabet per the - // semantic versioning spec. - appBuild = "dev" -) + // Note for maintainers: + // + // The expected process for setting the version in releases is as follows: + // - Create a release branch of the form 'release-vMAJOR.MINOR' + // - Modify the Version variable below on that branch to: + // - Remove the pre-release portion + // - Set the build metadata to 'release.local' + // - Update the Version variable below on the master branch to the next + // expected version while retaining a pre-release of 'pre' + // + // These steps ensure that building from source produces versions that are + // distinct from reproducible builds that override the Version via linker + // flags. -// version returns the application version as a properly formed string per the -// semantic versioning 2.0.0 spec (http://semver.org/). -func version() string { - // Start with the major, minor, and patch versions. - version := fmt.Sprintf("%d.%d.%d", appMajor, appMinor, appPatch) - - // Append pre-release version if there is one. The hyphen called for - // by the semantic versioning spec is automatically appended and should - // not be contained in the pre-release string. The pre-release version - // is not appended if it contains invalid characters. - preRelease := normalizePreRelString(appPreRelease) - if preRelease != "" { - version = fmt.Sprintf("%s-%s", version, preRelease) - } + // Version is the application version per the semantic versioning 2.0.0 spec + // (https://semver.org/). + // + // It is defined as a variable so it can be overridden during the build + // process with: + // '-ldflags "-X main.Version=fullsemver"' + // if needed. + // + // It MUST be a full semantic version per the semantic versioning spec or + // the app will panic at runtime. Of particular note is the pre-release + // and build metadata portions MUST only contain characters from + // semanticAlphabet. + Version = "1.3.0-pre" - // Append build metadata if there is any. The plus called for - // by the semantic versioning spec is automatically appended and should - // not be contained in the build metadata string. The build metadata - // string is not appended if it contains invalid characters. - build := normalizeBuildString(appBuild) - if build != "" { - version = fmt.Sprintf("%s+%s", version, build) - } + // NOTE: The following values are set via init by parsing the above Version + // string. - return version + // These fields are the individual semantic version components that define + // the application version. + Major uint32 + Minor uint32 + Patch uint32 + PreRelease string + BuildMetadata string +) + +// parseUint32 converts the passed string to an unsigned integer or returns an +// error if it is invalid. +func parseUint32(s string, fieldName string) (uint32, error) { + val, err := strconv.ParseUint(s, 10, 32) + if err != nil { + return 0, fmt.Errorf("malformed semver %s: %w", fieldName, err) + } + return uint32(val), err } -// normalizeSemString returns the passed string stripped of all characters -// which are not valid according to the provided semantic versioning alphabet. -func normalizeSemString(str, alphabet string) string { - var result bytes.Buffer - for _, r := range str { - if strings.ContainsRune(alphabet, r) { - result.WriteRune(r) +// checkSemString returns an error if the passed string contains characters that +// are not in the provided alphabet. +func checkSemString(s, alphabet, fieldName string) error { + for _, r := range s { + if !strings.ContainsRune(alphabet, r) { + return fmt.Errorf("malformed semver %s: %q invalid", fieldName, r) } } - return result.String() + return nil } -// normalizePreRelString returns the passed string stripped of all characters -// which are not valid according to the semantic versioning guidelines for -// pre-release strings. In particular they MUST only contain characters in -// semanticAlphabet. -func normalizePreRelString(str string) string { - return normalizeSemString(str, semanticAlphabet) +// parseSemVer parses various semver components from the provided string. +func parseSemVer(s string) (uint32, uint32, uint32, string, string, error) { + // Parse the various semver component from the version string via a regular + // expression. + m := semverRE.FindStringSubmatch(s) + if m == nil { + err := fmt.Errorf("malformed version string %q: does not conform to "+ + "semver specification", s) + return 0, 0, 0, "", "", err + } + + major, err := parseUint32(m[1], "major") + if err != nil { + return 0, 0, 0, "", "", err + } + + minor, err := parseUint32(m[2], "minor") + if err != nil { + return 0, 0, 0, "", "", err + } + + patch, err := parseUint32(m[3], "patch") + if err != nil { + return 0, 0, 0, "", "", err + } + + preRel := m[4] + err = checkSemString(preRel, semanticAlphabet, "pre-release") + if err != nil { + return 0, 0, 0, "", "", err + } + + build := m[5] + err = checkSemString(build, semanticAlphabet, "buildmetadata") + if err != nil { + return 0, 0, 0, "", "", err + } + + return major, minor, patch, preRel, build, nil } -// normalizeBuildString returns the passed string stripped of all characters -// which are not valid according to the semantic versioning guidelines for build -// metadata strings. In particular they MUST only contain characters in -// semanticBuildAlphabet. -func normalizeBuildString(str string) string { - return normalizeSemString(str, semanticBuildAlphabet) +func init() { + var err error + Major, Minor, Patch, PreRelease, BuildMetadata, err = parseSemVer(Version) + if err != nil { + panic(err) + } + if BuildMetadata == "" { + BuildMetadata = vcsCommitID() + if BuildMetadata != "" { + Version = fmt.Sprintf("%d.%d.%d", Major, Minor, Patch) + if PreRelease != "" { + Version += "-" + PreRelease + } + Version += "+" + BuildMetadata + } + } } diff --git a/version_buildinfo.go b/version_buildinfo.go new file mode 100644 index 00000000..30032e30 --- /dev/null +++ b/version_buildinfo.go @@ -0,0 +1,35 @@ +// Copyright (c) 2021-2022 The Decred developers +// Use of this source code is governed by an ISC +// license that can be found in the LICENSE file. + +//go:build go1.18 +// +build go1.18 + +package main + +import "runtime/debug" + +// vcsCommitID attempts to return the version control system short commit hash +// that was used to build the binary. It currently only detects git commits. +func vcsCommitID() string { + bi, ok := debug.ReadBuildInfo() + if !ok { + return "" + } + var vcs, revision string + for _, bs := range bi.Settings { + switch bs.Key { + case "vcs": + vcs = bs.Value + case "vcs.revision": + revision = bs.Value + } + } + if vcs == "" { + return "" + } + if vcs == "git" && len(revision) > 9 { + revision = revision[:9] + } + return revision +} diff --git a/version_nobuildinfo.go b/version_nobuildinfo.go new file mode 100644 index 00000000..506a0adc --- /dev/null +++ b/version_nobuildinfo.go @@ -0,0 +1,14 @@ +// Copyright (c) 2021-2022 The Decred developers +// Use of this source code is governed by an ISC +// license that can be found in the LICENSE file. + +//go:build !go1.18 +// +build !go1.18 + +package main + +// vcsCommitID returns an empty string for all Go versions prior to 1.18 since +// the information is not available in binaries prior to that version. +func vcsCommitID() string { + return "" +}