RFC 7 Monty Versioning #186

tristanls · 2025-02-21T23:49:13Z

For easier reading, see final RFC https://github.com/thousandbrainsproject/tbp.monty/blob/main/rfcs/0007_monty_versioning.md

codeallthethingz

LGTM, optional suggestions.

codeallthethingz · 2025-02-22T00:29:28Z

rfcs/0000_monty_versioning.md

+
+* We want the current version to be in the source code.
+* The `main` branch is protected and changes can be pushed only via Pull Requests.
+


I would add a constraint that it needs to be programmatically accessible for things like the print_version tool. https://github.com/thousandbrainsproject/tbp.monty/tree/main/tools/print_version

Added a constraint "We want the current version to be programmatically accessible, e.g., by the tools.print_version.cli tool." in fb95a0c

codeallthethingz · 2025-02-22T00:31:11Z

rfcs/0000_monty_versioning.md

+
+# Future possibilities
+
+If we were to adopt the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/#specification) then the version number updates could be automated based on the commit message.


We could also put this in the tbp.cli tool which would take care of most of the manual steps.

tbp bump-minor

I added a future possibility that "The tbp CLI could be extended to include a version command that prepares a Pull Request to update the version number." fb95a0c

vkakerbeck

Nice, thanks for outlining this! I like the server proposal. Just one question on the process for updating the version.

vkakerbeck · 2025-02-24T09:57:03Z

rfcs/0000_monty_versioning.md

+
+### Process
+
+1. Create a Pull Request that ***only*** updates the `__version__` variable in [`src/tbp/monty/__init__.py`](https://github.com/thousandbrainsproject/tbp.monty/blob/main/src/tbp/monty/__init__.py).


Can you elaborate why we would want a PR with only that change instead if including the version number update in the PR with the change that triggers the version update? If we have a PR with a breaking change + a PR with the version number update, which PR would be merged first? I would assume we don't want to add the breaking change into main under the old version. So then we would increment the version before introducing the change? Why couldn't we increment the version in the same PR as the change and have the discussion on whether the change warrants a version update there?

I think of it as the process of assigning Monty a version being separate and happening at a different cadence from the process of making changes to Monty.

Some considerations:

We will want to bundle multiple breaking changes into the same version.

We will want to bundle a breaking change and some patches together.

We will want to use version update as a trigger to create a new release / publish Monty.

Also, I added a note explaining what "current version" means, which may have contributed to my lack of clarity.

Note
"Current version" can have a counterintuitive meaning due to different interpretations of what "current" means. For the purposes of this RFC, "current" is (somewhat circularly) defined as the version number in the source code.

The future workflow will essentially be as follows:

commit

commit

commit

commit

review all commits above and update the version accordingly, which publishes Monty

commit

commit

review all commits above and update the version accordingly, which publishes Monty

To facilitate this workflow, we'd want to have version-only PRs, which would also trigger our release / publish workflows.

I also added this future possibility in 7ff85b6

In the future, integrating into the main branch may become cumbersome if the pace of commits to main is high. In that case, we will update our versioning strategy. One way to do this is to create a release branch that is used for releasing new versions. This note is intended to highlight the possibility, but if we get there, we will get into the details then.

nielsleadholm

Looks great, thanks for putting this together!

Just two high level comments/questions

Is it possible to elaborate a bit how historical versions will be accessed (e.g. if someone wants to run something from the DMC paper, and so access v0.0.1)? Would this require some use of PyPi or the like?
I don't have a good suggestion, and maybe there's no solution, but do you have any thoughts on how we can help us to remember to update the version number when merging PRs into tbp.monty? E.g. an automated (but non-blocking) email / message whenever a PR is opened for tbp.monty? We might eventually get in the habit, but it feels like we may merge several PRs before suddenly remembering that we need to increment the version number.

hlee9212

LGTM. I was literally going to ask if we are going to auto-update via Conventional Commits and/or Github Actions, but you have read my mind and answered them. :)

hlee9212 · 2025-02-24T16:54:31Z

To @nielsleadholm:

Is it possible to elaborate a bit how historical versions will be accessed (e.g. if someone wants to run something from the DMC paper, and so access v0.0.1)? Would this require some use of PyPi or the like?

Just my thoughts on the above question...(hopefully I am understanding the question correctly). For accessing historical versions, e.g. let's say someone wants to access tbp.monty v.0.0.1 for DMC paper - then in requirements.txt or pyproject.toml we will need to specify tbp.monty==0.0.1, or some instruction to use pip install tbp.monty==0.0.1.

If we want to check out a historical version from GitHub, we can tag the releases and do something like git clone --branch v.0.0.1 repo_url.

