fsaintjacques / semver-tool Goto Github PK

Thank you for this tool!

It would be nice to have the ability to construct requirement strings (eg. relax requirements while parsing the output of some package manager) through a template like $MAJOR.$MINOR.*. Of course this can be done by concatenating $(... get major).$(... get minor).*, but it will be more ergonomic to pass a template string in.

Hi fsaintjacques

Independently of your tool (I only just found it now!) I built a git plugin for semantic versioning:

https://github.com/markchalloner/git-semver

This also has it's own plugin architecture that can be used for validating versions scattered around projects (e.g. change log, manifests etc), as well as a built in updater.

As the two project seem pretty complimentary, I was wondering if you would be interested in merging the two in a new independent organisation account and working together on it?

Thanks

Looking at the GitHub action logs, I noticed the following:

asdf install semver latest
asdf global semver latest
semver --version
semver: 3.3.0

which seemed a bit strange because the action (unit tests and lint):

1. should have been running against a non-released commit of semver
2. appeared to be running against a non-latest release (we are at 3.4.0)

As well, the log output claim "asdf install semver latest" is simply the output of echo "asdf install semver latest". The actual install specifies version 3.3.0.

After I ran a couple tests, it turns out that the GitHub action tests do run (AFAICS) against the appropriate semver commit. Ouff.

On the other hand, the output is confusing and it's not clear what the point of downloading a specific version and echoing the version string when that is not (in most cases) the code being tested.

And more: the GitHub action code requires/downloads version 1.3.0 of Bats while the project moved to version 1.6.0 a bit before the GitHub action code was committed. On the upside, the action code did specify a version for the spellcheck dependency (the Makefile does not).

These problems seem to be the result of:

1. non-DRY parameterization
2. distributed dependency management
3. two separate testing paths: a Makefile running tests under Docker and using *nix install; a GitHub action script (ci.yaml) with it's own test execution scripting and asdf installation

Suggested steps to clean this up (in priority order):

1. At a minimum: specify exact and consistent versions for dependencies; maybe use variables rather than imbedded constants.
2. Remove or clarify/adjust the script that downloads a specific release of semver and prints its version string; then tests something else.
3. Create a little file with dependencies defined once and in one place. Use these definitions in the various scripts and tools.
4. Eliminate the difference between local testing and automated (GitHub actions) testing: GitHub actions become wrappers around the local testing scripts/tools. If asdf installation is to be tested (good idea! same for the other installation methods!), it should be explicitly tested: not by simply using it as part of the GitHub actions.

This seems a regression of #6. Running semver compare 1.8.1 1.8.1-rc2 should return 1 but returns -1

Currently, there are three "bats" unit test files. There does not seem to be a motivation (why 3?), a naming convention, or consistency (different files test different things .. but then they sometimes overlap).
A clean-up is needed. Suggestion: a single file, with tests organised by type/functionality (simple and just fine for a simple tool); or factor this out into separate files (can do this later if there is really a need).

We use a combination of the semver diff and bump to increment our docker images version based on included librairies in the docker file. However some of these libs don't use semver and we had to resort to a small hack. Having a command to check if something is a valid semver would be usefull.

Here is a snippet of what we are doing

set +e
semver get major ${CURRENT_APP_VERSION} >/dev/null 2>&1
IS_SEMVER=$?
set -e

if [[ ${IS_SEMVER} -eq 0 ]]; then
  NEW_IMAGE_VERSION=$(semver bump $(semver diff ${CURRENT_APP_VERSION} ${NEW_APP_VERSION}) ${CURRENT_IMAGE_VERSION})
else
  NEW_IMAGE_VERSION=$(semver bump major ${CURRENT_IMAGE_VERSION})
fi

What I would be looking at is removing the first 4 lines and basically using something like this instead

if [[ $(semver isvalid ${CURRENT_APP_VERSION}) -eq 0 ]]; then
  NEW_IMAGE_VERSION=$(semver bump $(semver diff ${CURRENT_APP_VERSION} ${NEW_APP_VERSION}) ${CURRENT_IMAGE_VERSION})
else
  NEW_IMAGE_VERSION=$(semver bump major ${CURRENT_IMAGE_VERSION})
fi

Dear dev team,

I'm currently automating my build pipeline to apply semantic versioning. In the frontend app this is already working fine done with npm version.
Whenever I have a "feature" oder "bugfix" branch, the pipeline is calling "npm verion prerelease --preid=dev". The first "prelease" call is adding the prerelease but also bumping the patch version. So I can always call this function:

