Changes

The community around Sugar is very diverse and only a small part of it is directly involved in software development. Of those, an even smaller part is personally responsible for the quality of the software, its growth, and its availability to translators, distributors and deployers. See [[Development Team/Release/Modules]] for a list of modules with their maintainers and peers.

The community around Sugar is very diverse and only a small part of it is directly involved in software development. Of those, an even smaller part is personally responsible for the quality of the software, its growth, and its availability to translators, distributors and deployers. See [[Development Team/Release/Modules]] for a list of modules with their maintainers and peers.

But this smaller group of people aren't the only ones that can contribute to the development of Sugar itself. Anyone with some spare time and enough skills and passion can make significant contributions to Sugar, but in order to bound to a limit the maintenance work, the submitted code needs to have some characteristics, explained in this page.

But this smaller group of people aren't the only ones that can contribute to the development of Sugar itself. Anyone with some spare time and enough skills and passion can make significant contributions to Sugar, but in order to bound to a limit the maintenance work, the submitted code needs to have some characteristics, explained on this page.

Please take these recommendations with a grain of salt, they are intended to make the life of your fellow developers easier, and are not intended to be general rules of "good programming".

Please take these recommendations with a grain of salt, they are intended to make the life of your fellow developers easier, and are not intended to be general rules of "good programming".

== It's all about communication ==

== It's all about communication ==

Make sure that [[Development Team/API policy|API policy]] rules are respected.

Make sure that [[Development Team/API policy|API policy]] rules are respected.

== Code style ==

== Code style ==

Follow [http://www.python.org/dev/peps/pep-0008/ PEP 08], but as it is quite broad, it's not enough in itself to guarantee a minimum of consistency. Some more comments below.

Follow [http://www.python.org/dev/peps/pep-0008/ PEP 08], but as it is quite broad, it's not enough in itself to guarantee a minimum of consistency. Some more comments below.

Use inline comments sparingly. If you feel your code needs an inline comment, consider instead splitting the method in two, with a reasonable name and API comment. API comments should say '''what''' the code does, not '''how''' it does it. How your code works should be clear from the code structure, refactor until the code structure is a clear reflection of its purpose.

Use inline comments sparingly. If you feel your code needs an inline comment, consider instead splitting the method in two, with a reasonable name and API comment. API comments should say '''what''' the code does, not '''how''' it does it. How your code works should be clear from the code structure—refactor until the code structure is a clear reflection of its purpose.

 

Take your time when choosing names for variables and other identifiers, it's your best chance to make your code understandable along with code organization. The cost of interpreting abbreviated identifiers is most often not worth the less typing.

Python is a very expressive language that allows for different programming models, before using the more exotic features consider readability over compactness and think that we want people to be able to contribute to Sugar without needing to be familiar with the whole Python syntax.

Python is a very expressive language that allows for different programming models, before using the more exotic features consider readability over compactness, and think that we want people to be able to contribute to Sugar without needing to be familiar with the whole Python syntax.

== Miscellaneous ==

== Miscellaneous ==

* Use logging.debug('foo %r bar', x) instead of logging.debug('foo %r bar' % x). This is more robust and formatting only happens if we actually log something.

* Use <code>logging.debug('foo %r bar', x)</code> instead of <code>logging.debug('foo %r bar' % x)</code>. This is more robust and formatting only happens if we actually log something.

* When you catch an exception and want to log it, use traceback.format_exc().

* When you catch an exception and want to log it, use logging.exception(), this will print the whole backtrace and exception information, which is very useful when debugging.

== Tools ==

== Tools ==

When possible use tools to check your code, this will save lots of time for everybody involved.

When possible use tools to check your code, this will save lots of time for everybody involved.

Please try to use [http://www.logilab.org/857 pylint] to verify your patch for things like exceeding 80 columns etc., unused imports and unused variables. Pylint is not a tool you can rely on 100% but it helps to follow some guidelines and to avoid the most stupid errors like typos. sugar-jhbuild contains a pylintrc you can use in the <code>scripts/data</code> directory: [http://git.sugarlabs.org/projects/sugar-jhbuild/repos/mainline/blobs/master/scripts/data/pylintrc pylintrc] (follow "raw blob data").

Please try to use [http://www.logilab.org/857 pylint] to verify your patch for things like exceeding 80 columns etc., unused imports and unused variables. Pylint is not a tool you can rely on 100%, but it helps to follow some guidelines and to avoid the most stupid errors like typos. It gets called with the name of the (installed) Python module to check, e.g. for sugar:

./sugar-jhbuild run pylint jarabe

 

You can also run it on individual files so you don't need to install first (doesn't work well for sugar-base and sugar-toolkit because they use the same module name):

./sugar-jhbuild run pylint source/sugar-datastore/src/carquinyol/*.py

[http://svn.browsershots.org/trunk/devtools/pep8/pep8.py pep8.py] catches more style errors than pylint, so make sure to run that one, too.

[http://github.com/cburroughs/pep8.py pep8.py] catches more style errors than pylint, so make sure to run that one, too:

./sugar-jhbuild run pep8 --repeat source/sugar-datastore/src/carquinyol/*.py

In the sugar packages use 'make distcheck' to make sure all files are included and the POTFILES.in is up to date.

In the sugar packages use 'make distcheck' to make sure all files are included and the POTFILES.in is up to date.

We are running periodic builds of Sugar using [http://buildbot.sugarlabs.org Buildbot]. If you break the build you are responsible to get it fixed. If you don't, the release team will take care of it, most likely by reverting your patch. More in detail:

We are running periodic builds of Sugar using [http://buildbot.sugarlabs.org Buildbot]. If you break the build you are responsible to get it fixed. If you don't, the release team will take care of it, most likely by reverting your patch. More in detail:

* Every change that causes build or check failures should be immediately fixed or reverted.

* Every change that causes build or test suite failures should be immediately fixed or reverted.

* Every change that causes check warnings should be fixed or reverted within 24 hours.

* Every change that causes pylint or PEP8 warnings should be fixed or reverted within 24 hours.

You can use the check command in jhbuild to execute the same checks that [http://buildbot.sugarlabs.org/ Buildbot] is doing.

You can pass the <code>--check</code> option to [[Development Team/Jhbuild|Jhbuild]] to execute the same checks that [http://buildbot.sugarlabs.org/ Buildbot] is doing:

./sugar-jhbuild buildone -n --check sugar-artwork

== References ==

== References ==

http://developer.gnome.org/doc/guides/programming-guidelines/index.html

http://developer.gnome.org/doc/guides/programming-guidelines/index.html

https://developer.mozilla.org/En/Mozilla_Coding_Style_Guide

https://developer.mozilla.org/En/Mozilla_Coding_Style_Guide