Rollback of full datetime created field

[nleiva]

NetBox version

v3.2.0

Feature type

Change to existing functionality

Proposed functionality

Hi, I understand that in the large scheme of things this breaking change introduced in 3.2 is largely unconcerning for untyped APIs. However, for the rest of APIs is sort of a hassle to go through these type of changes, as they slowly propagate over the dependency tree.

This change makes the NetBox Terraform provider incompatible with 3.2: e-breuninger/terraform-provider-netbox#145, because the go-netbox became incompatible as well netbox-community/go-netbox#127, due to the definitions in Go's OpenAPI package.

Use case

Nothing new, just looking to see if we could plan for a smoother transition.

Database changes

No response

External dependencies

No response

[kkthxbye-code]

What is the logic for Netbox rolling back and not the third-party packages being updated to support the new version? Wouldn't it also just create a weird state where 3.2.0 is not support but 3.2.1 is? Wouldn't the sensible thing be for you to stay on 3.1.x until the third-party packages you rely on are updated?

[nleiva]

Hi, thank you for the prompt response. In this case is a trade-off between the benefits this addition brings in the short term versus the negative impact that it might have. I wanted to give you visibility into the cascading effect that this has outside the Python community.

In terms of staying on an older version, that's certainly possible, at the cost of not enjoying all the goodness this new version seems to bring. Also, demo.netbox.dev for quick testing is running 3.2.0. In the end, it's all about the user experience.

I'm ok either way, just wanted to provide you some feedback.

[kkthxbye-code]

I certainly understand the frustration, but the change was included in the very first 3.2.0 beta on 15 Feb 2022. Ultimately it's the responsibility of third party package maintainers to make sure their libraries support newer netbox versions. I think ample notice was given in this case, for a very minor breaking change.

Another solution to the more general problem of breaking changes to the API was considered by Jeremy here: #7835

Not sure if the idea has been completely scrapped though, might be worth it to give your input there.

[nleiva]

Got it. I'll follow up with the different Go packages.

I'm not sure how often you make breaking API changes, nor how pressing this change was. But in general is a good practice to make them only on major releases.

Thanks

[kkthxbye-code]

But in general is a good practice to make them only on major releases.

You can see the netbox versioning scheme here: https://netbox.readthedocs.io/en/stable/release-notes/

• Major - Introduces or removes an entire API or other core functionality
• Minor - Implements major new features but may include breaking changes for API consumers or other integrations
• Patch - A maintenance release which fixes bugs and may introduce backward-compatible enhancements

[jeremystretch]

I'll just reiterate everything @kkthxbye-code said above. I'm going to close this out as there's no action to be taken.

[nleiva]

Right, I get what documents say. That's why I wanted to give you visibility on what happens when you introduce an API breaking change, which you described as "largely unconcerning".

If this change was really pushing, something on high demand, I'd understand why you made it on a minor release with the blessing of documentation. Otherwise, I would have waited for a major release to provide the best possible user experience.

[DanSheps]

I still fail to see how this would have helped you in this instance. Even if we did this in a major release (Netbox 4.0.0), you still would have upgraded and still would have encountered this error.

Our versioning scheme is unlikely to change in the future so I would take that into consideration when upgrading.

As an aside, because of the number of "breaking changes" we do in the code, we would likely be at NetBox 27.x.x or something right now.

[nleiva]

Thanks @DanSheps. In that scenario you would have followed Semantic Versioning 2.0.0 guidelines. So a self-generated OpenAPI library for 3.0 would still work for 3.2, and you have a range in 3.x to work across all libraries you depend on.

When you introduce an API breaking change on a minor version, you break this ''coordination". I want to emphasize API breaking changes, because this is targeted to developers that want to build solutions on top of NetBox and need a stable API.

If an enterprise customer of NetBox upgrades to 3.2 and that breaks something else. This is not good for anyone.

So, my point is. Is including the time in the create response critical enough to create this inconvenience? Could you put off these type of changes for major releases otherwise?

[DanSheps]

Thanks @DanSheps. In that scenario you would have followed Semantic Versioning 2.0.0 guidelines. So a self-generated OpenAPI library for 3.0 would still work for 3.2, and you have a range in 3.x to work across all libraries you depend on.

Well, we don't follow Semantic versioning

When you introduce an API breaking change on a minor version, you break this ''coordination". I want to emphasize API breaking changes, because this is targeted to developers that want to build solutions on top of NetBox and need a stable API.

Our policy is to allow breaking changes on minor versions, this isn't going to change, and API developers for NetBox should be well informed and aware of it.

If an enterprise customer of NetBox upgrades to 3.2 and that breaks something else. This is not good for anyone.

This is why it is important to read the release notes. This is specifically called out in the release notes and mentioned as such.

So, my point is. Is including the time in the create response critical enough to create this inconvenience? Could you put off these type of changes for major releases otherwise?

Again, you seem to be sticking to this Semantic Versioning requirement of "breaking changes only in major releases", which we do not follow. Our documentation even states we will do some breaking changes in minor versions and we will deploy major UI or feature changes/removals in major versions. Again, this isn't going to change and I think it is pointless to continue to debate this. I suggest you redirect your effort to providing a fix in the netbox-go repository for this API change, as it seems very trivial to do.