muratgozel / node-calver

Calendar based software versioning library as node.js module and with cli support. 📅

Hi there,

My name is Murat. I'm an independent, senior-level software developer who makes custom software including but not limited to web-based frontend and backend products, bots, iOS apps and CLI apps. I have custom shell scripts to deploy my apps and using CI/CD platforms as well.

I open source things I believe missing and potentially help others in the language's ecosystem. My open-source work also signals my portfolio as I'm not able to share all of my work publicly.

Tech Stack

You will find the programming languages, frameworks and libraries I prefer to use below. The list is not complete but hope that it gives an idea about my technical routines.

Javascript

• Typescript
• eslint to keep the codebase aligned with standard javascript code style.
• Localization libraries based on formatjs.
• jest for testing.

Frontend

All of my frontend products compatible with modern browsers + IE 10 and IE 11. See the full list of compatible browsers.

• Svelte as a frontend framework.
• React as a frontend framework but less than Svelte.
• Tailwind for styling.
• CSS pre-processors such as SASS and Stylus.
• Vite to create SSR enabled production builds.
• prosemirror to create custom text editors.

Backend

• node.js
• Fastify as server framework.
• redis for in-memory storage.
• PostgreSQL and slonik as a database client.
• ajv to validate schemas.
• Logto for authentication.
• pino for logging.

Desktop

• Xcode for iOS apps and WebStorm for all the other apps
• Postico to design and manage PostgreSQL databases.
• Built-in Terminal in MacOS.
• Docker for containerized deployments.

Cloud Services

• Digitalocean servers.
• AWS SES, S3 and Cloudfront.
• Heroku.
• Sentry.
• Plausible.
• Google Analytics.

Other Programming Languages

• Python. I use Python as neccessary depending on the project.
• Solidity. As closely working with web3 communities, I have a few smart contracts built in Solidity.
• Swift. I build iOS apps by using Swift and SwiftUI.
• Shell. I use shell to make custom deployment scripts.

node-calver's Issues

Reset increments

Exists an issue where when you are using the major, minor and micro, and you increment minor o major (as example), the lower types must be reset to zero, but those types keep their values.

Example:

const calver=new Calver('YYYY.MINOR.MICRO','2020.0.0');
calver.inc('micro');
console.log(calver.get());
// 2020.0.1
calver.inc('minor');
console.log(calver.get());
// 2020.1.1
// In this case must be 2020.1.0
// And the year must be 2021

Modifier gets set to -1 when bumping calendar and minor for a previous month version.

Hi,
When I pass increment as calendar.minor.rc to a previous month version without the modifier, the modifier gets set to -1. I'm not sure if maybe I'm trying something unusual here. I would expect that the following command gives me 2023.3.0-rc.0.

> const calver = await require('calver')
undefined
> calver.inc("yyyy.mm.minor", "2023.2.2", "calendar.minor.rc")
'2023.3.0-rc.-1'

If I try setting increment as calendar.rc, it keeps the minor:

> calver.inc("yyyy.mm.minor", "2023.2.2", "calendar.rc")
'2023.3.2-rc.0'

Is there a way that I can bump from a version without modifier (with date from a previous month), and get minor=0 and rc=0?

Thanks!

Semantic calendar bumps aren't working

The last refactor has a major regressed where the feature discussed in #2 is no longer possible.

calver.inc('YY.MM.MINOR', '21.1.0', 'calendar.minor')
Uncaught:
Error: The second tag of the level should be a modifier tag. You specified "MINOR" as the second tag and "CALENDAR" as the first tag.

It seems like this feature was explicitly removed based on the v21.11.0 changelog

Second level might only be a modifier

Just as a reminder, I gave a rationale for why this feature is helpful here: #2 (comment).

Missing `post` identifier

I currently have a convoluted way of getting my calendar versioning handled in most of my projects.

First non-(dev,beta,rc) release of the day is tagged/versioned with the date: yyyy.mm.dd
If a second full release is made, for say a hotfix, a suffix is added -1 for example, and is incremented for each subsequent release. This post/hotfix identifier is completely absent if there is only one public release that day. The next day resets to yyyy.mm.dd

On pypi/poetry, when I build and publish with a version like 2024.2.1-1 creates a version on pypi 2024.2.1.post1 with no manual input required.

