default.cfg isn't documented

Now that #98 has been merged it has replaced the temporary dirs.py I added exactly like I had envisioned that happening. So now it’s time to open this issue on one last improvement on that front I’d like to see.

See, both dirs.py and default.cfg had/have this one issue, that’s most relevant to devs, but not irrelevant to standard users either. When default.cfg is edited, Git will recognize this as a change that might be uploaded to the repo, which of course isn’t ever the case. While this can easily be ignored locally, switching branches will overwrite the default.cfg. Further if we ever change the default.cfg, which we should do as rarely as possible but let’s be real, it will probably happen a few times, this also would overwrite any custom changes by the user, and this last point is also what’s affecting all users, not just devs.

The question is, what do we actually do about that? I’ve thought about it for a while but I’m not entirely sure what’s the best approach. The best idea I had involves versioning and is this:

1. Rename default.cfg to [version].cfg and add internal cfg versioning
2. Add default.cfg to .gitignore (which btw still contains a reference to media_dir.txt we can delete with the same PR)
3. References still look for a default.cfg, and if it’s not found will offer to rename [version].cfg into default.cfg, making sure that hassle for end users is kept to an absolute minimum
4. At this stage the user only needs to get a default.cfg once which can be automatically done on the CLI, after which that default.cfg interferes neither with dev work like branch switching, nor will it ever be overwritten by updates. Necessary updates instead include a [newer version].cfg and will throw a warning/error at users, informing them of the need to migrate their changes to the newer version.

Thoughts are any issues with this plan?

[leotrs]

My next step in terms of the config system is definitely a more extensive documentation. I like your idea of also leaving a comment inside default.cfg. Some thing like DO NOT EDIT THIS FILE. USE <such and such> FILE INSTEAD.

This already works just fine on windows though

That’s what I thought, I just hadn’t tested it yet.

[leotrs]

I’m closing this as there now exists a file documenting the config system in docs/build/tutorials/configuration.html. This file is far from complete, but at least it explains the cascading system, which is the subject of this issue.