simver

package module
v0.31.0 Latest Latest
Warning

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

 Go to latest Published: May 28, 2024 License: Apache-2.0 Imports: 11 Imported by: 0

README

SimVer - Semantic Versioning Simplified 🔄

🌟 Overview

Forget about the headache of manual versioning. SimVer is here to automate and simplify semantic versioning in your Git workflow. By managing version tags directly linked to your commit activities, SimVer ensures a linear, predictable version history with zero manual overhead. Perfect for teams and developers looking for a set-it-and-forget-it solution, SimVer streamlines your development process, allowing you to focus on what truly matters - building great software.

🎯 Target Audience

SimVer is the go-to solution for developers and teams who:

  • Are exhausted by manual versioning complexities.
  • Desire a consistent, traceable version history.
  • Need seamless integration with CI/CD tools like GitHub Actions.

✨ Features

  • Automated Version Tags: Automatically generates semantic version tags for all commits and pull requests.
  • Clear Versioning Rules: Simplifies decision-making with straightforward rules for main and side branches.
  • Linear History Dependence: Ensures all version increments are predictable and orderly.

📘 How It Works

Versioning Logic Simplified
  • Direct Pushes to Main: Trigger minor version updates automatically.
  • Pull Requests:
    • To Main: Trigger minor updates.
    • To Side Branches: Apply patch updates.
    • Multiple Concurrent PRs: Ensure unique, sequential versioning without conflicts.
  • Merging: Versions merge seamlessly, with the target branch adopting the version from the merged branch or PR.
Tagging Made Easy
  • Main Branch: Receives clean, full release versions.
  • Side Branches and PRs: Get detailed pre-release tags to avoid confusion and maintain clarity.
Real-world Examples
  • Direct push to main changes v1.0.0 to v1.1.0.
  • A PR to main updates from v1.0.0 to v1.1.0.
  • A PR to a side branch updates from v1.1.0 to v1.1.1.
  • Handling multiple PRs ensures sequential updates without overlap.

🚀 Getting Started

Usage

Easily integrate SimVer into your GitHub Actions with this setup:

name: simver
permissions: { id-token: write, contents: write, pull-requests: read }
on:
    workflow_dispatch:
    push:
        branches: [main]
    pull_request:
        types: [opened, synchronize, reopened, closed]
jobs:
    simver:
        runs-on: ubuntu-latest
        steps:
            - uses: walteh/simver/cmd/gha-simver@v0
              with:
                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

⚠️ Current Limitations & 🛠 Future Fixes

  • Junk Tags Cleanup: Upcoming feature to clear temporary tags automatically. (#13)
  • Force Push Handling: We're improving how version recalculations handle force pushes to maintain accurate histories. (#6)

🤝 Contributing

Contributions are welcome! Fork, modify, and submit a pull request.

📜 License

Distributed under the MIT License. See LICENSE for more information.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	Err = errors.New("simver.Err")
)

Functions

func BumpPatch added in v0.1.34 

func BumpPatch[S ~string](arg S) S

func ExecutionAsString added in v0.13.0 

func ExecutionAsString(ctx context.Context, e Execution) (string, error)

func ForcePatch added in v0.1.34 

func ForcePatch(ctx context.Context, ee Execution, mmrt MMRT) bool

func LoadExecutionFromPR added in v0.18.0 

func LoadExecutionFromPR(ctx context.Context, tprov TagReader, prr PRResolver) (Execution, *PRDetails, error)

func Max added in v0.1.43 

func Max[A ~string, B ~string](a A, b B) string

func Skip added in v0.5.0 

func Skip(ctx context.Context, ee Execution, mmrt MMRT) bool

Types

type ActivePRProjectState added in v0.18.0 

type ActivePRProjectState struct {
	CurrentPR             *PRDetails
	CurrentRootBranchTags Tags
	CurrentRootCommitTags Tags
	CurrentHeadCommitTags Tags
	CurrentBaseCommitTags Tags
	CurrentBaseBranchTags Tags
	CurrentHeadBranchTags Tags
}

func (*ActivePRProjectState) BaseBranchTags added in v0.18.0 

func (e *ActivePRProjectState) BaseBranchTags() Tags

func (*ActivePRProjectState) HeadBranchTags added in v0.18.0 

func (e *ActivePRProjectState) HeadBranchTags() Tags

func (*ActivePRProjectState) HeadCommitTags added in v0.18.0 

func (e *ActivePRProjectState) HeadCommitTags() Tags

func (*ActivePRProjectState) IsMerge added in v0.18.0 

func (e *ActivePRProjectState) IsMerge() bool

func (*ActivePRProjectState) IsTargetingRoot added in v0.18.0 

func (e *ActivePRProjectState) IsTargetingRoot() bool

func (*ActivePRProjectState) PR added in v0.18.0 

func (e *ActivePRProjectState) PR() int

