~m15a/bump.fnl

A CLI tool to bump version and update changelog

Test mail

~m15a via public-inbox

4 months ago

f279e9b tools(nix): remove unneeded packages

~m15a pushed to ~m15a/bump.fnl git

6 months ago
View project feed  RSS 

#Bump.fnl (0.5.3-dev)

bump.fnl - bump version and update changelog.

https://sr.ht/~m15a/bump.fnl

ci

#Synopsis

Bump command line argument version string:

$ bump 1.2.3-dev # Drop pre-release label by default.
1.2.3

$ bump 1.2.3-dev --major # or -M
2.0.0-dev

$ bump 1.2.3-dev --minor # or -m
1.3.0-dev

$ bump 1.2.3-dev --patch # or -p
1.2.4-dev

$ bump 1.2.3 --dev
1.2.4-dev

$ bump 1.2.3 --any-string
1.2.4-any-string

Bump version strings in Fennel code or text file:

$ bump bump.fnl && git diff

diff --git a/bump.fnl b/bump.fnl
index cefa8b4..c477853 100755
--- a/bump.fnl
+++ b/bump.fnl
@@ -95,7 +95,7 @@
 
 ;;;; ## API documentation
 
-(local version :0.4.0-dev)
+(local version :0.4.0)
 
 (local {: view : dofile} (require :fennel))

Bump version and update headings and URLs in Markdown changelog:

$ bump CHANGELOG.md && git diff

diff --git a/CHANGELOG.md b/CHANGELOG.md
index a5a8b31..92c350a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning][2].
 [1]: https://keepachangelog.com/en/1.1.0/
 [2]: https://semver.org/spec/v2.0.0.html
 
-## [0.4.0-dev] - ???
+## [0.4.0] - 2024-03-26 +0900
 
 ## [0.3.1] - 2024-03-22 +0900
 
@@ -57,7 +57,7 @@ and this project adheres to [Semantic Versioning][2].
 
 - Script to bump version string easily.
 
-[0.4.0-dev]: https://git.sr.ht/~m15a/bump.fnl/refs/HEAD
+[0.4.0]: https://git.sr.ht/~m15a/bump.fnl/refs/v0.4.0
 [0.3.1]: https://git.sr.ht/~m15a/bump.fnl/refs/v0.3.1
 [0.3.0]: https://git.sr.ht/~m15a/bump.fnl/refs/v0.3.0
 [0.2.0]: https://git.sr.ht/~m15a/bump.fnl/refs/v0.2.0

#Description

bump.fnl bumps version string and update changelog. You can use it in command line as shown in Synopsis: it can

  • bump command line argument version string;
  • bump version string contained in Fennel code or text file; or
  • update Markdown changelog automatically according to intended version bumping (experimental feature).

The last feature should work for any Markdown changelog of style similar to keep a changelog, at least a style like ./CHANGELOG.md.

See an example usage ./example.bash.

It is also a Fennel library for general-purpose SemVer version string manipulation. It provides functions to

  • compose/decompose version string from/to table containing major, minor, and patch numbers, prerelease label, and build meta tag;
  • compare and query about version strings;
  • bump version string; and
  • parse text to search for version strings.

See API documentation for more details.

#Installation

#Do it yourself

For manual installation, it requires the following dependencies.

  • PUC Lua 5.1+ or LuaJIT: runtime dependency.
  • Fennel 1.4.2+: required only for compiling to Lua script or for using it as a library. Not tested but it might even work with older versions.
  • GNU make: to run build tasks.

Run make and then you will find a Lua executable script bin/bump. Install it anywhere:

$ make install PREFIX=$YOUR_FAVORITE_PATH
#Docker

You can build and use a Docker image to run bump.fnl without installing Lua and Fennel to your environment. It requires GNU make to run build task though.

Run make docker-image and then you will get bump.fnl:latest image. You might want to write a wrapper shell script:

#!/bin/sh
exec docker run -t --rm -v $PWD:/work bump.fnl "$@"
#Nix flake

If you are a Nix flake user, try bump.fnl one time:

$ nix run sourcehut:~m15a/bump.fnl -- --help

To use it as an overlay in your project,

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
    flake-utils.url = "github:numtide/flake-utils";
    ...
    bumpfnl.url = "sourcehut:~m15a/bump.fnl/main";
  };
  outputs = inputs@{ self, nixpkgs, flake-utils, ... }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = import nixpkgs {
          inherit system;
          overlays = [
            ...
            inputs.bumpfnl.overlays.default
          ];
        };
      in {
        devShells.default = pkgs.mkShell {
          packages = [
            ...
            pkgs.bumpfnl
          ];
        };
      });
}
#Use it as a Fennel library

Copy ./bump.fnl into your project. Make sure that it is on Fennel search path, or add it to environment variable $FENNEL_PATH.

#API documentation