• 0.1.0 --> 0.1.1-dev.1
• 0.1.1-dev.1 --> 0.1.1-dev.2

Merging back to master then calls a patch bump ("npm version patch" from 0.1.1-dev.2 to 0.1.1).
As you can see, the patch bump is not increasing the patch but just removing the prerelease part.

semver bump works a little bit different:

• semver bump prerel dev.. 0.1.0 --> 0.1.0-dev.1
• semver bump prerel dev.. 0.1.0-dev.1 --> 0.1.0-dev.2
• semver bump patch 0.1.0-dev.1 --> 0.1.1

My intuitive understanding is that npm patch bump works correctly. You want to switch from 1.0.0-rc.1 to 1.0.0

Now my question: Is there any option to make semver work the same way?

1. Increaing the patch version in a prerelease bump in case there is no prerelease part yet
2. Not increasing the patch version in a patch bump in case there is a prerelease part

In order to improve compatibility with shells function identifiers may not contain a hyphens '-'

The following shells are known not to support hyphens in function names:

* ash (busybox), csh, tcsh, dash

Source: https://unix.stackexchange.com/a/168222

Proposal:
function usage-version { --> function usage_version {

it would be great if this tool could bump the number of a prerel, for example something like

$ semver bump prerel alpha 1.2.3-alpha.3
1.2.3-alpha.4

Currently bumping a prerel strips any numbered versioning that prerelease version has.

Would be great to see this tool available right from the package repository. Personally I care about .deb but I imagine others would be interested in other package formats as well.

Hi François,

in https://github.com/fsaintjacques/semver-tool/blob/eb430f81c353feee4c4ab8206f0844d283e498dd/src/semver
in line 23 and following, the definition for PRERELEASE is given as follows:

PRERELEASE is an optional string composed of alphanumeric characters and hyphens

and the definition for BUILD is given as follows:

BUILD is also an optional string composed of alphanumeric characters and hyphens

The regex in line 5 of the same file seems to match these definitions.

However, the README.md in the repositorie's root folder explicitely declares compatibility with semver as defined by https://github.com/mojombo/semver which gives a slighty different definition for PRERELEASE and BUILD respectively. Quoted from there:

a series of dot separated identifiers
and further details the notion of "identifier" as follows:
Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-].
Identifiers MUST NOT be empty.
Numeric identifiers MUST NOT include leading zeroes.

The definition as given by semver is at odds with the definition given by this script. I would consider this a bug (and therefore this bug report) and propose the following options of resolving it:

a) documentation and code-comments should state clearly that the difference is intended. preferably a reason or reasons should also be given as to why the difference exists.
b) the README.md in the root of this repository should explicitely reference semver 1.x, as this version has a different definition of PRERELEASE that is more similar to this script's implementation.
c) change this script's implementation in order to match the semver 2.x definition.

With regards to (a), i could not be of any help as i do not have knowledge of the development process that lead up to the current state.
Option (b) seems to be the quickest solution with regards to implementation effort. However, semver 2.x was released quite some time ago and is the de-facto norm. It seems to me, that when people make unqualified reference to "semver", that version 2 is meant.

Regarding option (c), i intend to attach a patch to this issue shortly.

with best wishes,

Max

Hello,

Following is correct :

$ ./semver.sh compare 0.2.0-rc3 0.2.0-rc2
1

But the following compare should return -1:

$ ./semver.sh compare 0.2.0-rc3 0.2.0-rc21
1

Maybe with 2 digits prerel :

$ ./semver.sh compare 0.2.0-rc03 0.2.0-rc21
-1

But the recent bump prerel is moving from 2 digits to 1 :

$ ./semver.sh bump prerel 0.2.0-rc01+1.2.8
0.2.0-rc2

Thanks for the code

semver validate v2.10.1
valid

semver bump prerel 2.10.1
2.10.1-1

Should the following remove "v"?

semver bump prerel v2.10.1
2.10.1-1

Hi community,

I'm raising an issue to see if anyone else would be interested in having exit codes returned when using the 'validate' command.

Since this tool is built with CI in mind, it would be useful if a pipeline, pre-commit hook, etc. could be failed due to a non-zero exit code on version validation, rather than just echoing valid/invalid.

What does everyone else think? Is there some gotcha that I didn't consider? Maybe it could be controlled with a flag to start with, e.g. --exit-code, so as to not break pipelines currently using this tool.