These are uploaded to pypi and not treated as pre-releases.

I do not have dev,rc,beta builds uploading yet, but I want to get pre-releases up so my users can test it before it goes out wide.

https://pypi.org/project/sickchill/#history

It would be awesome if just calling

with today = 2024.2.1
calver.inc(format, '', 'calendar.post') returned '2024.2.1',
calver.inc(format, '2023.2.1', 'calendar.post') (previous date) returned '2024.2.1',
calver.inc(format, '2024.2.1', 'calendar.post') returned '2024.2.1.post1',
calver.inc(format, '2024.2.1.post1', 'calendar.post') returned '2024.2.1.post2

and possibly add a nulpost (or something of that nature) modifier that would accept and create a post level without modifier words:

calver.inc(format, '', 'calendar.nulpost') returned '2024.2.1',
calver.inc(format, '2023.2.1', 'calendar.nulpost') (previous date) returned '2024.2.1',
calver.inc(format, '2024.2.1', 'calendar.nulpost') returned '2024.2.1-1',
calver.inc(format, '2024.2.1-1', 'calendar.nulpost') returned '2024.2.1-2

Also, note my nulpost has a - separator and pypi converts it to . = maybe a parameter for modifier-level separator?

I'm interested in writing a github action to make this simple for python users to use, and keep both a release branch and a dev/rc branch uploaded to pypi with pre-releases. So any help getting this library to work in the odd way I am trying to make it fit me lmk lol. Thanks.

inc behavior unclear

Hi!
It is not exactly clear to me how calver.inc(format ,version , 'calendar') is supposed to work.
For example the following test cases scenarios:

assert.strictEqual(calver.inc('yyyy.mm.patch', '2020.6.1', 'calendar'), '2021.1.0')
assert.strictEqual(calver.inc('yyyy.mm.patch', '2021.1.0', 'calendar'), '2021.1.0')

The first line I would expect that the calendar is updated to the current date, and the patch number is reset.
For the second line I would expect to get some kind of error, because the inc doesn't actually increment anything.

Is this supposed to happen?

Happy to help

This project could use some reinvigoration. Mind if I help out as a maintainer? I currently maintain https://github.com/casmith/release-it-calver-plugin, so I have a vested interest in this project's survival.

Do you have a plan to support timezone?

Currently, it's fixed as UTC. do you have a plan to support timezone?
I am willing to create a PR, but it's better to confirm before I do that.

proposal: build identifier after modifiers

Great package, thanks for sharing 🙏🏼

I want to propose adding a build-identifier option that, if used, would be appended to a modifier. The identifier on previous versions would be ignored when determining next version, and would not affect the current version rolling logic.

This would also comply with semver conventions.

From semver:

Build metadata MUST be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85, 1.0.0+21AF26D3—-117B344092BD.

Example scenario

• Calver format: yy.mm.dd.patch
• Version on production: 22.9.10.0
• git short sha: abcd123

A developer is working on the feature deployment branch fixing-stuff and determined version for the first feature deployment is 22.9.10.1-dev.0 accessible at https://fixing-stuff-abcd123.dev.company.com. There are several services that participate in the deployment, e.g. sentry, spinnaker, et.c.

A build identifier that would become part of of the deployment chain would simplify targeting regressions or broken deployments.

Example version using a build identifier: 22.9.10.1-dev.0+fixing-stuff-abcd123.

This would allow developers and QA to quickly target where problems were solved (or occurred) during the development phase since it has a human annotation to it 😄

I am up for creating a PR if this makes sense, otherwise I will concat the build identifer to the calver version.

Behaviour of the 'micro' inc function

When I make use of date-based elements in my version tag, I would expect Calver to automatically update these correctly.

Take this example:

const version = new Calver('YYYY.MM.MICRO', '2020.11.3');
version.inc(); // 2020.12.0

const version2 = new Calver('YYYY.MM.MICRO', '2020.12.0');
version2.inc(); // 2020.12.0

The first version number was last created in november (2020-11), since it is december now, it updates to 2020.12.0.
If I want to increase the version number again in december, executing the inc() function returns exactly the same version number. Instead, we'll have to use inc('micro') to get 2020.12.1.

Maybe I'm missing something, but it seems to me that calver-based version numbers always should be adding one to the micro-level in this case, since the year and month levels did not change from the current version number. Calver knows what day it is, so it can compare it with the current version name to determine what should be updated.

