*****************************
How to hack on Simple Backup
*****************************

Style guide
-----------

When writing code for SBackup please follow the style guide for Python code,
PEP 8. See http://www.python.org/dev/peps/pep-0008/.

Tools to ease you writing good style code are:

Eclipse IDE
Pydev
Pylint - checks the code style, imports, unused variables etc.

Commit messages should have the same format as changelog entries
  * [FIX] LP Bug #577296: Crash, a number is required, not str
  * [Fix] regression: avoid backup of circular symlinks
  * [Fix]: implemented a work-around to enable notifications
  * [Change]: Logarithmic purge disabled since it still has issues  
  * [Enhancement]: improvements to the release script

Summary of style guide
----------------------

* Use 4 spaces per indentation level.
* Never mix tabs and spaces.
* Use spaces instead of tabs (set this in your IDE). 
* Limit line length to 80-120 characters.
* Modules should have short, all-lowercase names.  Underscores can be used
  in the module name if it improves readability.
* Function names, method names and instance variables should be lowercase, with
  words separated by underscores as necessary to improve readability.
* Top level functions and classes are separated by 2 lines, method definitions
  within classes by a single line


Branches and versions
=====================

Development takes place in the trunk version. At a certain point in time, a
version branch is forked and a release is prepared. Fixes and modifications
made to a specific branch are then re-merged into the trunk.


How to run from source code
---------------------------

Attention: For the current version, it is not recommended to install
Simple Backup for productive use and to code on it beside at the same time.

The reason is that there are 2 packages for import in
that case, it might occur name conflicts: in your development environment and
in the Python site-packages directory.

ALTERNATIVE A - recommended
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Use helper scripts shipped with sbackup (based on fresh wheezy installation)

0. Install bazaar and set your Launchpad ID

	~$ sudo apt-get install bzr
		You have not informed bzr of your Launchpad ID, and you must do this to
		write to Launchpad or access private data.  See "bzr help launchpad-login".
		-> inform bzr of ID

	install bzrtools and bzr-gtk (if you want to)
	see: bzr help gtk


    bzr whoami "Firstname Lastname <your@email.org>"
	bzr launchpad-login <username>

	see: https://help.launchpad.net/YourAccount/CreatingAnSSHKeyPair
	add ssh key (or copy .ssh from another machine)
	


1. create a directory for your local branch

	~$ mkdir Dokumente/sbackup
	~$ cd Dokumente/sbackup


2. checkout branch

	~/Dokumente/sbackup$ bzr branch lp:sbackup/0.11
		Branched 244 revisions.
		~/Dokumente/sbackup$ cd 0.11/
		~/Dokumente/sbackup/0.11$ ls
		AUTHORS    COPYING  debian  HACKING  INSTALL   METAINFO  nssbackup.ChangeLog  README   setup.py.in  tests  tools
		ChangeLog  data     doc     help     Makefile  NEWS      po                   scripts  src          TODO

	~/Dokumente/sbackup/0.11$ bzr log -r-2..
		
		------------------------------------------------------------
		revno: 244
		committer: Jean-Peer Lorenz <peer.loz@gmx.net>
		branch nick: 0.11
		timestamp: Thu 2012-01-05 18:03:14 +0100
		message:
		  * updated changelog
		------------------------------------------------------------
		revno: 243
		committer: Jean-Peer Lorenz <peer.loz@gmx.net>
		branch nick: 0.11
		timestamp: Thu 2012-01-05 18:02:50 +0100
		message:
		  * [Fix] LP: #768080 incremental snapshots store more files than needed:
		  add TAR option '--no-check-device'. Thanks to Rogach (platon7pronko) and
		  Felix Griewald (tiiunder) for the patch.


3. You have successfully branched sbackup to your local harddrive!


4. Before actually running scripts in order to test modifications, please setup
your development environment by means of following script:

	~/Dokumente/sbackup/0.11$ source tools/setup-dev.sh
	=SBACKUP DEVELOPMENT= user@host:~/Dokumente/sbackup/0.11/scripts$ 


5. You are now in a dedicated environment (note the leading
'=SBACKUP DEVELOPMENT= ' in front of your prompt). It is changed into
the 'script' directory of your branch.

Execute scripts as you like,
e.g. run a backup with
	./sbackup-run --no-dbus --config-file=<path to your test config file>

or full backups with
	./sbackup-run --no-dbus --full --config-file=<path to your test config file>

or restore with
	./sbackup-restore --config=<path to your test config file> <name of snapshot>


6. To finish hacking, just exit the development environment by typing 'exit'

7. optional: you can also call './tools/teardown-dev.sh' at any time in order
to clean up your branch and remove temporary files and installed language files.


8. push changes
   bzr bind lp:~nssbackup-dev/sbackup/0.11 in case the checkout was done
   before bzr launchpad-login call; be sure your SSH keys are in place

   bzr push

   when getting error "http does not support mkdir()", try:
   bzr push --remember bzr+ssh://bazaar.launchpad.net/~nssbackup-dev/sbackup/0.11
	


ALTERNATIVE B
~~~~~~~~~~~~~

Prepare setup manually. If you know what you are doing you can run development
code for testing as follows:

1. Add your development directory to the Python path. Do this in a shell, so
   it does not affect the whole system! You can use the following commands:

	declare -x PYTHONPATH="/Path-to-development/sbackup/src:"$PYTHONPATH

2. Manually create a file `resources` with appropriate content based on the
   template file `resources.in` and place it in the package's top level
   directory (src/sbackup). This file is usually created during installation
   and therefore it is required to tweak it by hand for development.
 
3. Analogous to step 2) create a file `metainfo` with appropriate content based
   on the template file `metainfo.in` and place it in the package's top level
   directory (src/sbackup).
   
4. Go to the source directory to run the application you wish
	
	cd /Path-to-development/0.2/sripts
	python sbackup-config-gtk
	python sbackup-restore-gtk
	python sbackup
	

Limitations
~~~~~~~~~~~

When running solely from a development environment it is currently not
possible to perform/test any D-Bus related actions including the indicator
application. Reason for this is the missing/not installed policy file
in /etc/dbus-1/system.d. When installing sbackup properly from source or
deb this file will be installed and D-Bus communication is possible.


Translations
============

First, some links related to translations using Launchpad/Rosetta:

* http://blog.launchpad.net/general/trying-out-launchpad-translations
* https://help.launchpad.net/Translations/YourProject
* https://help.launchpad.net/Translations/YourProject/ImportingTranslations
* https://help.launchpad.net/Translations/YourProject/ImportPolicy
* https://help.launchpad.net/Translations/YourProject/Exports


Testing
=======

Following test must be executed (automated or manually) before publishing
a new version on each target distribution. Use the spreadsheet to document
your efforts and results.

