Beanstalkd: misleading comment about Walver in dat.h

[kr]

This comment isn't really true:

https://github.com/beanstalkd/beanstalkd/blob/f7803cab05dbbb21f606555676e1ac559afc1bd5/dat.h#L136-L137

Only two WAL versions have appeared in beanstalkd releases: version 5 and version 7. Current beanstalkd can read either version, but only writes version 7. (Other version numbers have been consumed in commits between releases.)

If you run beanstalkd 1.5 or newer on a binlog written by 1.4.6 or older, it will automatically convert to the new format. There is even a test for this, cttest_binlog_v5, but that test requires a binary called beanstalkd-1.4.6 in $PATH to create the old binlog, so it is probably getting skipped in CI at the moment.

The principle I've been following here is to make sure beanstalkd can read all older versions that have been in a release. See fileread in file.c. I never bothered to handle unreleased versions, because only beanstalkd developers need to worry about that, and only when changing the WAL format.

Also, by not providing a way to write older versions, this means users can never convert backwards, only forwards. But I think that's okay, because in general it may not even be possible to convert to an older format, if beanstalkd adds functionality that's unsupported in older formats.

(Sorry for not posting this as a review on #456. I was traveling and didn't get to it in time.)

[kr]

Here's the workflow I was using to do this:

1. If any change needs to be made to the format, first increment Walver.
2. If and only if this is the first such change since the last release:
   
   
   
   1. Copy-paste relevant file-reading functions in file.c and add the old version number to their names. For example, if you are incrementing Walver from 7 to 8, then copy readrec to readrec7. (Currently, there is only one such function, readrec. But if a future readrec calls other version-specific functions, those will have to be copied too.)
   
   
   2. Add a switch case to fileread for the old version.
   
   
3. Modify the current reading function (readrec) to reflect your change.

[kr]

Incrementing Walver for every change, even if not every version will be released, is helpful even if it "wastes" version numbers. It is a really easy thing to do and it means during development you won't have to worry about misinterpreting the contents of a binlog that you generated with a dev copy of beanstalkd.

[ysmolsky]

I feel like I should have waited more on that PR. I am sorry being too eager to commit my semi baked comments. I will give it proper wait time for the next PRs.

Thank you, Keith. Your input is invaluable. I have seen those functions and a tests and my guess was that all migrations are manual, that for every migration we need to follow the procedure you described above. What I had in mind that we somehow automate this process, but in a short team I do not see it's possible and we better stick to the old way.

Anyway, my comment is not accurate and I will add your comments into the file. They are important to new contributors.

Thank you again.

[kr]

No worries! I hadn't given any indication I was going to be offline for a while. It's probably better not to block on me. Definitely don't feel bad about being too eager, you've really brought this project back to life.