Document policy on backwards-incompatible changes?

[sirosen]

I'm trying to specify which versions of psutil are supported by an application I work on. If a backwards-incompatible change to the python API provided were necessary, would I expect that to be a new major release? (Not necessarily semver.)
This should be documented, e.g. at the top of the changelog file.

It looks like psutil maintains fairly strong backwards-compatibility, and an API-breaking-change is very unlikely. Plus, it would be quite disruptive to make a change given how many projects have open bounds like psutil>=2.1, etc.

But it would still be good to have a clear policy on this!

---

The contrib guide suggests asking questions in the Google group, but I don't think that's appropriate in this case.
If I'm wrong, please feel free to close, and I can ask a question / suggest documentation there.

[giampaolo]

Hello there. Interesting topic.

Yes, backward compatibility is rarely broken (...and python 2.6 is still supported!). The latest biggest API breakage which comes to my mind was in psutil 2.0.0, in 2014 (7 years ago):

• https://github.com/giampaolo/psutil/blob/4d03c917561297de1e6017059c60eb879cf8353c/HISTORY.rst#200
• https://gmpy.dev/blog/2014/psutil-20-api-redesign
• https://gmpy.dev/blog/2014/psutil-20

That was a massive breakage, sort of comparable to the python 2 -> 3 transition. Back then that was possible because psutil was much less used. Today I'd never do that. =)

The only other more recent incompatible change that I could find in the HISTORY was:

1291: [OSX] Process.memory_maps() was removed because inherently broken (segfault) for years.

...which was introduced in 5.6.0 in 2019:
https://github.com/giampaolo/psutil/blob/4d03c917561297de1e6017059c60eb879cf8353c/HISTORY.rst#560
...and that was done due to security concerns.

The only potentially incompatible change I can foresee for the immediate future is this one: #1392 (comment). But it's not really a breakage, as the function signature will support both "new" and "old" API usages. If I were to release that now, I'd probably go from 5.8.0 to 5.9.0.

More in general: I don't expect to break APIs any time soon. If I were to break something, I'd bump up the major version, e.g. from 5.8.0 (current) I'd go straight to 6.0.0. It must be noted though, that I may still go to 6.0.0 even if I do not break any API, e.g. if I introduce a very important brand new feature (unlikely) or if I accumulate enough 5.9.* versions (more likely).

Long story short: psutil backward compatibility is taken seriously and versioning is sort of linear, even though it doesn't follow strict rules (maybe it should?).

As for what to put in the doc: I'm not sure... I wouldn't know what to say exactly or how to phrase it. The only thing worth mentioning would probably be the fact that in case of API breakage, the major bit will increase (e.g. 5.8.0 -> 6.0.0). But in my mind that is kind of obvious already (or isn't it?).

I'm open to suggestions.

[sirosen]

Given how long of a history this library has, and how stable it's been, I wouldn't want to introduce something onerous for you.

But if everyone is writing >=X, then psutil can never safely change, even if there's an API change which is really wanted. That "feels wrong" to me. But also, I only maintain one tool which supports py2.7, and I can't really imagine continuing to support 2.6, so my perspective may be skewed.

What about some text which just documents what you do today? Something along the lines of the cryptography policy, but a little looser. Like...

psutil provides a strong backwards compatibility guarantee.

Most major and minor versions will not contain any breaking changes.
If a backwards-incompatible change is needed, it will be a new major version, and it may be preceded by a deprecation window if appropriate.

An exception is applied for security issues, which may be resolved in a point release even if they are backwards incompatible.

Does that seem good? I could put exactly that in a PR if it helps. 😄

(Aside: thanks for being so receptive to this discussion! And for all the years of psutil dev and support!)