Repository: decred/dcrd
Pull request #2651 (2021-05-14 07:10:07)

version: Rework to support single version override.
This reworks the way versions are handled internally to 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 and combines the pre-release and build normalization funcs since they are now the same.

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
- Is slightly more efficient since the full version string is no longer dynamically created on each invocation

Finally, while here, add some comments regarding the release process to help maintainers.


Patch:
diff --git a/internal/rpcserver/rpcserver.go b/internal/rpcserver/rpcserver.go
index 0a500c63..05579b69 100644
--- a/internal/rpcserver/rpcserver.go
+++ b/internal/rpcserver/rpcserver.go
@@ -5396,8 +5396,8 @@ func handleVerifyMessage(_ context.Context, s *Server, cmd interface{}) (interfa
 // handleVersion implements the version command.
 func handleVersion(_ context.Context, s *Server, cmd interface{}) (interface{}, error) {
 	runtimeVer := strings.Replace(runtime.Version(), ".", "-", -1)
-	buildMeta := version.NormalizeBuildString(runtimeVer)
-	build := version.NormalizeBuildString(version.BuildMetadata)
+	buildMeta := version.NormalizeString(runtimeVer)
+	build := version.NormalizeString(version.BuildMetadata)
 	if build != "" {
 		buildMeta = fmt.Sprintf("%s.%s", build, buildMeta)
 	}
@@ -5413,7 +5413,7 @@ func handleVersion(_ context.Context, s *Server, cmd interface{}) (interface{},
 			Major:         uint32(version.Major),
 			Minor:         uint32(version.Minor),
 			Patch:         uint32(version.Patch),
-			Prerelease:    version.NormalizePreRelString(version.PreRelease),
+			Prerelease:    version.NormalizeString(version.PreRelease),
 			BuildMetadata: buildMeta,
 		},
 	}
diff --git a/internal/version/version.go b/internal/version/version.go
index 23c851b3..bb0a1fe2 100644
--- a/internal/version/version.go
+++ b/internal/version/version.go
@@ -1,5 +1,5 @@
 // Copyright (c) 2013-2014 The btcsuite developers
-// Copyright (c) 2015-2020 The Decred developers
+// Copyright (c) 2015-2021 The Decred developers
 // Use of this source code is governed by an ISC
 // license that can be found in the LICENSE file.
 
@@ -10,94 +10,152 @@ package version
 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 (https://semver.org/).
-const (
-	Major uint = 1
-	Minor uint = 7
-	Patch 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 (
-	// PreRelease is defined as a variable so it can be overridden during the
-	// build process with:
-	// '-ldflags "-X github.com/decred/dcrd/internal/version.PreRelease=foo"'
-	// if needed.  It MUST only contain characters from semanticAlphabet per
-	// the semantic versioning spec.
-	PreRelease = "pre"
-
-	// BuildMetadata is defined as a variable so it can be overridden during the
-	// build process with:
-	// '-ldflags "-X github.com/decred/dcrd/internal/version.BuildMetadata=foo"'
-	// if needed.  It MUST only contain characters from semanticBuildAlphabet
-	// per the semantic versioning spec.
-	BuildMetadata = ""
+	// 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 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 github.com/decred/dcrd/internal/version.Version=fullsemver"'
+	// if needed.
+	//
+	// It MUST be a full semantic version per the semantic versioning spec or
+	// the package will panic at runtime.  Of particular note is the pre-release
+	// and build metadata portions MUST only contain characters from
+	// semanticAlphabet.
+	Version = "1.7.0-pre"
+
+	// NOTE: The following values are set via init by parsing the above Version
+	// string.
+
+	// These fields are the individual semantic version components that define
+	// the application version.
+	Major         uint
+	Minor         uint
+	Patch         uint
+	PreRelease    string
+	BuildMetadata string
 )
 
-// String returns the application version as a properly formed string per the
-// semantic versioning 2.0.0 spec (https://semver.org/).
-func String() string {
-	// Start with the major, minor, and patch versions.
-	version := fmt.Sprintf("%d.%d.%d", Major, Minor, Patch)
-
-	// 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(PreRelease)
-	if preRelease != "" {
-		version = fmt.Sprintf("%s-%s", version, preRelease)
+// parseUint converts the passed string to an unsigned integer or returns an
+// error if it is invalid.
+func parseUint(s string, fieldName string) (uint, error) {
+	val, err := strconv.ParseUint(s, 10, 0)
+	if err != nil {
+		return 0, fmt.Errorf("malformed semver %s: %w", fieldName, err)
+	}
+	return uint(val), err
+}
+
+// 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 nil
+}
+
+// parseSemVer parses various semver components from the provided string.
+func parseSemVer(s string) (uint, uint, uint, 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 := parseUint(m[1], "major")
+	if err != nil {
+		return 0, 0, 0, "", "", err
+	}
+
+	minor, err := parseUint(m[2], "minor")
+	if err != nil {
+		return 0, 0, 0, "", "", err
+	}
+
+	patch, err := parseUint(m[3], "patch")
+	if err != nil {
+		return 0, 0, 0, "", "", err
 	}
 
-	// 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(BuildMetadata)
-	if build != "" {
-		version = fmt.Sprintf("%s+%s", version, build)
+	preRel := m[4]
+	err = checkSemString(preRel, semanticAlphabet, "pre-release")
+	if err != nil {
+		return 0, 0, 0, s, s, err
 	}
 
-	return version
+	build := m[5]
+	err = checkSemString(build, semanticAlphabet, "buildmetadata")
+	if err != nil {
+		return 0, 0, 0, s, s, err
+	}
+
+	return major, minor, patch, preRel, build, nil
+}
+
+func init() {
+	var err error
+	Major, Minor, Patch, PreRelease, BuildMetadata, err = parseSemVer(Version)
+	if err != nil {
+		panic(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 {
+// String returns the application version as a properly formed string per the
+// semantic versioning 2.0.0 spec (https://semver.org/).
+func String() string {
+	return Version
+}
+
+// NormalizeString returns the passed string stripped of all characters which
+// are not valid according to the semantic versioning guidelines for pre-release
+// and build metadata strings.  In particular they MUST only contain characters
+// in semanticAlphabet.
+func NormalizeString(str string) string {
 	var result bytes.Buffer
 	for _, r := range str {
-		if strings.ContainsRune(alphabet, r) {
+		if strings.ContainsRune(semanticAlphabet, r) {
 			result.WriteRune(r)
 		}
 	}
 	return result.String()
 }
-
-// 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)
-}
-
-// 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)
-}


Test patch:
diff --git a/internal/rpcserver/rpcserverhandlers_test.go b/internal/rpcserver/rpcserverhandlers_test.go
index 4d725866..93b035c9 100644
--- a/internal/rpcserver/rpcserverhandlers_test.go
+++ b/internal/rpcserver/rpcserverhandlers_test.go
@@ -8087,8 +8087,8 @@ func TestHandleVersion(t *testing.T) {
 	runtimeVer := strings.Replace(runtime.Version(), ".", "-", -1)
 	version.BuildMetadata = "foo"
 	version.PreRelease = "pre"
-	buildMeta := version.NormalizeBuildString(
-		fmt.Sprintf("%s.%s", version.BuildMetadata, runtimeVer))
+	buildMeta := version.NormalizeString(fmt.Sprintf("%s.%s",
+		version.BuildMetadata, runtimeVer))
 
 	result := map[string]types.VersionResult{
 		"dcrdjsonrpcapi": {
diff --git a/internal/version/version_test.go b/internal/version/version_test.go
new file mode 100644
index 00000000..f694fdd7
--- /dev/null
+++ b/internal/version/version_test.go
@@ -0,0 +1,369 @@
+// Copyright (c) 2021 The Decred developers
+// Use of this source code is governed by an ISC
+// license that can be found in the LICENSE file.
+
+package version
+
+import "testing"
+
+// TestSemVerParsing ensures parsing a semantic version string works as
+// expected.
+func TestSemVerParsing(t *testing.T) {
+	tests := []struct {
+		ver     string // semantic version string to parse
+		major   uint   // expected major version
+		minor   uint   // expected minor version
+		patch   uint   // expected patch version
+		pre     string // expected pre-release string
+		build   string // expected build metadata string
+		invalid bool   // expected error
+	}{{
+		ver:   "0.0.4",
+		major: 0,
+		minor: 0,
+		patch: 4,
+	}, {
+		ver:   "1.2.3",
+		major: 1,
+		minor: 2,
+		patch: 3,
+	}, {
+		ver:   "10.20.30",
+		major: 10,
+		minor: 20,
+		patch: 30,
+	}, {
+		ver:   "1.1.2-prerelease+meta",
+		major: 1,
+		minor: 1,
+		patch: 2,
+		pre:   "prerelease",
+		build: "meta",
+	}, {
+		ver:   "1.1.2+meta",
+		major: 1,
+		minor: 1,
+		patch: 2,
+		build: "meta",
+	}, {
+		ver:   "1.1.2+meta-valid",
+		major: 1,
+		minor: 1,
+		patch: 2,
+		build: "meta-valid",
+	}, {
+		ver:   "1.0.0-alpha",
+		major: 1,
+		minor: 0,
+		patch: 0,
+		pre:   "alpha",
+	}, {
+		ver:   "1.0.0-beta",
+		major: 1,
+		minor: 0,
+		patch: 0,
+		pre:   "beta",
+	}, {
+		ver:   "1.0.0-alpha.beta",
+		major: 1,
+		minor: 0,
+		patch: 0,
+		pre:   "alpha.beta",
+	}, {
+		ver:   "1.0.0-alpha.beta.1",
+		major: 1,
+		minor: 0,
+		patch: 0,
+		pre:   "alpha.beta.1",
+	}, {
+		ver:   "1.0.0-alpha.1",
+		major: 1,
+		minor: 0,
+		patch: 0,
+		pre:   "alpha.1",
+	}, {
+		ver:   "1.0.0-alpha0.valid",
+		major: 1,
+		minor: 0,
+		patch: 0,
+		pre:   "alpha0.valid",
+	}, {
+		ver:   "1.0.0-alpha.0valid",
+		major: 1,
+		minor: 0,
+		patch: 0,
+		pre:   "alpha.0valid",
+	}, {
+		ver:   "1.0.0-alpha-a.b-c-somethinglong+build.1-aef.1-its-okay",
+		major: 1,
+		minor: 0,
+		patch: 0,
+		pre:   "alpha-a.b-c-somethinglong",
+		build: "build.1-aef.1-its-okay",
+	}, {
+		ver:   "1.0.0-rc.1+build.1",
+		major: 1,
+		minor: 0,
+		patch: 0,
+		pre:   "rc.1",
+		build: "build.1",
+	}, {
+		ver:   "2.0.0-rc.1+build.123",
+		major: 2,
+		minor: 0,
+		patch: 0,
+		pre:   "rc.1",
+		build: "build.123",
+	}, {
+		ver:   "1.2.3-beta",
+		major: 1,
+		minor: 2,
+		patch: 3,
+		pre:   "beta",
+	}, {
+		ver:   "10.2.3-DEV-SNAPSHOT",
+		major: 10,
+		minor: 2,
+		patch: 3,
+		pre:   "DEV-SNAPSHOT",
+	}, {
+		ver:   "1.2.3-SNAPSHOT-123",
+		major: 1,
+		minor: 2,
+		patch: 3,
+		pre:   "SNAPSHOT-123",
+	}, {
+		ver:   "1.0.0",
+		major: 1,
+		minor: 0,
+		patch: 0,
+	}, {
+		ver:   "2.0.0",
+		major: 2,
+		minor: 0,
+		patch: 0,
+	}, {
+		ver:   "1.1.7",
+		major: 1,
+		minor: 1,
+		patch: 7,
+	}, {
+		ver:   "2.0.0+build.1848",
+		major: 2,
+		minor: 0,
+		patch: 0,
+		build: "build.1848",
+	}, {
+		ver:   "2.0.1-alpha.1227",
+		major: 2,
+		minor: 0,
+		patch: 1,
+		pre:   "alpha.1227",
+	}, {
+		ver:   "1.0.0-alpha+beta",
+		major: 1,
+		minor: 0,
+		patch: 0,
+		pre:   "alpha",
+		build: "beta",
+	}, {
+		ver:   "1.2.3----RC-SNAPSHOT.12.9.1--.12+788",
+		major: 1,
+		minor: 2,
+		patch: 3,
+		pre:   "---RC-SNAPSHOT.12.9.1--.12",
+		build: "788",
+	}, {
+		ver:   "1.2.3----R-S.12.9.1--.12+meta",
+		major: 1,
+		minor: 2,
+		patch: 3,
+		pre:   "---R-S.12.9.1--.12",
+		build: "meta",
+	}, {
+		ver:   "1.2.3----RC-SNAPSHOT.12.9.1--.12",
+		major: 1,
+		minor: 2,
+		patch: 3,
+		pre:   "---RC-SNAPSHOT.12.9.1--.12",
+	}, {
+		ver:   "1.0.0+0.build.1-rc.10000aaa-kk-0.1",
+		major: 1,
+		minor: 0,
+		patch: 0,
+		build: "0.build.1-rc.10000aaa-kk-0.1",
+	}, {
+		ver:   "1.0.0-0A.is.legal",
+		major: 1,
+		minor: 0,
+		patch: 0,
+		pre:   "0A.is.legal",
+	}, {
+		ver:     "1",
+		invalid: true,
+	}, {
+		ver:     "1.2",
+		invalid: true,
+	}, {
+		ver:     "1.2.3-0123",
+		invalid: true,
+	}, {
+		ver:     "1.2.3-0123.0123",
+		invalid: true,
+	}, {
+		ver:     "1.1.2+.123",
+		invalid: true,
+	}, {
+		ver:     "+invalid",
+		invalid: true,
+	}, {
+		ver:     "-invalid",
+		invalid: true,
+	}, {
+		ver:     "-invalid+invalid",
+		invalid: true,
+	}, {
+		ver:     "-invalid.01",
+		invalid: true,
+	}, {
+		ver:     "alpha",
+		invalid: true,
+	}, {
+		ver:     "alpha.beta",
+		invalid: true,
+	}, {
+		ver:     "alpha.beta.1",
+		invalid: true,
+	}, {
+		ver:     "alpha.1",
+		invalid: true,
+	}, {
+		ver:     "alpha+beta",
+		invalid: true,
+	}, {
+		ver:     "alpha_beta",
+		invalid: true,
+	}, {
+		ver:     "alpha.",
+		invalid: true,
+	}, {
+		ver:     "alpha..",
+		invalid: true,
+	}, {
+		ver:     "beta",
+		invalid: true,
+	}, {
+		ver:     "1.0.0-alpha_beta",
+		invalid: true,
+	}, {
+		ver:     "-alpha.",
+		invalid: true,
+	}, {
+		ver:     "1.0.0-alpha..",
+		invalid: true,
+	}, {
+		ver:     "1.0.0-alpha..1",
+		invalid: true,
+	}, {
+		ver:     "1.0.0-alpha...1",
+		invalid: true,
+	}, {
+		ver:     "1.0.0-alpha....1",
+		invalid: true,
+	}, {
+		ver:     "1.0.0-alpha.....1",
+		invalid: true,
+	}, {
+		ver:     "1.0.0-alpha......1",
+		invalid: true,
+	}, {
+		ver:     "1.0.0-alpha.......1",
+		invalid: true,
+	}, {
+		ver:     "01.1.1",
+		invalid: true,
+	}, {
+		ver:     "1.01.1",
+		invalid: true,
+	}, {
+		ver:     "1.1.01",
+		invalid: true,
+	}, {
+		ver:     "1.2",
+		invalid: true,
+	}, {
+		ver:     "1.2.3.DEV",
+		invalid: true,
+	}, {
+		ver:     "1.2-SNAPSHOT",
+		invalid: true,
+	}, {
+		ver:     "1.2.31.2.3----RC-SNAPSHOT.12.09.1--..12+788",
+		invalid: true,
+	}, {
+		ver:     "1.2-RC-SNAPSHOT",
+		invalid: true,
+	}, {
+		ver:     "-1.0.3-gamma+b7718",
+		invalid: true,
+	}, {
+		ver:     "+justmeta",
+		invalid: true,
+	}, {
+		ver:     "9.8.7+meta+meta",
+		invalid: true,
+	}, {
+		ver:     "9.8.7-whatever+meta+meta",
+		invalid: true,
+	}, {
+		// Would be valid except major is > max uint64.
+		ver:     "99999999999999999999999.999999999999999999.99999999999999999",
+		invalid: true,
+	}, {
+		ver: "999999999.999999999.999999999----RC-SNAPSHOT.12.09.1-----------" +
+			"---------------------..12",
+		invalid: true,
+	}}
+
+	for _, test := range tests {
+		major, minor, patch, pre, build, err := parseSemVer(test.ver)
+		if test.invalid && err == nil {
+			t.Errorf("%q: did not receive expected error", test.ver)
+			continue
+		}
+		if !test.invalid && err != nil {
+			t.Errorf("%q: unexpected err: %v", test.ver, err)
+			continue
+		}
+
+		if major != test.major {
+			t.Errorf("%q: mismatched major -- got %d, want %d", test.ver,
+				major, test.major)
+			continue
+		}
+
+		if minor != test.minor {
+			t.Errorf("%q: mismatched minor -- got %d, want %d", test.ver,
+				minor, test.minor)
+			continue
+		}
+
+		if patch != test.patch {
+			t.Errorf("%q: mismatched patch -- got %d, want %d", test.ver,
+				patch, test.patch)
+			continue
+		}
+
+		if pre != test.pre {
+			t.Errorf("%q: mismatched pre-release -- got %s, want %s", test.ver,
+				pre, test.pre)
+			continue
+		}
+
+		if build != test.build {
+			t.Errorf("%q: mismatched buildmetadata -- got %s, want %s",
+				test.ver, build, test.build)
+			continue
+		}
+	}
+}