Table of contents

#Function: bump/major

(bump/major version)

Bump major version number in the version string.

#Example
(bump/major "0.9.28") ;=> "1.0.0"

#Function: bump/minor

(bump/minor version)

Bump minor version number in the version string.

#Example
(bump/minor "0.9.28") ;=> "0.10.0"

#Function: bump/patch

(bump/patch version)

Bump patch version number in the version string.

#Example
(bump/patch "0.9.28") ;=> "0.9.29"

#Function: bump/prerelease

(bump/prerelease version ?prerelease)

Append ?prerelease label (default: dev) to the version string.

Besides, it strips build tag and increments patch version number. If you like to increment other than patch number, compose it with any other bump/* function.

#Examples
(bump/prerelease "1.2.0") ;=> "1.2.1-dev"
(bump/prerelease "1.2.0" :alpha) ;=> "1.2.1-alpha"

(-> "1.1.4"
    bump/prerelease
    bump/minor)
;=> "1.2.0-dev"

#Function: bump/release

(bump/release version)

Strip pre-release and/or build label(s) from the version string.

#Example
(bump/release "1.2.1-dev+001") ;=> "1.2.1"

#Function: compose

(compose {:build build :major major :minor minor :patch patch :prerelease prerelease})

Compose version string from a table that contains:

  • major: major version,
  • minor: minor version,
  • patch: patch version, and
  • prerelease: suffix label that implies pre-release version (optional).
  • build: suffix label that attaches build meta information (optional).
#Example
(compose {:major 0 :minor 1 :patch 0 :prerelease :dev})
;=> "0.1.0-dev"

#Function: decompose

(decompose version)

Decompose version string to a table containing its components.

See compose for components' detail.

#Examples
(decompose "1.1.0-rc.1")
;=> {:major 1 :minor 1 :patch 0 :prerelease :rc.1}

(decompose "0.3.1-dev+001")
;=> {:major 0 :minor 3 :patch 1 :prerelease :dev :build :001}

#Function: gparse

(gparse text)

Return an iterator that returns version strings in the text one by one.

#Example
(let [text "4.5.6.7 1.2.3+m 4.3.2a v1.2.3 1.2.3-dev+a2"]
  (doto (icollect [v (gparse text)] v)
    table.sort))
;=> ["1.2.3" "1.2.3+m" "1.2.3-dev+a2"]

#Function: parse

(parse text ?init)

Return the first version string found in the text.

Version string in version tag (e.g., v1.2.3) will also be picked up. Optional ?init specifies where to start the search (default: 1).

#Examples
(parse " v1.0.0 1.0.0-alpha 1.0.1") ;=> "1.0.0"
(parse "1.0.0 2.0.0" 2) ;=> "2.0.0"

#Function: prerelease?

(prerelease? x)

If x is a prerelease version string, return true; otherwise false.

#Examples
(prerelease? "1.0.0+sha.a1bf00a") ;=> false
(prerelease? "1.0.0-alpha") ;=> true

#Function: release?

(release? x)

If x is a release version string, return true; otherwise false.

#Examples
(release? "1.0.0+sha.a1bf00a") ;=> true
(release? "1.0.0-alpha") ;=> false

#Function: version<

(version< left right)

Return true if left version is older than right; otherwise false.

#Examples
(version< :1.0.0-alpha :1.0.0-alpha.1) ;=> true
(version< :1.0.0-alpha.1 :1.0.0-alpha.beta) ;=> true
(version< :1.0.0-alpha.beta :1.0.0-beta) ;=> true
(version< :1.0.0-beta.2 :1.0.0-beta.11) ;=> true
(version< :1.0.0-beta.11 :1.0.0-rc.1) ;=> true
(version< :1.0.0-rc.1 :1.0.0) ;=> true

#Function: version<=

(version<= left right)

Return true if left version is older than or equal to right.

Otherwise false.

#Function: version<>

(version<> left right)

Return true if left and right versions have different precedence.

Otherwise false. Note that build tags are ignored for version comparison.

#Example
(version<> :1.0.0-alpha+001 :1.0.0-alpha+100) ;=> false

#Function: version=

(version= left right)

Return true if left and right versions have the same precedence.

Otherwise false. Note that build tags are ignored for version comparison.

#Example
(version= :1.0.0-alpha+001 :1.0.0-alpha+010) ;=> true

#Function: version>

(version> left right)

Return true if left version is newer than right; otherwise false.

#Function: version>=

(version>= left right)

Return true if left version is newer than or equal to right.

Otherwise false.

#Function: version?

(version? x)

If x is a version string, return true; otherwise return false.

#Examples
(version? "1.2.3-dev+111") ;=> true
(version? {:major 1 :minor 2 :patch 3}) ;=> false

Copyright (c) 2024 NACAMURA Mitsuhiro

License: BSD 3-clause