I don't have a good suggestion, and maybe there's no solution, but do you have any thoughts on how we can help us to remember to update the version number when merging PRs into tbp.monty? E.g. an automated (but non-blocking) email / message whenever a PR is opened for tbp.monty? We might eventually get in the habit, but it feels like we may merge several PRs before suddenly remembering that we need to increment the version number.

I think your question may be answering @vkakerbeck's question on why the PR update for versions should be separate! 😄 If there is a PR that just updates the version, then your own PR will have to be rebased on top of that, so one does not need to manually update / remember to update the version number, as long as the PR is "up-to-date" with main branch (as all PRs are currently doing).

tristanls · 2025-02-24T18:34:22Z

@nielsleadholm

Is it possible to elaborate a bit how historical versions will be accessed (e.g. if someone wants to run something from the DMC paper, and so access v0.0.1)? Would this require some use of PyPi or the like?

I'm adding the following to the RFC in bc351c6, which is intended to answer the above.

Accessing specific versions

The most detailed and specific way to access a specific version of tbp.monty is to clone the repository and checkout the specific commit.

If we tag the version commit with the corresponding version number, then the version can be accessed by checking out the tag. GitHub has releases and tags pages that list the tagged versions.

If we publish Monty, then the specific published version could be installed via a package manager by specifying the published version.

tristanls · 2025-02-24T18:37:14Z

@nielsleadholm

I don't have a good suggestion, and maybe there's no solution, but do you have any thoughts on how we can help us to remember to update the version number when merging PRs into tbp.monty? E.g. an automated (but non-blocking) email / message whenever a PR is opened for tbp.monty? We might eventually get in the habit, but it feels like we may merge several PRs before suddenly remembering that we need to increment the version number.

I don't think we should update the version with every commit. It will be OK and even desirable to merge several PRs before updating the version number. I commented above regarding what I expect the workflow to be.

tristanls · 2025-02-24T23:17:37Z

FYI, I added some more context around MAJOR version number 0:

It is worth noting that the MAJOR version number 0 is special. When MAJOR is 0, then incrementing the MINOR version number can include backwards-incompatible changes. MAJOR version number 0 is the usual way of indicating that the software is still in development and not ready for production use.

We will use MAJOR version number 0 for the ongoing development of Monty. Incrementing the MAJOR version number beyond 0 should be a future RFC, as it will be a significant event.

tristanls · 2025-02-24T23:57:42Z

@codeallthethingz, I want to explicitly ask if what I proposed here will work with how we currently use readme.io. I imagine that if we go from 0.0.1 to 0.0.2, we wouldn't want to create a v0.0.2 documentation version but instead update the v0.0 documentation version.

codeallthethingz · 2025-02-25T00:03:59Z

@codeallthethingz, I want to explicitly ask if what I proposed here will work with how we currently use readme.io. I imagine that if we go from 0.0.1 to 0.0.2, we wouldn't want to create a v0.0.2 documentation version but instead update the v0.0 documentation version.

That is the current behaviour. We truncate to the minor version for the docs.

vkakerbeck

Sounds good :) Thanks for the clarifications & updates!

nielsleadholm

Thanks for the clarifications, looks great!

ramyamounir

Thanks @tristanls, looks great!

tristanls · 2025-02-25T16:12:06Z

FYI, added expected workflow section from the comment to the RFC

Expected Workflow

By adopting this versioning scheme and process, the expected workflow is as follows:

commit
commit
commit
commit
review all commits above and update the version accordingly (in the future this will also publish Monty)
commit
commit
review all commits above and update the version accordingly (in the future this will also publish Monty)
commit
...

tristanls · 2025-02-25T16:14:44Z

Motion for Final Comment Period

I motion for the Final Comment Period with the disposition to merge this RFC.

I interpret @codeallthethingz, @hlee9212, @vkakerbeck, @nielsleadholm, and @ramyamounir current PR acceptance as approval.
@scottcanoe please indicate your decision on the disposition to merge:

approve: via approving this PR or commenting that you approve to merge
abstain: by commenting that you abstain
other: by commenting

scottcanoe

LGTM. I've not worked with GitHub releases and tags, but it sounds clean. Can you clarify what is meant by "if we publish Monty..."? I'm assuming that means putting on PyPi or conda-forge.

tristanls · 2025-02-25T23:04:46Z

@scottcanoe, correct. Currently, I'm thinking conda. I will update the RFC to be more specific.

elaborated on release branches option

tristanls · 2025-02-25T23:08:02Z

This concludes the Final Comment Period, with all maintainers approving to merge. The PR will be merged shortly after the final pre-merge changes.

tristanls requested review from codeallthethingz, scottcanoe, vkakerbeck, nielsleadholm, ramyamounir and hlee9212 February 21, 2025 23:53

tristanls self-assigned this Feb 21, 2025

tristanls added rfc:proposal This issue tracks an RFC proposal triaged This issue or pull request was triaged labels Feb 21, 2025

