Versioning todo.txt spec

[karbassi]

With discussion and proposed changes to the todo.txt spec, the community will need a way to identify which version of the spec they are using.

There needs to be a way to identify to users and developers of tools the version of the spec they are using.

This issue is to discuss ways we could do that.

[zagortenay333]

Why not just tag a commit? Using x.y for the version number, where x = backwards-incompatible, y = backwards-compatible.

[bram85]

The alternatives are:

• Encode the version in the filename;
• Encode the version inside the file;
• Configure the todo.txt client. Existing clients implicitly use the current/original spec. If they implement such parameter it implies they're aware of other todo.txt formats.

[karbassi]

@zagortenay333 Not what the versioning will be like, but how to signify the version of that todo.txt file to the program/user.

We'll be using the semver pattern for the versions.

[karbassi]

Encode the version in the filename;

Something like todo-v2.0.0.txt or todo-2.txt?

Encode the version inside the file

If we have some sort of commenting pattern available in spec 2.0.0, we could do

# version: 2.0.0

Configure the todo.txt client. Existing clients implicitly use the current/original spec. If they implement such parameter it implies they're aware of other todo.txt formats.

Would the user be in charge of telling all their clients what version they are using then?

[pablito1755]

I'm inclined to think that the file is written/edited to a particular version of the spec and so it should state that version to client apps. Unless the specification also mandates a standard configuration file that all clients must use (which I don't think is a bad idea... it works well with a solution for #4), the text file should probably know the version. Otherwise users potentially need to configure multiple clients to recognize the correct format.

Putting the version in the filename seems like a bad idea. The clients need to know the full path of the file. When the version changes, not only do the files need to be renamed, but the client's config file also needs to be updated.

[pablito1755]

Thinking about this a bit more, the standard config file seems increasingly attractive to me. The database text files should all follow the same standard so the current spec version should really only live in one place. Otherwise, the client app could (theoretically) find itself having to handle files in different formats... which is clearly undesirable. In the absence of a version number config setting, the app client assumes version 1.

[cweagans]

IMO:

• Make a version comment on the first line of a todo.txt file optional
• If not present, the version will be assumed to be the latest released spec
• Programs that are responsible for reading and writing a todo.txt file should specify the version that they are writing (add the comment if it's not present).

This way, if there are breaking changes, most applications will already have the version comment in the file. The ones that don't only need to modify the way that they write files so that there is a version comment present.

[heX16]

"Make a version comment on the first line of a todo.txt file optional" +1
and make as tag: "todotxt_version:2.0"

[tomByrer]

Good idea to have the comment header to include the version. Bad to expect everyone (eg 3-year old clients) to assume that the absence of such comment means 'latest released spec'. Should be if no version mentioned = v1.0.

[andoresuperesu]

@tomByrer @heX16 @cweagans

Just to make it clear:

1. Make a version comment on the first line of a todo.txt file optional
2. If not present, the version will be assumed to be the v1.0.
3. Programs that are responsible for reading and writing a todo.txt file should specify the version that they are writing (add the comment if it's not present).

As mentioned by @karbassi, it should follow the format:

# version: 2.0.0

Which follows the lines of the shebang in unix.

what do you think @karbassi ?

[Nadrieril]

It seems to me that there is consensus on having an optional comment header specifying the version. Is there anything else to discuss or can we add it to the spec and close this issue ?

[zagortenay333]

A user should be able to tell the client what version the todo.txt file is in, so it shouldn't be assumed that it's version 1 if the comment is missing.

[cweagans]

@zagortenay333 The reason for assuming version 1 if the comment is missing is because earlier versions of the spec didn't have versioning at all. It's not a good standpoint to assume that all of the todo.txt apps will get immediately updated to support a new version of the spec. We want existing users to be able to keep doing what they're doing, and opt in to newer features if their client supports it.

[zagortenay333]

If a client didn't update to a new version of the spec, then they support version 1 by default.

[cweagans]

Well, yeah. That's exactly what is being accomplished. If the comment is missing, the file supports version 1 of the spec. If the comment is present, then it's whatever version the comment specifies.

Clients that have not been upgraded don't know about the semantics of that comment, and therefore cannot use that comment at all to determine the semantics of the rest of the file.

[zagortenay333]

I meant that it shouldn't be part of the specification that version 1 is assumed if a comment is missing, so that a user can just tell the client to assume a version without having to type a meta-comment at the top of the file.

[koppor]

I am working in a project for reference management. We store bibliographic data in BibTeX files, which are plain-text sort-of-key-value files.

Regarding the version information, we also changed our store of custom information (such as the groups where each bibliography entry belongs to). Here, we parse the file and guess by certain "properties" of the data whether it is the old format or the new one. In case we hit the old one, we offer to convert it to the new one.

Although having versioning information is a good practise, what should the tool do if no such version information is contained in the file? Is the file invalid? What is a sensible default? What happens if all users always delete the version information? - Our tool also loads text files produced from other tools. The user can edit the text file manually. Thus, we decided not to rely on any meta data concerning the version or encoding information. We removed all code regarding that and go for the content.

In case a file is both v1 and v2, why add version information? If a file is v1 only, how does the tool behave if a user manually changes the version information from v1 to v2?

Based on my experience with JabRef, I would propose: Do not include version information.

[arcturus140]

adding the version information in the file when it is missing automatically breaks the file for all older clients. We can also not expect the user to know which upgrades break how many clients he may be using...