func (*ActivePRProjectState) ProvideRefs added in v0.18.0 

func (e *ActivePRProjectState) ProvideRefs() RefProvider

func (*ActivePRProjectState) RootBranch added in v0.18.0 

func (e *ActivePRProjectState) RootBranch() string

func (*ActivePRProjectState) RootBranchTags added in v0.18.0 

func (e *ActivePRProjectState) RootBranchTags() Tags

type BasicRefProvider added in v0.1.40 

type BasicRefProvider struct {
	HeadRef  string
	BaseRef  string
	RootRef  string
	MergeRef string
}

func (*BasicRefProvider) Base added in v0.1.40 

func (e *BasicRefProvider) Base() string

func (*BasicRefProvider) Head added in v0.1.40 

func (e *BasicRefProvider) Head() string

func (*BasicRefProvider) Merge added in v0.1.40 

func (e *BasicRefProvider) Merge() string

func (*BasicRefProvider) Root added in v0.1.40 

func (e *BasicRefProvider) Root() string

type Calculation 

type Calculation struct {
	MyMostRecentTag   MMRT
	MostRecentLiveTag MRLT
	MyMostRecentBuild MMRBN
	PR                int
	NextValidTag      NVT
	IsMerged          bool
	ForcePatch        bool
	Skip              bool
}

func Calculate added in v0.1.34 

func Calculate(ctx context.Context, ex Execution) *Calculation

func (*Calculation) CalculateNewTagsRaw 

func (me *Calculation) CalculateNewTagsRaw(ctx context.Context) *CalculationOutput

type CalculationOutput added in v0.1.31 

type CalculationOutput struct {
	BaseTags  []string
	HeadTags  []string
	RootTags  []string
	MergeTags []string
}

func (*CalculationOutput) ApplyRefs added in v0.1.31 

func (out *CalculationOutput) ApplyRefs(opts RefProvider) Tags

func (*CalculationOutput) CurrentBuildTag added in v0.20.0 

func (me *CalculationOutput) CurrentBuildTag(opts RefProvider) (string, string)

type Execution 

type Execution interface {
	PR() int
	IsTargetingRoot() bool
	IsMerge() bool
	HeadCommitTags() Tags
	HeadBranchTags() Tags
	BaseBranchTags() Tags
	RootBranchTags() Tags
	ProvideRefs() RefProvider
}

func NewLocalProjectState added in v0.18.0 

func NewLocalProjectState(ctx context.Context, gp GitProvider, tr TagReader) (Execution, error)

type GitProvider 

type GitProvider interface {
	GetHeadRef(ctx context.Context) (string, error)
	CommitFromRef(ctx context.Context, ref string) (string, error)
	Branch(ctx context.Context) (string, error)
	RepoName(ctx context.Context) (string, string, error)
	Dirty(ctx context.Context) (bool, error)
}

type LST added in v0.18.0 

type LST string // assumed last full decorated tag

type LocalProjectState added in v0.18.0 

type LocalProjectState struct {
	Commit string
	Branch string
	Tags   Tags
	Dirty  bool
}

func (*LocalProjectState) BaseBranchTags added in v0.18.0 

func (me *LocalProjectState) BaseBranchTags() Tags

BaseBranchTags implements Execution.

func (*LocalProjectState) HeadBranchTags added in v0.18.0 

func (me *LocalProjectState) HeadBranchTags() Tags

HeadBranchTags implements Execution.

func (*LocalProjectState) HeadCommitTags added in v0.18.0 

func (*LocalProjectState) HeadCommitTags() Tags

HeadCommitTags implements Execution.

func (*LocalProjectState) IsDirty added in v0.18.0 

func (me *LocalProjectState) IsDirty() bool

func (*LocalProjectState) IsLocal added in v0.18.0 

func (me *LocalProjectState) IsLocal() bool

func (*LocalProjectState) IsMerge added in v0.18.0 

func (*LocalProjectState) IsMerge() bool

IsMerge implements Execution.

func (*LocalProjectState) IsTargetingRoot added in v0.18.0 

func (me *LocalProjectState) IsTargetingRoot() bool

IsTargetingRoot implements Execution.

func (*LocalProjectState) PR added in v0.18.0 

func (*LocalProjectState) PR() int

PR implements Execution.

func (*LocalProjectState) ProvideRefs added in v0.18.0 

func (me *LocalProjectState) ProvideRefs() RefProvider

ProvideRefs implements Execution.

func (*LocalProjectState) RootBranchTags added in v0.18.0 

func (*LocalProjectState) RootBranchTags() Tags

RootBranchTags implements Execution.

type MAXLR added in v0.1.43 

type MAXLR string // max live or reserved tag

func MaxLiveOrReservedTag added in v0.1.43 

func MaxLiveOrReservedTag(mrlt MRLT, mrrt MRRT) MAXLR