I would expect the following behaviour:

const version = new Calver('YYYY.MM.MICRO', '2020.11.3');

// It is november 15th
version.inc(); // 2020.11.4 

// It is november 30th
version.inc(); // 2020.11.5

// It is december 1st
version.inc(); // 2020.12.0

// a later day in december
version.inc(); // 2020.12.1

Level 2 semantic tags are incremented incorrectly for pre-releases

Hello!

I'm using another Node.js package which leverages this great package to do calendar versioning. I couldn't get it to act like I expected in some cases, and I think this is an oversight in how semantic tags are incremented when (pre-release) modifiers are included.

It centres around whether versions with modifier tags should be considered pre-releases or not, i.e. is 2023.6.0 > 2023.6.0-rc.*?
To be fair, I can see the argument for modifiers like dev or alpha being considered as 'post-release' (2023.6.0-dev.* > 2023.6.0), but rc ("release candidate") should definitely be considered as a pre-cursor release to the main unsuffixed version; this is how semantic versioning treats pre-release tags.

Edit: a suggested fix is in PR #22

Here's some examples to illustrate:

💡 N.b. date now in the following is June 2023

Incrementing a pre-release

Welcome to Node.js v18.14.2.
Type ".help" for more information.
> c = require('calver')
Calver {
  seperator: '.',
  levels: [
    'CALENDAR', 'MAJOR',
    'MINOR',    'PATCH',
    'DEV',      'ALPHA',
    'BETA',     'RC'
  ],
  _useLocalTime: false
}
> c.inc('YYYY.MM.MINOR', '2023.5.26', 'calendar.minor.rc')
'2023.6.0-rc.0' ✅ 
> c.inc('YYYY.MM.MINOR', '2023.6.0-rc.0', 'calendar.minor.rc')
'2023.6.1-rc.1' ❌ 

My expectation here is that the second example should result in 2023.6.**0**-rc.1, i.e. the semantic MINOR tag should not be incremented.

Going from release to pre-release

Using calendar.rc is a workaround to the former case, to avoid incrementing the minor as well as the rc tag, but when going from release (no modifier tag) to pre-release (adding -rc.0), minor is also needed, in order to increment the minor semantic tag in the case where the date has not changed, i.e. when adding a pre-release modifier tag, the semantic MINOR tag should be incremented (or reset, if the date has changed):

> c.inc('YYYY.MM.MINOR', '2023.5.17', 'calendar.rc')
'2023.6.0-rc.0' ✅ 
> c.inc('YYYY.MM.MINOR', '2023.6.0', 'calendar.rc')
'2023.6.0-rc.0 ❌
> c.inc('YYYY.MM.MINOR', '2023.5.17', 'calendar.minor.rc')
'2023.6.0-rc.0' ✅ 
> c.inc('YYYY.MM.MINOR', '2023.6.0', 'calendar.minor.rc')
'2023.6.1-rc.0 ✅ 

N.b. obviously the result for calendar.rc when the date has not changed is technically correct, since the minor increment was omitted, but my point is that more that it's the 'undesired' result.

Going from pre-release to release

> c.inc('YYYY.MM.MINOR', '2023.6.0-rc.0', 'calendar.minor')
'2023.6.1' ❌ 

Similarly, the expected result here is 2023.6.0, incrementing the pre-release 2023.6.0-rc.0 by calendar.minor (i.e. dropping the modifier tag) should also not increment the minor semantic tag, because the main release 2023.6.0 is newer than its -rc.* pre-releases.
Using just calendar as the increment level is not a practical workaround, since that doesn't work when the date has changed:

> c.inc('YYYY.MM.MINOR', '2023.5.17-rc.0', 'calendar')
'2023.5.17' ❌ 
> c.inc('YYYY.MM.MINOR', '2023.5.17-rc.0', 'calendar.minor')
'2023.6.0' ✅  

N.b. this is possibly another/different bug? I would have expected calendar to work here, since the date has changed. It seems to neither reset the minor tag nor update the calendar tag.

separators and modifiers

first thanks for writing this library

I would like to know if you have any plans to support modifiers dev, alpha
and support additional separators to the dot ., like - or _
or simply allow identifiers together, like YYYY0M

let me know if you need more information or prs about it