| 2010-09-30 07:13:53 |
Duane Hinnen |
description |
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. |
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.
|
|
