summary refs log tree commit diff stats
path: root/doc/HACKING
diff options
context:
space:
mode:
Diffstat (limited to 'doc/HACKING')
-rw-r--r--doc/HACKING95
1 files changed, 95 insertions, 0 deletions
diff --git a/doc/HACKING b/doc/HACKING
new file mode 100644
index 00000000..dd384758
--- /dev/null
+++ b/doc/HACKING
@@ -0,0 +1,95 @@
+Guidelines on Code Modification
+===============================
+
+Coding Style
+------------
+
+* Use syntax compatible to both python 2.6 and 3.1.
+* Use docstrings with pydoc in mind
+* Follow the style guide for python code:
+    http://www.python.org/dev/peps/pep-0008/
+* Although this guide suggests otherwise, tabs are used for indentation
+    of code and docstrings.  In other documents (readme, etc), use spaces.
+* Test the code with unit tests where it makes sense
+
+
+Patches
+-------
+
+Send patches, created with "git format-patch", to the email adress
+
+    romanz@lavabit.com
+
+If you plan to do major changes, or many changes over time, I encourage
+you to create a fork on GitHub, Gitorious or any other site.
+
+
+Starting Points
+---------------
+
+Good places to read about ranger internals are:
+ranger/core/actions.py
+ranger/core/environment.py
+ranger/fsobject/fsobject.py
+
+About the UI:
+ranger/gui/widgets/browsercolumn.py
+ranger/gui/widgets/browserview.py
+ranger/gui/defaultui.py
+
+
+Common Changes
+--------------
+
+* Change which files are previewed in the auto preview:
+In ranger/gui/widget/browsercolumn.py
+the constant PREVIEW_BLACKLIST
+
+* Adding options:
+In ranger/defaults/options.py
+add the default value, like: my_option = True
+In ranger/shared/settings.py
+add the name of your option to the constant ALLOWED_SETTINGS
+
+The setting is now accessible at self.settings.my_option,
+assuming <self> is a "SettingsAware" object.
+
+* Changing commands, adding aliases:
+ranger/defaults/commands.py
+or ~/.config/ranger/commands.py
+
+* Adding colorschemes:
+Copy ranger/colorschemes/default.py to ranger/colorschemes/myscheme.py
+and modify it according to your needs.  Alternatively, mimic the jungle
+colorscheme.  It subclasses the default scheme and just modifies a few things.
+In ranger/defaults/options.py (or ~/.config/ranger/options.py), change
+    colorscheme = 'default'
+to: colorscheme = 'myscheme'
+
+* Change which files are considered to be "hidden":
+In ranger/defaults/options.py
+change the hidden_filter regular expression.
+
+* Change the key map:
+Modify ranger/defaults/keys.py.  This should be self-explanatory.
+Check out ranger/core/actions.py for the most common actions, of course
+you can also use your own functions.
+
+* Change the file type => application associations:
+In ranger/defaults/apps.py
+modify the method app_default.
+The variable "f" is a filesystem-object with attributes like mimetype,
+extension, etc.  For a full list, check ranger/fsobject/fsobject.py
+
+* Change the file extension => mime type associations:
+Modify ranger/data/mime.types
+
+
+Version Numbering
+-----------------
+
+X.Y.Z, where:
+
+* X: Major version, milestone
+* Y: Minor version, even number => stable version
+* Z: Revision, may be omitted if zero