codeallthethingz approved these changes Feb 22, 2025

View reviewed changes

vkakerbeck reviewed Feb 24, 2025

View reviewed changes

nielsleadholm reviewed Feb 24, 2025

View reviewed changes

hlee9212 approved these changes Feb 24, 2025

View reviewed changes

vkakerbeck approved these changes Feb 25, 2025

View reviewed changes

nielsleadholm approved these changes Feb 25, 2025

View reviewed changes

ramyamounir approved these changes Feb 25, 2025

View reviewed changes

nielsleadholm approved these changes Feb 25, 2025

View reviewed changes

This was referenced Feb 25, 2025

build: use version from source; remove obsolete option #189

Merged

build: reset version to 0.0.0 to satisfy conda constraint #190

Merged

scottcanoe approved these changes Feb 25, 2025

View reviewed changes

RFC Monty Versioning

74d7563

tristanls added 8 commits February 25, 2025 17:07

rfc: additional constraint and future possibility

04089e1

rfc: Add note about major version 0 being special

a04067a

rfc: add section about accessing specific versions

3828f11

rfc: release branch future possibility

f91cfe5

rfc: rename constraints to proposed constraints

ce985f5

elaborated on release branches option

rfc: note on not incrementing major version number

dd866fd

rfc: add expected workflow; clarify release branch future a bit

0374b0e

rfc: give examples of where we would publish Monty

4ee4518

tristanls force-pushed the rfc_monty_versioning branch from bb3870e to 4ee4518 Compare February 25, 2025 23:07

tristanls changed the title ~~RFC Monty Versioning~~ RFC 7 Monty Versioning Feb 25, 2025

rfc: pre-merge updates

9bcb878

tristanls enabled auto-merge (squash) February 25, 2025 23:10

tristanls merged commit 691ccf0 into thousandbrainsproject:main Feb 25, 2025
13 checks passed

tristanls deleted the rfc_monty_versioning branch February 25, 2025 23:12

nielsleadholm pushed a commit to nielsleadholm/tbp.monty that referenced this pull request Mar 3, 2025

rfc: RFC 7 Monty Versioning (thousandbrainsproject#186)

dbf8c82


		* We want the current version to be in the source code.
		* The `main` branch is protected and changes can be pushed only via Pull Requests.


		# Future possibilities

		If we were to adopt the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/#specification) then the version number updates could be automated based on the commit message.


		### Process

		1. Create a Pull Request that *only* updates the `__version__` variable in [`src/tbp/monty/__init__.py`](https://github.com/thousandbrainsproject/tbp.monty/blob/main/src/tbp/monty/__init__.py).

RFC 7 Monty Versioning #186

RFC 7 Monty Versioning #186

Uh oh!

Conversation

tristanls commented Feb 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codeallthethingz left a comment

Choose a reason for hiding this comment

Uh oh!

codeallthethingz Feb 22, 2025

Choose a reason for hiding this comment

Uh oh!

tristanls Feb 24, 2025

Choose a reason for hiding this comment

Uh oh!

codeallthethingz Feb 22, 2025

Choose a reason for hiding this comment

Uh oh!

tristanls Feb 24, 2025

Choose a reason for hiding this comment

Uh oh!

vkakerbeck left a comment

Choose a reason for hiding this comment

Uh oh!

vkakerbeck Feb 24, 2025

Choose a reason for hiding this comment

Uh oh!

tristanls Feb 24, 2025

Choose a reason for hiding this comment

Uh oh!

tristanls Feb 24, 2025

Choose a reason for hiding this comment

Uh oh!

nielsleadholm left a comment

Choose a reason for hiding this comment

Uh oh!

hlee9212 left a comment

Choose a reason for hiding this comment

Uh oh!

hlee9212 commented Feb 24, 2025

Uh oh!

tristanls commented Feb 24, 2025

Accessing specific versions

Uh oh!

tristanls commented Feb 24, 2025

Uh oh!

tristanls commented Feb 24, 2025

Uh oh!

tristanls commented Feb 24, 2025

Uh oh!

codeallthethingz commented Feb 25, 2025

Uh oh!

vkakerbeck left a comment

Choose a reason for hiding this comment

Uh oh!

nielsleadholm left a comment

Choose a reason for hiding this comment

Uh oh!

ramyamounir left a comment

Choose a reason for hiding this comment

Uh oh!

tristanls commented Feb 25, 2025

Expected Workflow

Uh oh!

tristanls commented Feb 25, 2025

Motion for Final Comment Period

Uh oh!

scottcanoe left a comment

Choose a reason for hiding this comment

Uh oh!

tristanls commented Feb 25, 2025

Uh oh!

tristanls commented Feb 25, 2025

Uh oh!

Uh oh!

Uh oh!

tristanls commented Feb 21, 2025 •

edited

Loading