versioned

package module
v1.0.30 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 6, 2024 License: MIT Imports: 13 Imported by: 30

README

versioned

Simplified package metadata management for Go packages.

This repository contains:

  • github.com/greenpau/versioned: Go package (library)
  • github.com/greenpau/versioned/cmd/versioned: Command-line package metadata management utility

Table of Contents

Getting Started

First, install versioned:

go get -u github.com/greenpau/versioned/cmd/versioned
Increment MAJOR.MINOR.PATCH Versions

Browse to a repository and initialize VERSION file with versioned:

versioned -init

Display current version of the repo:

versioned

Update patch version in VERSION file:

$ versioned -patch
increased patch version by 1, current version: 1.0.1
updated version: 1.0.1, previous version: 1.0.0

Do the same operation silently:

versioned -patch -silent

Update minor version in VERSION file:

versioned -minor

Update major version in VERSION file:

versioned -major
Makefile Usage

Another way of using versioned is adding the following release step in a Makefile:

APP_NAME="myapp"
GIT_BRANCH:=$(shell git rev-parse --abbrev-ref HEAD -- | head -1)

release:
        @echo "Making release"
        @if [ $(GIT_BRANCH) != "master" ]; then echo "cannot release to non-master branch $(GIT_BRANCH)" && false; fi
        @git diff-index --quiet HEAD -- || ( echo "git directory is dirty, commit changes first" && false )
        @versioned -patch
        @git add VERSION
        @git commit -m 'updated VERSION file'
        @versioned -sync cmd/$(APP_NAME)/main.go
        @echo "Patched version"
        @git add cmd/$(APP_NAME)/main.go
        @git commit -m "released v`cat VERSION | head -1`"
        @git tag -a v`cat VERSION | head -1` -m "v`cat VERSION | head -1`"
        @git push
        @git push --tags
        @echo "If necessary, run the following commands:"
        @echo "  git push --delete origin v$(APP_VERSION)"
        @echo "  git tag --delete v$(APP_VERSION)"

Package Metadata

Golang

For demonstration, please consider that a developer manages the following code as part of main.go:

package main

import (
        "flag"
        "fmt"
        "github.com/greenpau/versioned"
        "os"
)

var (
        app        *versioned.PackageManager
        appVersion string
        gitBranch  string
        gitCommit  string
        buildUser  string
        buildDate  string
)

func init() {
    app = versioned.NewPackageManager("myapp")
    app.Description = "MyApp"
    app.Documentation = "https://github.com/me/myapp"
    app.SetVersion(appVersion, "1.0.0")
    app.SetGitBranch(gitBranch, "master")
    app.SetGitCommit(gitCommit, "v1.0.0-dirty")
    app.SetBuildUser(buildUser, "")
    app.SetBuildDate(buildDate, "")
}

In the init() function, the developer initializer versioned package manager and sets default application name, description, and documentation. These do not change at runtime.

Next, notice the var section, where there are a number of string variable. At runtime, the values of the variables are not initialized. The values are empty strings.

One way to initialize them is using ldflags at build time. Here, the APP_VERSION variable is set to the value from VERSION file.

Then, the variable is being user to set main.appVersion. The main is the package in the code above and appVersion is the variable that are being set at build time.

