Golang uses Github to host the Go library. This article introduces the version management of the Go library.

Go library version rules

The rule for the go library version: major version number. Revision number, where:

  • Major version number: the major version number is appended when the library is modified in a way that is not backward compatible, such as feature refactoring.
  • Minor version number: retrograde compatible changes to the library, such as new functionality, are appended to the minor version number;
  • Revision number: When the library has made a downward compatible change (on a smaller scale), such as a fix or optimization feature, the revision is appended.

Go class library version example

Again, take the github.com/vsixz/common-go class library as an example.

Minor Version Upgrade

Major version is not upgraded, minor or revised version is upgraded.

X.x can be directly upgraded to v1.x.x.

The current version is v1.0.0, now we have made functional modifications to the class library, release V1.0.1:

1. Switch torelease/1.xbranch

git checkout release/v1.x
Copy the code

2. Modify the library code

3. Submit the code and publish it

git add .
git commit -m "update hello"Git push git tag v1.0.1Copy the code

4, the use ofdemo-goTest and upgrade the version

How to upgrade the library:

  • usego get -u xxxUpgrade to the latest version under the major version number;
  • usego get xxx@versionUpgrade to a specified version.
$go get -u github.com/vsixz/common-go go: downloading github.com/vsixz/common-go v1.0.1 go: found github.com/vsixz/common-go/helloin github.com/vsixz/common-go v1.0.1
go: github.com/vsixz/common-go upgrade => v1.0.1
Copy the code

Look at the go.mod file under Demo-go and see that it has been upgraded to the new version:

5. Run tests

$ go run main.go
testHello: Hello, Jay common-go version: v1.0.1Copy the code

Major Upgrade

Major version upgrade.

Note that when using go Get -u XXX to upgrade the version of the class library, it cannot be upgraded across the major version, but can only be upgraded to the latest minor version under the current major version.

X to v1.x.x is an exception. You can run the go get -u XXX command to upgrade the v0.x.x.

The current version is V1.0.1, now the function of this library has been reconstructed, release v2.0.0:

1. Continue to follow best practices2.xVersion branching

git checkout -b release/v2.x
Copy the code

2. Create the class library in the root directoryv2Directory, and put the current project go class library andgo.modFull copy (or cut) tov2directory

3. Modify module name to new version

go mod edit -module github.com/vsixz/common-go/v2 v2/go.mod
Copy the code

Check out the v2/go.mod file:

After the module name is changed, if the go file in the v2 directory references the package of the class library, you need to update reference v2; otherwise, the reference package cannot be found.

4, v2 class library new features

5. Submit the code and publish

git add .
git commit -m "refactor hello to v2"Git tag v2.0.0 git tag --tagsCopy the code

6, use,demo-goTest and upgrade the version

Note that you cannot use go get -u XXX to upgrade to the latest version that is different from the current major version. You need to use go get xxx@version to upgrade:

$go get github.com/vsixz/common-go/[email protected]Copy the code

Check the go.mod file to see that the v2 version dependency package has been added

7. Modify the test code

Using both v1 and v2 package functions:

8. Run tests

$ go run main.go
testHello: Hello, Jay common-go version: v1.0.1 Hello, Jay Chou common-go version: v2.0.0Copy the code

Use the native GO class library

If the local GO library is not maintained remotely, how do I refer to the package of the local library?

Use replace to reference the local GO library in the go.mod file, which is sometimes easier to develop.

The module name of common-go is github.com/vsixz/common-go

Replace replaces references to modules with go library relative paths

The following example switches a reference to the GO class library to a local reference.

Since this is a local reference, the version number only needs to be in the range of the main version number.

conclusion

Major version upgrades make code maintenance and version maintenance more difficult, and require downstream users to migrate versions. It is best to upgrade the main version of the library when there is a compelling reason to do so, such as to optimize the code for large-scale refactoring.