Document changes to MacOS's configuration paths, compared to last appdirs release

[pradyunsg]

There's an unannounced behaviour change here (using Library/Preferences instead of Library/Application Support like it used to), and... well, it'd be a good idea to flag this all over the documentation. :)

[pradyunsg]

Based on f9c2074, the MacOS paths for this library are incompatible with appdirs.

It is worth flagging this to users who are porting over.

[gaborbernat]

That was a bugfix for appdirs. 👍 Incompatible, but appdirs got it wrong here per the macos spec 🤔

[pradyunsg]

Agreed.

However, it's still weird that there was a change in behaviour in a backwards incompatible manner in a minor version release -- which was not noted in the changelog and didn't have any documentation updates either.

Applications loading from ~/Library/Application Support would now try loading from ~/Library/Preferences instead, which means existing user configuration files are ignored -- which is... bad?

[gaborbernat]

, which means existing user configuration files are ignored -- which is... bad?

The price we need to pay for progress 😊 PR welcome to document it.

[Jackenmen]

However, it's still weird that there was a change in behaviour in a backwards incompatible manner in a minor version release -- which was not noted in the changelog and didn't have any documentation updates either.

This change was done in 2.0.0 (which actually got it from appdirs's unreleased changes), not 2.1.0.
See #11

The price we need to pay for progress 😊

As said above, this has not actually happened in a non-major version but this statement makes me a bit worried about the specifics of the version policy platformdirs has. If it isn't SemVer (or maybe even if it is since "Semantic Versioning Will Not Save You"), perhaps it should be documented what the version policy is and what is covered by it?

[pradyunsg]

What makes you say that this was changed in 2.0.0? See the first post, which explicitly notes that the change happened in a minor version.

[Jackenmen]

I'm looking at it but the line you link to in 2.0.2 is the implementation for Windows, not macOS.
Here's the correct place and it uses ~/Library/Preferences same as 2.1.0:
https://github.com/platformdirs/platformdirs/blob/2.0.2/platformdirs.py#L243

[gaborbernat]

version policy platformdirs has.

We do semver, but the change here was considered a bug fix not a feature change.

[machow]

I'm not sure I understand how this doesn't warrant a major version bump. Is the expectation that platformdirs could change the base directory at any time (e.g. a minor or patch bump)? If so, it seems worth documenting, so people know to be defensive about this.

It would break several app behaviors I know of (e.g. https://github.com/rstudio/pins uses the R version of appdirs, and a change like this there would break behavior for users).

To my understanding--semver is not about features and bugs, so the question is whether this was an "incompatible API change". It's incompatible for cases like the one I listed above (but I sympathize with wanting to fix a broken behavior!).

[gaborbernat]

You can't judge this in an abstract. Think about the context. The contract is that will give the correct folder for the platform. If historically, we gave the wrong folder, and now we change it to give the correct one that's a bug fix. A feature change would be if we'd give historically the correct folder, but now we decided to give another folder that's also correct. The initial folder here was clearly incorrect and wrong. It worked but gave the wrong answer.

[machow]

(I'm not sure how my case was abstract, since it is a concrete implementation.)

That clears things up--thanks. It sounds like you see it like a calculator giving the wrong calculation, and could see why it is more of a bug fix in that case.

[pradyunsg]

PR welcome to document it.

To avoid going into extensive discussion on this, I'll flag that this has been stated by a maintainer here. :)

[Jackenmen]

That comment was about adding missing changelog entry which actually is not missing.
Sooo, are PRs documenting the version guarantees also welcome?
Especially the part that the specific location that platformdirs's functions give might change in non-major versions as this is totally something that can break a lot of people's code and they might otherwise not be aware that this project does not consider such change as not breaking. I don't agree with that policy but as long as it is clearly documented, I won't complain :)

[pradyunsg]

I've gone ahead and editted OP + the title to not have information that this discussion has shown to be incorrect.

[Jackenmen]

The changelog entry is already there:

What would yoy want to be added into documentation in addition to what's already there?

[tfeldmann]

What do you recommend as a migration strategy? Just hardcoding the wrong, old path on macOS and checking for config files there? What about something like a compat-flag to switch between wrong and correct path?

[layday]

IMO, this change should be reverted. App configuration on macOS does not belong in Library/Preferences, which is reserved for plist files generated by calling the "NSUserDefaults class or an equivalent system-provided interface". Apps should never write in Preferences directly. The nearest Mac equivalent to XDG .config was and remains Application Support.

[layday]

The original change was made back in 2017 in ActiveState/appdirs#100 but it was never merged into the release branch of AppDirs. Arguably, platformdirs should've been started from release, not master.

[tanlin2013]

What do you recommend as a migration strategy? Just hardcoding the wrong, old path on macOS and checking for config files there? What about something like a compat-flag to switch between wrong and correct path?

Need this too!!! Harcoding with copy & paste the config.toml file is the only way to go?

[gaborbernat]

Seems this is fine now.