doc/HACKING

   1 Guidelines on Code Modification
   2 ===============================
   3
   4 Coding Style
   5 ------------
   6
   7 * Use syntax compatible to both python 2.6 and 3.1.
   8 * Use docstrings with pydoc in mind
   9 * Follow the style guide for python code:
  10     http://www.python.org/dev/peps/pep-0008/
  11 * Although this guide suggests otherwise, tabs are used for indentation
  12     of code and docstrings.  In other documents (readme, etc), use spaces.
  13 * Test the code with "doctest" where it makes sense
  14
  15
  16 Patches
  17 -------
  18
  19 Send patches, created with "git format-patch", to the email adress
  20
  21     romanz@lavabit.com
  22
  23 If you plan to do major changes, or many changes over time, I encourage
  24 you to create a fork on GitHub, Gitorious or any other site.
  25
  26
  27 Starting Points
  28 ---------------
  29
  30 Good places to read about ranger internals are:
  31 ranger/core/actions.py
  32 ranger/core/environment.py
  33 ranger/fsobject/fsobject.py
  34
  35 About the UI:
  36 ranger/gui/widgets/browsercolumn.py
  37 ranger/gui/widgets/browserview.py
  38 ranger/gui/ui.py
  39
  40
  41 Common Changes
  42 --------------
  43
  44 * Change which files are previewed in the auto preview:
  45 In ranger/fsobject/file.py
  46 the constant PREVIEW_BLACKLIST
  47
  48 * Adding options:
  49 In ranger/defaults/options.py
  50 add the default value, like: my_option = True
  51 In ranger/container/settingobject.py
  52 add the name of your option to the constant ALLOWED_SETTINGS
  53
  54 The setting is now accessible at self.settings.my_option,
  55 assuming <self> is a "SettingsAware" object.
  56
  57 * Adding colorschemes:
  58 Copy ranger/colorschemes/default.py to ranger/colorschemes/myscheme.py
  59 and modify it according to your needs.  Alternatively, mimic the jungle
  60 colorscheme.  It subclasses the default scheme and just modifies a few things.
  61 In ranger/defaults/options.py (or ~/.config/ranger/options.py), change
  62     colorscheme = 'default'
  63 to: colorscheme = 'myscheme'
  64
  65 * Change the file type => application associations:
  66 In ranger/defaults/apps.py
  67 modify the method app_default.
  68 The variable "f" is a filesystem-object with attributes like mimetype,
  69 extension, etc.  For a full list, check ranger/fsobject/fsobject.py
  70
  71 * Change the file extension => mime type associations:
  72 Modify ranger/data/mime.types
  73
  74
  75 Version Numbering
  76 -----------------
  77
  78 Three numbers;  The first changes on a rewrite, the second changes when major
  79 configuration incompatibilities occur and the third changes with each release.