Thanks for your consideration

It is common that the pre-release portion of a semantic version string contains a numerical value that represents successive versions. E.g. "3.1.0-rc.1" or "1.0.0-beta2". When such numbering is used during the release process, it is this numerical value that is most frequently "bumped". Given the frequency of the operation and that fact that this operation is often tied to an automated build/test/release process (pushing out new candidates), it is advantageous to have an automated "bump". The current version of semver does not do this: in fact, the "bump prerel" command simply replaces the pre-release portion and drops any build portion. Any change to the numbering must either be done by hand, or, through some exterior process that needs to be designed, built, integrated, and maintained in the automated pipeline.

It is proposed that the common case of incrementing a trailing numerical value in the pre-release field be supported. It should be amenable to automated pipelines. It should not break the previous usage of "bump prerel". It should not introduce new options or commands if not needed (which I believe is feasible).

I have prototyped such an extension and am willing to move it forward towards a pull request unless there are objections.

The basic approach is that a current disallowed usage of "bump prerel" with a trailing dot can be used to introduce numerical bumping. In the proposed change the trailing dot denotes a numeric value that is either created or updated. Here are a few examples:

1. semver bump prerel rc. 1.0.1 => 1.0.1-rc1
2. semver bump prerel rc. 1.0.1-rc1 => 1.0.1-rc2
3. semver bump prerel rc. 1.0.1-beta2 => 1.0.1-rc1
4. semver bump prerel rc.. 1.0.1 => 1.0.1-rc.1
5. semver bump prerel rc. 1.0.1-beta2+b1455 => 1.0.1-rc1
6. semver bump prerel . 1.0.1 => 1.0.1-1

As well, an "implicit" scheme is supported where the existing pre-release portion is used as the base:

7. semver bump prerel 1.0.1-rc1 => 1.0.1-rc2
8. semver bump prerel 1.0.1-beta => 1.0.1-beta1
9. semver bump prerel 1.0.1 => 1.0.1-1

The existing command is still supported:

10. semver bump prerel rc.3 1.0.1-rc1 => 1.0.1-rc.3
11. semver bump prerel rc 1.0.1-beta2+b1455 => 1.0.1-rc

N.B. examples 1 through 9 would cause an error in the current version either because of the trailing dot or the lack of a required argument. This lack of "backwards error compatibility" could be corrected by the use of an environment variable that forces complete backward compatibility with version 3.x.x of semver. I believe this is useful for non-regression testing, but not worth it for general use.

It seems to me that this proposed change does not imply a bump of the major version of semver.

Maybe I'm doing something wrong, but seems as though this should work:

git tag --sort=v:refname | tail -n 1 | semver get major

Instead it errors and gives the usage guide

Got any examples for the pre-commit hooks? And actual git usage?

It looks like in commit e0a836c, "is-nat" was renamed to "is:_nat" in src/semver. There is no mention of this (strange) naming in the commit log which was meant to resolve issue #42. Looks like a typo in a global substitution to me.

Fix: replace "is:_nat" with "is_nat" everywhere.

Add a "sort" command, sorting version numbers read from STDIN.

For a script I'm currently writing it would be nice to have an option to just validate a version string. Would it be possible to add something like semver validate 0.1.0-dev+001? And as a result it could return version 0.1.0-dev+001 does match the semver scheme. That would be really nice :)

The "tag" badge is:

1. Dynamic: always returns the most recent tag
2. Static: the "click through" URL always points to a specific tag, not the most recent
3. Error prone: one has to remember to edit the badge (the static part) when a commit is tagged. This has not always been done.

Some design thought about this tag needs to be done: what it is supposed to represent?

The dynamic part is "nice" in that one can always find the most recent tag (release? -- might be a better choice!) no matter which version of the README one is looking at. You can see if you are on the most recent. Note there is a text field in the badge "stable version" which maybe hints at the purpose of the badge. Unfortunately, this text is not displayed and only if one has the discipline to only tag stable versions does it make sense. The label for this dynamic part, however, suggests that one is looking at the named tag. But this is not the case.

The static part is "nice" in that clicking on it gets you to a specific tag: just not necessarily the one that it advertised. For example, at version 3.1.0, if one clicks on the badge, one navigates to version 3.0.0 (where the badge still advertises 3.1.0). If you then click on the badge in version 3.0.0, one navigates to 2.0.0

Part of the problem is the required manual editing step to update the badge URL during the release process. But even if one did this, it is still confusing.

