Discuss: How to avoid rewriting the full config file

[florisla]

I'm not a fan of rewriting config files.

Feedback we had in various issues shows it's

• ugly (it moves sections around, can affect newlines and whitespace)
• inconvenient (it introduces source control changes in places where it should not)
• dangerous (it drops comments!)
• probably unnecessary

See for example #62, #83, #87, #90, #94, #161, #163, #169, #201, #207, #217, #228.
How are we going to solve this?
Various things we can do:

1. Update the version in the config file, but don't rewrite the whole file.
2. Rely on setup.cfg version.
3. Rely on the version found in the first bumpversion:file: section.
4. Don't update the config file unless the user configures bump2version to do it.

[florisla]

Proposal:

• If version is present, use it and replace it like you would a regular file. Don't rewrite the full config file.
• If metadata.version is present in setup.cfg, use it and replace it similarly.
• If none of both is present, simply assume that the first file section defined contains the full version number.`

Whether to modify metadata.version should be configurable. The default may be either of

• Modify if it's present.
• Modify if it's present and bump2version is configured in the same setup.cfg file.
• Only modify it if requested.

The latter is most compatible with current behavior, but the middle option seems more intuitive.

This takes care of whitespace issues, newline issues, dropped comments, double version definitions in setup.cfg, and redundant version definition in any config file.

[clbarnes]

Rather than relying on the first file defined, one file's config could have another variable defined, canonical. Having anything other than 1 canonical version file defined would raise an error. In general, I'd be in favour of a major version increment which reduces configuration and complexity, rather than adding better ways to do things but keeping the old ones around, which increases complexity and reduces guarantees.

[maven-slava]

Why not keep a single explicit file just for the version?

So at the bare minimum, one can expect that at least this file will always appear in VCS logs on version bump commits.
It should dramatically simplify all the hustle with rewriting (or not) config files and other target files with versions that not always might be rewritten (like files with a shorter or major version only.)

It will:

1. Get rid of the headache with a need to update the version in the config file, but don't rewrite the whole file.
2. Won’t need a dependency on “setup.cfg”.
3. Won’t obscure that it implicitly relies on the version found in the first bumpversion:file: section (hence reducing the possibility of surprises when such file will change its position or will be removed.)
4. Won't require updating the config file at all.
5. Will embrace Unix’s philosophy that everything is a file and file is everything.

P.S.
In general, I am against the introduction of new files (especially for one tiny purpose). Still, in my humble experience, I have seen in the past that for the sake of a single place of version, it is hard to find a better place than a single separate file (and then synchronizing it with other targets (sometimes even into RDMS.))

[xbreak]

@florisla, what do you think about allowing user to specify a version file like suggested by @clbarnes and @maven-slava?
If adopted it seems to me it would be straight forward to remain backwards compatible* or decide to deprecate previous method.

*By allowing user to decide between mutually exclusive config properties current_version or promote a separate file as the authoritative source of current version, specified by "tbd" property (e.g. canonical or maybe current_version_file).

[tandav]

I solved this issue by switching to bumpver. Nice package which is not listed in RELATED.md alternatives.
It supports setup.cfg and does not rewrites it, no whitespace issues.