how to reconcile new .clicompanion format and users old format .clicompanion file

With the next release we are introducing a new format for the .clicompanion file.
I will quickly go over the format differences

An example showing the difference between the old and new formats

NEW
dpkg -l @: package : Find version of a package

OLD
dpkg -l : package : Find version of a package

This new format will allow a user to add commands that can require arguments at run time anywhere in the command. The old format only allowed input at the end of the command. Which worked for a lot of commands, but not all. An example of a command that would not have worked with the old format:

cat @ @ | sort | uniq > @ : file1, file2, file3 : combine, sort and remove

THE BUG
We need to update users .clicompanion files with the new expanded default file. This will provide examples of the new format to the user. We can not simply overwrite the .clicompanion file because a user may have put a lot of work into building his 'command dictionary'.

Ideally we would combine the two files. We would need to replace all the default commands (or the default commands with user arguments). Leaving the users added commands untouched.

One solution is to just back up the old file(.clicompanion.bak) and put the new in place.

Conversation with persia on subject.

01:36 < persia> OK. Ship the new file in /etc/clicompanion.d/
01:36 < persia> Ship some checksums for all old standard files somewhere.
01:37 < persia> Change the runtime logic that copies the file to $HOME if it isn't present to
                also check to see if the checksums for the file when it is present are in the
                checksum list file.
01:37 < persia> If they are, also copy the new one.
01:37 < persia> If the admin changes the /etc/clicompanion.d/ file, they will get a conffile
                change warning, and can deal with it.
01:38 < persia> If a user changes their personal config, they won't get it overwritten.
01:38 < duanedesign> ahh. :)
01:39 < persia> For extra points, categorise the checksums as "V1", "V2", etc. so that you
                can tell the user "The config format has changed: would you like to back up
                your existing configuration and run with a standard configuration, or would
                you prefer to exit? Documentation on the new format is available in
                /usr/share/doc/.../
01:39 < persia> But since they are categorised, you can also change the config within the
                same format, and use the same logic to auto-update any users using the
                default config.
01:40 < persia> So, that presumes you have a wrapper or some such for some broken program
                that can only process $HOME/.clicompanion
01:40 < duanedesign> oh neat. Telling the user about the documentation of the new format
                     would be very helpful
01:40 < persia> A better solution would be not to copy it, and have the program fall back to
                /etc/... $HOME/,.clicompanion (or better $XDG_CONFIG_DIR/clicompanion )
                wasn't present.
01:41 < persia> Then you can immediately identify users with custom configurations by the
                presence of the file. If it's present, attempt to parse: if parse fails,
                report that the format is incompatible, offer to move it out of the way (to
                .bak or something) or exit, and point at docs for the new format.
01:45 < duanedesign> persia: do you have any recommendation where the checksums should go?
01:45 < persia> I'd probably stick them in /usr/share/ somewhere. Up to you.
01:46 < persia> If you're feeling especially admin-friendly, you could stick them in
                /var/lib/ and add a tool so that admin could add new items.
01:46 < persia> This would allow an admin to create a new default, and automatically notify
                the end-users, etc.
01:48 < duanedesign> ok. well i do have a /usr/share/clicompanion directory being created for
                     the locale folder...
01:49 < duanedesign> thank you. I will get started :)
01:49 < persia> Have fun. The number of ways you can engineer this is limitless, and mostly
                depends on how complicated you want to get.
01:49 < persia> The key points to watch out for are:
01:50 < persia> 1) if the admin changes the default system behaviour from that shipped in
                your package, you need to respect that.
01:50 < persia> 2) If the user changes the behaviour of the app from that shipped in your
                package, you need to respect that
01:50 < persia> 3) If at all possible, try to give users a "Just Works" experience: if manual
                action is required on their part: be sure to point them at docs, etc.