fsaintjacques / semver-tool Goto Github PK
View Code? Open in Web Editor NEWsemver bash implementation
License: Apache License 2.0
semver bash implementation
License: Apache License 2.0
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
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).
Got any examples for the pre-commit hooks? And actual git usage?
The "tag" badge is:
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.
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
Add a "sort" command, sorting version numbers read from STDIN.
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:
As well, an "implicit" scheme is supported where the existing pre-release portion is used as the base:
The existing command is still supported:
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.
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
I would use this, but since there are no install docs, I will go elsewhere..
This seems a regression of #6. Running semver compare 1.8.1 1.8.1-rc2
should return 1
but returns -1
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
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
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
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 +
?
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.
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.
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 :)
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
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 :)
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):
semver
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:
Makefile
running tests under Docker and using *nix install; a GitHub action script (ci.yaml) with it's own test execution scripting and asdf installationSuggested steps to clean this up (in priority order):
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.@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.
Great work 👍
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
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:
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).
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
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
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 {
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 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.
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
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
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:
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:
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?
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.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.