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.