type MAXMR added in v0.1.43 

type MAXMR string // max my reserved tag

func MaxMyOrReservedTag added in v0.1.43 

func MaxMyOrReservedTag(mrrt MRRT, mmrt MMRT) MAXMR

type MMRBN 

type MMRBN int // my most recent build number

func MyMostRecentBuildNumber 

func MyMostRecentBuildNumber(e Execution) MMRBN

type MMRT 

type MMRT string // my most recent tag

func MyMostRecentTag 

func MyMostRecentTag(e Execution) MMRT

type MRLT 

type MRLT string // most recent live tag

func MostRecentLiveTag 

func MostRecentLiveTag(e Execution) MRLT

type MRRT 

type MRRT string // most recent reserved tag

func MostRecentReservedTag 

func MostRecentReservedTag(e Execution) MRRT

type MRT added in v0.1.31 

type MRT string // my reserved tag

type NVT 

type NVT string // next valid tag

func GetNextValidTag 

func GetNextValidTag(ctx context.Context, minor bool, maxt MAXLR) NVT

type PRDetails 

type PRDetails struct {
	Number               int
	HeadBranch           string
	BaseBranch           string
	RootBranch           string // always main
	Merged               bool
	MergeCommit          string
	HeadCommit           string
	PotentialMergeCommit string

	BaseCommit string
	RootCommit string
}

func NewPushSimulatedPRDetails added in v0.1.45 

func NewPushSimulatedPRDetails(parentCommit, headCommit, branch string) *PRDetails

func (*PRDetails) Base added in v0.18.0 

func (me *PRDetails) Base() string

Base implements RefProvider.

func (*PRDetails) Head added in v0.18.0 

func (me *PRDetails) Head() string

Head implements RefProvider.

func (*PRDetails) IsSimulatedPush added in v0.1.45 

func (dets *PRDetails) IsSimulatedPush() bool

func (*PRDetails) Merge added in v0.18.0 

func (me *PRDetails) Merge() string

Merge implements RefProvider.

func (*PRDetails) Root added in v0.18.0 

func (me *PRDetails) Root() string

Root implements RefProvider.

type PRProvider 

type PRProvider interface {
	PRDetailsByPRNumber(ctx context.Context, prNumber int) (*PRDetails, bool, error)
	PRDetailsByCommit(ctx context.Context, commit string) (*PRDetails, bool, error)
	PRDetailsByBranch(ctx context.Context, branch string) (*PRDetails, bool, error)
}

type PRResolver added in v0.1.12 

type PRResolver interface {
	CurrentPR(ctx context.Context) (*PRDetails, error)
}

type RefProvider added in v0.1.40 

type RefProvider interface {
	Head() string
	Base() string
	Root() string
	Merge() string
}

type SingleRefProvider added in v0.18.0 

type SingleRefProvider struct {
	Ref string
}

func (*SingleRefProvider) Base added in v0.18.0 

func (e *SingleRefProvider) Base() string

func (*SingleRefProvider) Head added in v0.18.0 

func (e *SingleRefProvider) Head() string

func (*SingleRefProvider) Merge added in v0.18.0 

func (e *SingleRefProvider) Merge() string

func (*SingleRefProvider) Root added in v0.18.0 

func (e *SingleRefProvider) Root() string

type Tag added in v0.1.34 

type Tag struct {
	Name string
	Ref  string
}

type TagReader added in v0.17.0 

type TagReader interface {
	TagsFromCommit(ctx context.Context, commitHash string) (Tags, error)
	TagsFromBranch(ctx context.Context, branch string) (Tags, error)
}

type TagWriter added in v0.8.0 

type TagWriter interface {
	CreateTags(ctx context.Context, tag ...Tag) error
	FetchTags(ctx context.Context) (Tags, error)
}

type Tags 

type Tags []Tag

func (Tags) Copy added in v0.26.0 

func (t Tags) Copy() Tags

func (Tags) ExtractCommitRefs added in v0.1.40 

func (t Tags) ExtractCommitRefs() Tags

func (Tags) GetReserved 

func (t Tags) GetReserved() (Tag, bool)

func (Tags) MappedByName added in v0.1.40 

func (t Tags) MappedByName() map[string]string

func (Tags) MarshalZerologArray added in v0.1.44 

func (t Tags) MarshalZerologArray(a *zerolog.Array)

MarshalZerologArray implements zerolog.LogArrayMarshaler.

func (Tags) Names added in v0.1.40 

func (t Tags) Names() []string

func (Tags) SemversMatching added in v0.1.31 

func (t Tags) SemversMatching(matcher func(string) bool) []string

func (Tags) Sort added in v0.1.44 

func (t Tags) Sort() Tags

Source Files

View all Source files

Directories

Path Synopsis
cmd
gha-simver
gha-wait-on-simver
gen
mockery

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.