Suggested work: define what is really wanted: current stable release? most recent tag? pointer to the stable release that this commit is based on? ?? Then figure out how to represent it.

FYI: Issue #48 also covers badges. Might be a good idea to do a badge cleanup PR that resolves both issues.

Docker versions can't use + in tag, hence build bump isn't available if you want to use semver in this case.
Can we have any customization to make different build syntax? like - instead + ?

Hi François,
as indicated in paragraph 11. of the semver specification v2.0.0:
When major, minor, and patch are equal, a pre-release version has lower precedence than a normal version, which means 1.0.0-alpha < 1.0.0
so running $ semver compare 1.0.0 1.0.0-alpha should result in 1 when it currently returns -1
best regards
Eric

Not sure if you've heard of the asdf version manager, but I've created a plugin for this semver tool. Essentially asdf uses github releases to install specific binaries for each host system. Once asdf is installed, semver can now be installed with this new plugin

# Install asdf plugin for semver
asdf plugin add semver

# Install specific version
asdf install semver latest

# Set a version globally (on your ~/.tool-versions file)
asdf global semver latest

# Now semver commands are available
semver --version
semver: 3.2.0

Just wanted to share this, but didn't know where... feel free to close this issue whenever
https://github.com/mathew-fleisch/asdf-semver

Dots are not considered as valid in the prelease part:

> semver validate 3.2.0-2023.03.03.1
invalid

without the dots:

> semver validate 3.2.0-2301011
valid

Semver allows it:

A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version

When the move from travis-ci to github actions was made, the "build" badge was not updated. One helpful reference for defining this badge can be found in https://stackoverflow.com/questions/57719605/official-badge-for-github-actions

This simple tool with no dependencies except for bash (not even more modern versions) is easy to install: download the single script file to anywhere, make it executable, and (if desired) be sure it is on your PATH.

However, the script has also been packaged up by (at present) two other tools: adsf and bpkg. These package managers can also install semver and might be useful in certain contexts, especially if the package managers are already being used. It is doubtful that setting up a package manager just to install semver makes any sense. Maybe other package managers/installers will appear: RPM, Debian, ?, .. (lol!).

The package manager details, especially how to set them up, do not belong in the semver README installation notes. This project does not (and should not) test the package manager setup and semver packaging/configuration. Packaging is a downstream activity.

Proposed:

1. The README file should contain pointers and a brief description of these package managers (a few lines). It should not contain set-up procedures.
2. These notes should not distract from the simple procedure or get in the way of the main contents of the README. There should be pointer (link) to an "alternate installations" section to be found towards the end of the README from the "installation".

See the discussion of this in PR #65

I think it is great that others have found the semver tool useful to the point of doing downstream packaging! There is no reason that the semver project shouldn't reference these efforts. And, we shouldn't be breaking things for these efforts (e.g. arbitrary name changes, versioning hygiene, etc).

I would use this, but since there are no install docs, I will go elsewhere..

It would be great, if your script could print all the specific parts of a given version, like:

semver get major 1.2.3
1
semver get minor 1.2.3
2
semver get patch 1.2.3
3
semver get prerel 1.2.3-rc.1
rc.1

Great work 👍

@fsaintjacques noted that "ideally the returned atom would match the tokens supported by bump, hence usable with xargs and similar tools.

This change would break backward compatibility, so a major version increment for semver-tool is implied.

The "release" subcommand is not implemented in the semver script and, in fact, causes a confusing error message if used. In addition, the "release" subcommand for "bump" is not completely documented in the public documentation (README.md): not in syntax, but example is given. "release" does work for "bump".

The external, public doc (README.md) does not correspond to the script's usage message. The usage message is correct.

Hi fsaintjacques.

At first, I want to thank You for such a great utility.

Despite the fact, that You primary targeted this tool for project usage, it also have possibility to compare 2 strings (which is my case):

semver compare <ver1> <ver2>

In case of compare two version strings, it ends in never ending loop when trying to find version file, since I'm running semver as utility (no .version file anywhere).
Maybe you should consider to load vesion file in case if only 1 parameter is passed (here) instead of doing that for each case (here).

Thanks in advance

I see this is licensed as GPLv3, is there a reason for being that restrictive?

I'm bundling the script into a project of mine which I was planning on releasing as MIT and I've read that they are not compatible. I'm not planning on making my project GPLv3, how should I proceed?

I'm not making any changes to the script, I'm just bundling it to avoid having to manually install it inside a docker container.

Thanks :)