[feature request] choose a config file format and use the file extension

[adriangalilea]

Instead of

Bugwarrior’s configuration file can be written either in ini or toml format.

That I think increases the chances of issues like these: https://github.com/GothenburgBitFactory/bugwarrior/issues/426

It's be probably better to have a single file extension.

Also, as of now if I define my bugwarriorrc with a file extension I get the following

❯ bugwarrior-pull
CRITICAL:bugwarrior.command:Could not load configuration. Maybe you have not created a configuration file.
FileNotFoundError: [Errno 2] No such file or directory: '/Users/adrian/.config/bugwarrior/bugwarriorrc'

This seems like a trivial feature request but, if you have a single format with extension you get:

• simpler documentation to mantain and read
• syntax highlight
• avoid issues like the one mentioned

Alternatively you could continue mantaining both, I don't see the point, but it'd be good to at least have file extensions regardless.

[ryneeverett]

That I think increases the chances of issues like these: #426

I don't see how a single file format makes #426 worse.

It's be probably better to have a single file extension.

For context, the toml configuration format has not yet been released. I would like at least one release to support both configurations for a couple reasons:

1. The toml format is fairly new, probably not that well tested, and I've gotten basically zero feedback on it so far. I consider it somewhat experimental and I don't think there's a good reason to force users to switch to it at this point.
2. The next release will be jarring enough for users. The configuration validation is pretty aggressive and I doubt there will be a single user who doesn't have to fix errors because my experience is that it's hard to write more than 10 lines of configuration without an error. (To be clear, the mistakes that cause validation errors also cause bugwarrior to defy user expectations.)
3. I think the taskwarrior community is probably annoyed enough about the taskwarrior-3 upgrade process and there's no need to make this one as painful. The transition is more graceful if there is at least one release that supports both formats.

I would also note that part of the motivation for adding the toml support was to ensure that the configuration language was sufficiently abstracted from the configuration schema. This is part of the larger architectural improvements proceeding towards #775. Keeping multiple configuration formats ensures this property remains but is probably not a good enough reason on its own.

All that said, I'd be open to potentially dropping the ini support some day. Unless there's a pressing need to remove it though, I'd see an incremental step to be to remove it from the documentation and print a deprecation warning when it is used.

Also, as of now if I define my bugwarriorrc with a file extension I get the following

I have a feeling this is another case of #1007 and perhaps #1001.

* syntax highlight

I don't see how a single format would improve syntax highlighting.

Alternatively you could continue mantaining both, I don't see the point, but it'd be good to at least have file extensions regardless.

The .bugwarriorrc ini file has never had a file extension. This was pretty common and wasn't recognized as a flaw back in the day. The TOML specification requires that files have an extension, whereas INI doesn't really have a specification. My view is: if you don't like under-specification and 90's goofiness, don't use INI.

[adriangalilea]

Let me give an overview of my opinion first:

• Projects are hard to maintain as it is, having to document 2 different config formats will make it more tedious to document and debug, and communicate.
• Some issues may be related to a specific format which makes it harder in the code aswell.
• Config issues and solutions you find on GitHub issues may not apply to you since it's a different format unbeknownst to you.
• I don't expect everyone to identify ini from toml just by looking at the syntax, much less if there's no file extension.

So in my opinion this adds unnecessary complexity, duplicities, makes it harder to maintain, document and troubleshoot, for no gain whatsoever.

The next release will be jarring enough for users.

I'd say then it's the perfect moment to do all big changes at once.

If there's going to be breaking changes I rather do it all and forget, rather than every so often having to adopt minor breaking changes.

(To be clear, the mistakes that cause validation errors also cause bugwarrior to defy user expectations.)

Which is why avoiding duplicities and sticking to one thing is best.

The transition is more graceful if there is at least one release that supports both formats.

Reasonable, but I rather do it all at once, a project like this, the simpler the better, to maintain and to use. I guess if you are not ready to upgrade to a version introducing breaking changes, you can just hold on on the previous one.

I'd see an incremental step to be to remove it from the documentation and print a deprecation warning when it is used.

Yeah, this sounds like the perfect middle ground.

I don't see how a single format would improve syntax highlighting.

I meant having a file extension, but now I see this is going to happen once toml get's adopted as it will have .toml extension.

The .bugwarriorrc ini file has never had a file extension. This was pretty common and wasn't recognized as a flaw back in the day. The TOML specification requires that files have an extension, whereas INI doesn't really have a specification. My view is: if you don't like under-specification and 90's goofiness, don't use INI.

Just to clarify my stance on this after reading and understanding the situation a bit more, yes, it's totally fine to have config without extension, but, having 2 different config languages without extension, makes it complex for people sharing their config with other people and so on.

I must say that after reading you I understand the thought process and decisions better, to a degree is a matter of taste and I respect your decisions, I don't intend to impose my thoughts just share them.

[ryneeverett]

I do appreciate you weighing in. I've been uncomfortable making these decisions for users with only my own perspective.

I guess if you are not ready to upgrade to a version introducing breaking changes, you can just hold on on the previous one.

This is a sound argument in general and one I would make for taskwarrior-3. But bugwarrior is a bit different since it interacts with third-party API's which are subject to change. They do seem to be becoming more stable but old bugwarrior releases are typically pretty broken by API incompatibility. To me this factor makes a forced migration more aggravating.

having 2 different config languages without extension

To be clear, there isn't really such flexibility about this. It's not documented yet (#1001) but, unless you use the BUGWARRIORRC environment variable to change the path, ini must be named bugwarriorrc and toml must be named bugwarrior.toml. See https://github.com/GothenburgBitFactory/bugwarrior/blob/20972fb9dd4bcadb954acd29f05ce839950b515b/bugwarrior/config/load.py#L33-L64

[ryneeverett]

I will consider making the incremental step before the next release and will probably solicit more opinions.

[adriangalilea]

This is a sound argument in general and one I would make for taskwarrior-3. But bugwarrior is a bit different since it interacts with third-party API's which are subject to change. They do seem to be becoming more stable but old bugwarrior releases are typically pretty broken by API incompatibility. To me this factor makes a forced migration more aggravating.

Makes a lot of sense, my point is simply that if I'm going to face breaking changes I prefer to do it in one sitting and learn what taskwarrior v3 + bugwarrior v2 implies, set it and forget it. But your decisions are more sound than initially thought since I was confused by the dev documentation and a bit lost.

To be clear, there isn't really such flexibility about this. It's not documented yet (https://github.com/GothenburgBitFactory/bugwarrior/issues/1001) but, unless you use the BUGWARRIORRC environment variable to change the path, ini must be named bugwarriorrc and toml must be named bugwarrior.toml. See

This settles it for me on the extensions, I thought there were 2 possible schemas, ini/toml, with the same exact file .bugwarriorrc, but if the toml will have it's extension, I have no problem since both variants are identified. You are aware of what's causing this confusion so it's alright.

Bottom line for me is that while the intention of aiding the upgrading experience of the user is great, in a project where man-hours are scarce, time should be focused on other things rather than retro-compatibility, it's a slippery slope and it grows bigger than you expect it to, it's great if it's a commercial product and you can support it, but I think since people are having issues finding the right docs and there's some communication issues, perhaps it's best to simplify in areas like this, and I think, the time spent creating duplicate documentation and explaining doubts of unclear documentation is a bigger cost than what it would be by just making a breaking change that's very well written and communicated.

I think we can safely close this, thank you.