Re: cross-platform backup tool First beta v2.1.2b1 release towards v2.2.0

Hi,

On 18/09/2022 14:31, Frank Crawford wrote:
> On Sun, 2022-09-18 at 13:51 +0200, Eric Lavarde wrote:
> ...
>> You shouldn't need to use the old syntax, as long as you use the API
>> 200. With API 201, the server is called with the new syntax
>> (rdiff-backup server ...), else (the default) it's called with the
>> old
>> syntax (rdiff-backup --server ...). If you observed something
>> different,
>> please create an issue. In any case, you can still put whatever you
>> want
>> in the remote schema.
>>
> Just on that, I want to confirm that the API refers as much to the CLI
> syntax as the internal usage, i.e. 300 may have a different syntax to
> 201, but 2XX will always be backwards compatible with the command-line,
> in that you may add more, but old things should work?

Roughly, yes. It's actually a bit more complicated than that:

- the CLI is part of the API only when calling the server process
- else you can use the API independently from the CLI, as long as you 
don't use new features only available in newer APIs, potentially 
reachable only through new CLI options (we have such features only 
available with API 201, but none yet requiring such extra options, but 
that could come).
- it's a bit far away to see through the crystal ball, but I envision 
that all 2.y versions of rdiff-backup will speak all 2NN APIs, until we 
reach an API called e.g. 299. rdiff-backup 3.y will speak API 300, which 
will be technically the same as 299, but will have dropped compatibility 
with any lower API. I find this a bit difficult to explain so I might 
change slightly the semantic to make it easier to understand, and keep 
track of.

The basic idea will remain that rdiff-backup 3.0 will be able to speak 
with the last rdiff-backup 2.x version (and none else), while all 2.x 
will be able to speak with each other. And the old CLI will indeed most 
probably be dropped with 3.0 (so get used to it).
- one other thing foreseen is that 2.1/2.2 speaks API 200 by default 
(the original 2.0.5 implicit API), while 2.4 will speak 201 by default 
(but still be able to speak 200 with 2.0.5), and might introduce 202 (or 
whichever number I decide). And so on, so that each API version will 
have one version to mature before it becomes the default.
- this said, the API version is pinned if you set --api-version 
explicitly, and --api-version 201 will fail if you try to talk to 2.0.5.

If it's confusing, check:

$ rdiff-backup info
---
exec:
   api_version:
     actual: 0
     default: 200
     max: 201
     min: 200
[...]

$ rdiff-backup --api-version=201 info
---
exec:
   api_version:
     actual: 201
     default: 200
     max: 201
     min: 200
[...]

you'll notice that the _actual_ API version is pinned by the 2nd call, 
whereas it's still negotiable in the 1st case (zero value).

I'm still unsure if I'm going to implement a separate format versioning 
for the repository, or just align it to the API versioning.

Hope this helps,
Eric

PS: as a side and unrelated remark, I hope you've read the FILES section 
of the man pages and discovered the cool new feature with config file!