APP_VERSION:=$(shell cat VERSION | head -1)
GIT_COMMIT:=$(shell git describe --dirty --always)
GIT_BRANCH:=$(shell git rev-parse --abbrev-ref HEAD -- | head -1)
BUILD_USER:=$(shell whoami)
BUILD_DATE:=$(shell date +"%Y-%m-%d")

        @CGO_ENABLED=0 go build -o bin/myapp -v \
                -ldflags="-w -s \
                -X main.appVersion=$(APP_VERSION) \
                -X main.gitBranch=$(GIT_BRANCH) \
                -X main.gitCommit=$(GIT_COMMIT) \
                -X main.buildUser=$(BUILD_USER) \
                -X main.buildDate=$(BUILD_DATE)" \
                -gcflags="all=-trimpath=$(GOPATH)/src" \
                -asmflags="all=-trimpath $(GOPATH)/src" cmd/mypapp/*.go

The end result os that the following variables are being set with values.

        appVersion string
        gitBranch  string
        gitCommit  string
        buildUser  string
        buildDate  string

However, what happen when a user does not use -ldflags.

In that case, versioned sets a number of defaults. For example, if appVersion is not being wtih -ldflags, then the default 1.0.0 will be set.

    app.SetVersion(appVersion, "1.0.0")
    app.SetGitBranch(gitBranch, "master")
    app.SetGitCommit(gitCommit, "v1.0.0-dirty")
    app.SetBuildUser(buildUser, "")
    app.SetBuildDate(buildDate, "")

A developer, prior to releasing code, would put proper defaults. This way when someone build the code, it would inherit a set of default values for version, git, and build metadata.

Further, the versioned can be used to update the default values.

versioned -sync cmd/myapp/main.go
Python

The versioned inspects Python file for the presense of __version__ module level dunder (see PEP 8) and, if necessary, updates the version to match the one found in VERSION file.

The following command detects the code uses Python based on the .py extension and synchronizes the version.

versioned -sync requests.py

Alternatively, when a Python file does not have an extension, use --format to explicitly state the way the file should be handled.

versioned -sync app-client --format python

Additionally, if a file is a part of a Python package, then there is no need for VERSION file. Rather, use --source to indicate the source of truth for version information.

versioned --source setup.py -sync requests.py
Node.js, Javascript, Typescript

The versioned inspects npm package file for version information. The following command displays the current version of a package.

$ versioned --source package.json
1.0.1

The following command patches the version to 1.0.2:

$ versioned --source package.json --patch
increased patch version by 1, current version: 1.0.2
updated version: 1.0.2, previous version: 1.0.1

As for the synchronization of the version in package.json and other files in the package, the following rules apply.

Consider creating src/Config.ts Typescript file.

export const Config = {
  Version: "1.0.0",
};

The versioned finds a reference to Version and syncronizes the value:

versioned --source package.json --sync src/Config.ts

After running the above command, the version in package.json and src/Config.ts will be identical.

export const Config = {
  Version: "1.0.2",
};

Markdown Table of Contents

The versioned is capable of generating and updating of a Table of Contents (TOC) in Markdown README.md file.

The following command either generates or updates the Table of Contents in README.md file:

versioned --toc

Alternatively, specify Markdown file path:

versioned -toc -filepath ./another_doc.md

License Header

The versioned is capable of update license header. The default license type is Apache License 2.0:

versioned -addlicense -copyright="Paul Greenberg (greenpau@outlook.com)" -year=2020 -filepath ./main.go

The following command finds all .swift files and adds GPLv3 license header.

for src_file in `find ./ -type f -name '*.swift'`; do
  versioned -addlicense -copyright="Paul Greenberg (greenpau@outlook.com)" -year=2023 -license gpl3 -filepath=$src_file;
done

The available license headers are:

  • mit
  • asl
  • apache
  • gpl3

The following command removes license header from a file:

versioned -striplicense -filepath=toc_test.go

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddLicense added in v1.0.26 

func AddLicense(h *LicenseHeader) error

AddLicense adds a license header to a file.

func StripLicense added in v1.0.26 

func StripLicense(h *LicenseHeader) error

StripLicense remove a license header from a file.

func UpdateToc added in v1.0.25 

func UpdateToc(toc *TableOfContents) error

UpdateToc updates table of contents of the provided file.

Types

type LicenseHeader added in v1.0.25 

type LicenseHeader struct {
	FilePath        string
	FileExtension   string
	Year            uint64
	CopyrightHolder string
	LicenseType     string
	Action          string
	// contains filtered or unexported fields
}

LicenseHeader represent license headers.

func NewLicenseHeader added in v1.0.25 

func NewLicenseHeader() *LicenseHeader

NewLicenseHeader returns an instance of LicenseHeader.

func (*LicenseHeader) AddCopyrightHolder added in v1.0.25 

func (h *LicenseHeader) AddCopyrightHolder(s string) error

AddCopyrightHolder adds copyright holder.

func (*LicenseHeader) AddFilePath added in v1.0.25 

func (h *LicenseHeader) AddFilePath(fp string) error

AddFilePath adds the path to a file.

func (*LicenseHeader) AddLicenseType added in v1.0.25 

func (h *LicenseHeader) AddLicenseType(s string) error

AddLicenseType adds license type.

func (*LicenseHeader) AddYear added in v1.0.25 

func (h *LicenseHeader) AddYear(i uint64) error

AddYear adds copyright year.

type PackageManager added in v1.0.15 

type PackageManager struct {
	Name          string        `json:"name" xml:"name" yaml:"name"`
	Version       string        `json:"version" xml:"version" yaml:"version"`
	Description   string        `json:"description" xml:"description" yaml:"description"`
	Documentation string        `json:"documentation" xml:"documentation" yaml:"documentation"`
	Git           gitMetadata   `json:"git" xml:"git" yaml:"git"`
	Build         buildMetadata `json:"build" xml:"build" yaml:"build"`
}

PackageManager stores metadata about a package.

func NewPackageManager added in v1.0.15 

func NewPackageManager(s string) *PackageManager

NewPackageManager return an instance of PackageManager.

func (*PackageManager) Banner added in v1.0.15 

func (p *PackageManager) Banner() string

Banner returns package

func (*PackageManager) SetBuildDate added in v1.0.15 

func (p *PackageManager) SetBuildDate(v, d string)

SetBuildDate sets Build.Date attribute of PackageManager.

func (*PackageManager) SetBuildUser added in v1.0.15 

func (p *PackageManager) SetBuildUser(v, d string)

SetBuildUser sets Build.User attribute of PackageManager.

func (*PackageManager) SetGitBranch added in v1.0.15 

func (p *PackageManager) SetGitBranch(v, d string)

SetGitBranch sets Git.Branch attribute of PackageManager.

func (*PackageManager) SetGitCommit added in v1.0.15 

func (p *PackageManager) SetGitCommit(v, d string)

SetGitCommit sets Git.Commit attribute of PackageManager.

func (*PackageManager) SetVersion added in v1.0.15 

func (p *PackageManager) SetVersion(v, d string)

SetVersion sets Version attribute of PackageManager.

func (*PackageManager) ShortBanner added in v1.0.15 

func (p *PackageManager) ShortBanner() string

ShortBanner returns one-line information about a package.

func (*PackageManager) String added in v1.0.15 

func (p *PackageManager) String() string

type TableOfContents added in v1.0.22 

type TableOfContents struct {
	FilePath string
	// contains filtered or unexported fields
}

TableOfContents represent Markdown Table of Contents section.

func NewTableOfContents added in v1.0.22 

func NewTableOfContents() *TableOfContents

NewTableOfContents return a new instance of TableOfContents.

func (*TableOfContents) AddFilePath added in v1.0.25 

func (toc *TableOfContents) AddFilePath(s string)

AddFilePath adds markdown file path.

func (*TableOfContents) AddHeading added in v1.0.22 

func (toc *TableOfContents) AddHeading(s string) error

AddHeading adds an entry to TableOfContents.

func (*TableOfContents) ToString added in v1.0.22 

func (toc *TableOfContents) ToString() string

ToString return string representation of TableOfContents.

type Version 

type Version struct {
	Major    uint64
	Minor    uint64
	Patch    uint64
	FilePath string
	FileName string
	FileType string
	FileDir  string
}

Version represents a software version. The version format is `major.minor.patch`.

func NewVersion 

func NewVersion(s string) (*Version, error)

NewVersion returns an instance of Version.

func NewVersionFromFile 

func NewVersionFromFile(fp string) (*Version, error)

NewVersionFromFile return Version instance by reading VERSION file in a current directory.

func (*Version) Bytes 

func (v *Version) Bytes() []byte

Bytes returns byte representation of Version string.

func (*Version) IncrementMajor 

func (v *Version) IncrementMajor(i uint64)

IncrementMajor increments major version

func (*Version) IncrementMinor 

func (v *Version) IncrementMinor(i uint64)

IncrementMinor increments minor version

func (*Version) IncrementPatch 

func (v *Version) IncrementPatch(i uint64)

IncrementPatch increments patch version

func (*Version) SetFile added in v1.0.22 

func (v *Version) SetFile(fp string) error

SetFile sets file details of Version.

func (*Version) String 

func (v *Version) String() string

String returns string representation of Version.

func (*Version) UpdateFile 

func (v *Version) UpdateFile() error

UpdateFile updates version information in the file associated with the version.

Source Files

View all Source files

Directories

Path Synopsis
cmd
versioned

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.