Guidelines and Policy
Contributing
You can structure your changes into a series of commits in git. A series of well disposed changes is easy to review. Write a sufficient commit log message for each change. Do not fear writing down details about why the change is implemented as it is, if there are multiple alternatives. Also, if you forsee any future possibilites or problems, please describe them in the commit log.
You can find kupfer's git repository at github and fork it there, for easy publication of your changes.
If you suggest your changes for inclusion into Kupfer, make sure you have read the whole Guidelines and Policy chapter of this manual. And take care to structure your changes, do not fear asking for advice. Good Luck!
Icon Guidelines
Consider the following:
A Leaf is an object, a metaphor for a physical thing. It can have as detailed icon as is possible.
An Action is a verb, a command that can be carried out. Choose its name with care. The icon should be simple, maybe assign the action to a category, rather than trying to illustrate the action itself. For example, all text display actions use the "bold style" icon, in some icon themes simply a bold "A".
Coding style
Kupfer python code is indented with four spaces. If you contribute to kupfer keep in mind that
Python code should be clear
Kupfer is a simple project. Do simple first.
Python's general style guideline is called PEP 8, and you should programmers should read it. The advice given there is very useful when coding for Kupfer.
Specific Points
Using rank_adjust
A declaration like this can modify the ranking of an object:
class MyAction (Action):
rank_adjust = -5
...
Often, this is useless. Don't use it, let Kupfer learn which actions are important.
If the action is destructive, the adjust should be negative. Never positive. For example Move to Trash has a negative 10 rank_adjust.
If the action is very general, and applies to almost everything but still should never be the default for anything, the adjust should be negative.
Using super(..)
You should use the Python 3 super() without arguments.
Old code was using the following style which worked best in older Python, but the style is obsolete:
Source.__init__(self, _("Recent items"))
Text and Encodings
Care must be taken with all input and output text and its encoding! Internally, kupfer must use str for all internal text. The module kupfer.support.kupferstring has functions for the most important text conversions.
A resource for unicode in Python:
Always find out what encoding you must expect for externally read text (from files or command output). If you must guess, use the locale encoding. Text received from GTK is always str, which means encoding is not a problem.
Note that the gettext function _() always returns a unicode string (str).