Bug 6250 - Fremantle osso-backup developer documentation is out of date
: Fremantle osso-backup developer documentation is out of date
Status: NEW
Product: Developer Guide
maemo.org wiki
: 5.0-final
: All Maemo
: Low normal with 2 votes (vote)
: ---
Assigned To: Andre Klapper
: wiki
: http://wiki.maemo.org/Documentation/M...
: docs
:
:
  Show dependency tree
 
Reported: 2009-11-19 10:59 UTC by Lucas Maneos
Modified: 2010-05-17 15:55 UTC (History)
4 users (show)

See Also:


Attachments


Note

You need to log in before you can comment on or make changes to this bug.


Description Lucas Maneos (reporter) 2009-11-19 10:59:46 UTC
SOFTWARE VERSION:
Fremantle final SDK, osso-backup 1.8.16-1+0m5 on device (1.2009.42-11).

The online documentation looks like a straight copy of the Diablo version
(<http://maemo.org/maemo_release_documentation/maemo4.1.x/node8.html#SECTION00860000000000000000>)[1],
and does not mention new functionality available in Fremantle.

More specifically, in Fremantle the directories /etc/osso-backup/pre-backup.d
and /etc/osso-backup/post-backup.d are also available for custom scripts that
run before/after a backup operation.  There may be other differences / new
features we don't know about :-)

[1] with the only exception of the categories list, which is up to date in the
"Custom back-up locations" section, but not in the "After restore run scripts"
section.
Comment 1 Dave Neary maemo.org 2009-11-19 13:51:32 UTC
Are there any specific changes you'd like to see made?

Without meaning to be glib, this page is in the wiki. Perhaps you'd like to
make the modifications yourself?

Dave.
Comment 2 Lucas Maneos (reporter) 2009-11-19 22:22:11 UTC
(In reply to comment #1)
> Without meaning to be glib, this page is in the wiki. Perhaps you'd like to
> make the modifications yourself?

Well, I agree with the principle in general, but a) I don't have the relevant
information and b) this is a particularly sensitive case since
incorrect/misleading information can result in data loss.

See bug 6178 (which I probably should have mentioned in the original report,
sorry) for the background details.  Bug 6178 comment 4 is the first and only
mention I've seen of the new script directories and google doesn't return
anything useful either.  Also, as I said there may be other surprises yet to be
discovered (despite the name osso-backup is closed-source so the UTSL approach
isn't an option).

There must be some internal docs/specs describing the Fremantle
features/behaviour, so someone familiar with the details should update the
public developer docs.

In the meantime I made a couple of edits for things I'm fairly certain about
and I'm watching the page so don't worry if you have to throw away the whole
thing to post the new content.
Comment 3 Dave Neary maemo.org 2009-12-23 21:03:58 UTC
Andre: do you know who is responsible for oss-backup, please? We need to have
them check the state of the documentation & verify if it is indeed out of date.
Comment 4 Jarmo Tikka nokia 2009-12-28 11:59:55 UTC
Just more info that we have official Fremantle examples for backup here
https://garage.maemo.org/svn/maemoexamples/trunk/maemo-examples/ (see
example_backup_*) in case somebody wants to fix Fremantle Developer Guide for
this.
Comment 5 Dave Neary maemo.org 2009-12-30 15:11:48 UTC
(In reply to comment #4)
> Just more info that we have official Fremantle examples for backup here
> https://garage.maemo.org/svn/maemoexamples/trunk/maemo-examples/ (see
> example_backup_*) in case somebody wants to fix Fremantle Developer Guide for
> this.

The example is a rather trivial usage of the API, and doesn't actually show the
thing which the original reporter is asking about. The server example
initialises a context, connects to the com.nokia.backup service, and sends
"backup_start" followed by "backup_finish".

The client just listens to the com.nokia.backup service and prints a message
saying "I can write" or "I can't write" depending on the back-up status.

This appears not to be up to date about how to configure the backup
application. The section
http://wiki.maemo.org/Documentation/Maemo_5_Developer_Guide/Generic_Platform_Components/Using_Backup_Application#Custom_back-up_locations
is the section in question. Do you know who can tell us if this paragraph is
still accurate?

Thanks!
Comment 6 Dave Neary maemo.org 2009-12-30 15:26:43 UTC
In fact, after trying to improve the paragraph, I think that I don't understand
it at all. There are a few questions which arise:

* What is the so-called locations configuration? Where is it set, and what is
its default value?
* Where should users put their custom back-up scripts?
* What happens if one script has a file explicitly included with location, and
another has it excluded with exclude?

I don't understand this phrase in particular:
For other data not normally backed up, the so-called locations configuration is
used. It is important that the locations configuration paths MUST NOT overlap
with the documents path.

What is the documents path? What does overlap mean? Does it mean that I want to
back up files in the documents path, or that a locatiopns file is stored in the
documents path, etc? I am a bit lost.
Comment 7 Andre Klapper maemo.org 2010-05-17 15:55:34 UTC
[Rearrangement of Documentation bug reports.]