How to deal with Science layer of versioning. #375

New Issue

GiteaMirror · 2026-02-17T11:57:42-06:00

GiteaMirror commented

2026-02-17 11:57:42 -06:00

Originally created by @gmajan on GitHub (Apr 3, 2019).

moja global develops tools to estimate greenhouse gas emissions and sinks from forests and agriculture. Every module has an approved science design before coding can even begin. When the science changes, the code will definitely change (but the API MIGHT stay the same.)

We want to use an adapted SemVer with 4 numbers: Science.Major.Minor.Patch-pre-release

Are there any existing approaches that we can adopt?

Thank you.

Originally created by @gmajan on GitHub (Apr 3, 2019). moja global develops tools to estimate greenhouse gas emissions and sinks from forests and agriculture. Every module has an approved science design before coding can even begin. When the science changes, the code will definitely change (but the API MIGHT stay the same.) We want to use an adapted SemVer with 4 numbers: Science.Major.Minor.Patch-pre-release Are there any existing approaches that we can adopt? Thank you.

GiteaMirror closed this issue

2026-02-17 11:57:42 -06:00

GiteaMirror commented

2026-02-17 11:57:44 -06:00

@runeimp commented on GitHub (Apr 4, 2019):

@gmajan Including a 4th version field is most likely unnecessary.

If you do a complete rewrite (even though the API hasn't changed) then bump the major version number. If you do an update that doesn't change the API but there are significant factors regarding the update (your science base changes significantly but doesn't require a complete rewrite) then do a minor bump. If the updates is based on a minimal science change and the API doesn't change then just do a standard patch bump.

With each release I'm guessing you'll be noting in the docs about changes in the science aspect that required the code update so you're pretty well covered in any case. These science change notes would be appropriate for your software changelog as well if you maintain one.

@runeimp commented on GitHub (Apr 4, 2019): @gmajan Including a 4th version field is most likely unnecessary. If you do a complete rewrite (even though the API hasn't changed) then bump the major version number. If you do an update that doesn't change the API but there are significant factors regarding the update (your science base changes significantly but doesn't require a complete rewrite) then do a minor bump. If the updates is based on a minimal science change and the API doesn't change then just do a standard patch bump. With each release I'm guessing you'll be noting in the docs about changes in the science aspect that required the code update so you're pretty well covered in any case. These science change notes would be appropriate for your software changelog as well if you maintain one.

GiteaMirror commented

2026-02-17 11:57:45 -06:00

@jwdonahue commented on GitHub (Aug 16, 2019):

@gmajan

Most good software has prerequisite requirements and design documentation and those docs often reference domain specific knowledge or data. You can include those in your versioned packages. I have never seen a valid reason to add another field to SemVer. I have however, seen many reasons to use some other versioning scheme. SemVer is not always the right choice. In your case, it probably is, you're just not thinking clearly about what it is you should be versioning.

I would simply incorporate digital versions of the papers or references thereon, in whatever kind of package you are versioning. You should probably stick with SemVer, unless you have a librarian or DevOps personnel on staff, who can justify otherwise.

@jwdonahue commented on GitHub (Aug 16, 2019): @gmajan Most good software has prerequisite requirements and design documentation and those docs often reference domain specific knowledge or data. You can include those in your versioned packages. I have never seen a valid reason to add another field to SemVer. I have however, seen many reasons to use some other versioning scheme. SemVer is not always the right choice. In your case, it probably is, you're just not thinking clearly about what it is you should be versioning. I would simply incorporate digital versions of the papers or references thereon, in whatever kind of package you are versioning. You should probably stick with SemVer, unless you have a librarian or DevOps personnel on staff, who can justify otherwise.

GiteaMirror commented

2026-02-17 11:57:45 -06:00

@jwdonahue commented on GitHub (Sep 11, 2019):

@gmajan, unless you have further questions or intend to issue a PR, please close this issue at your earliest possible convenience.

@jwdonahue commented on GitHub (Sep 11, 2019): @gmajan, unless you have further questions or intend to issue a PR, please close this issue at your earliest possible convenience.

GiteaMirror commented

2026-02-17 11:57:47 -06:00

@gmajan commented on GitHub (Sep 11, 2019):

Thank you very much. We are sticking to the suggestions from Runeimp. So no extra numbers.

@gmajan commented on GitHub (Sep 11, 2019): Thank you very much. We are sticking to the suggestions from Runeimp. So no extra numbers.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/semver#375