Manual:Pywikibot/Development/Guidelines

This makes contains Development guidelines for helping people who want to help and improve pywikibot.

Bug triage
If you like to help pywikibot is not just writing code. You can help easily by categorizing, confirming, prioritizing bugs. Just go to the browse projects in phabricator and get the list. For more info see Bug management/How to triage.

Broken test always get a High priority to be solved instantly. Priority of the framework library parts should be higher than that of scripts. Bugs should have higher priority than feature requests.

Making a patch
Read Manual:Pywikibot/Gerrit.

Commit messages should follow the Gerrit Commit message guidelines.

You may prefix the subject with indicator enclosed by square brackets. Here are some examples:


 * [bugfix]: Fixes a bug – refer the related phabricator task. This patch should be priorized.
 * [cleanup]: Code cleanup – does not affect the behavior but improves the code.
 * [compat2core]: Compat to core relationship – scripts merged from compat or some compat functionality merged to core.
 * [i18n]: Internationalisation issues – translating related code, translation dictionaries, interface to translatewiki.net.
 * [FEAT]: Feature – new options, additional behavior. A bit like [IMPR] below.
 * [FIX]: Fixes a bug – same as [bugfix]
 * [IMPR]: Improvement – new options, additional behavior or code cleanup.
 * [L10N]: Localisation issues – project related code mostly done in config or family files.
 * [PEP8]: PEP8 related changes – code style changes, looks nicer.
 * [POC]: Proof of concept – indicates a new concept or new library part.
 * [TEST]: Tests related code – mostly found in tests folder.
 * [WIP]: Working in Process – you may review it but don't submit it with CR+2. The patch author or committer is grateful for reviewing his code, suggestions and remarks.

Follow pep8
These are some standards for writing code - pep8 is mainly about writing your code in a way that would be easy to read. Most of the rules are enforced by Jenkins. Accepted code by Jenkins is voted with +2 (not +1!). Some of the most important things are:
 * Add a space before and after an equal sign ("=") when you want to define a variable except in function/method signatures which don't use any spaces around the equal sign.
 * All lines are shorter than 100 characters, but newly added or modified lines should be kept under 79 characters. The newline character and lines consisting of only one long word (or URL for example) are not counted.
 * Indentation are really important about readability of code, use it properly, use 4 spaces instead of tab character
 * Imports should be sorted by “source” (first standard libraries, then third party and then local (pywikibot)), “type” (first normal  then  ) and then alphabetical. Between the sources (and preferably between types) should be a newline. Also each import has to be in a separated line. For example:

Follow pep257
This standard is mainly about docstrings (documentation inside code). There are two kinds of docstring, one-line docstring and multi-line docstring. A one-line docstring has to be like: and a multi-line docstring has to be like: Multi-line docstrings consist of a summary line just like a one-line docstring, followed by a blank line, followed by a more elaborate description. The summary line may be used by automatic indexing tools; it is important that it fits on one line and is separated from the rest of the docstring by a blank line.

Naming style

 * Names of classes has to be CapWord (use DataPage instead of Datapage, datapage or data_page)
 * Names of functions and methods has to be lowercase with underscores for better readability (e.g. set_label instead setLabel, or SetLabel)
 * Names of errors has to be CapWord with "Error" suffix (like NoPageError)

Documentation
Don't forget to update the documentation both in mediawiki.org and in the code.

For adding the documentation you need to add it at the top of the class or file or function you're working on it as an example:

Every method or function must have a documentation string. Documentation of a class constructor should be placed at the class documentation itself. Documentation should follow Epytext Markup Language. Using Epydoc fields decorators is highly recommended. The pywikibot API reference is generated using the markup language. There is a help page about decorators also in python.org help wiki.

Test via pyflakes
pyflakes is a tool to check correct usage of variables in code - for example if you define a variable and don't' use it (or don't define a variable and use it) it returns an error for you.

You can easily install and run the check, there is a manual for it

Miscellaneous

 * Use "bot" instead of "robot" in naming variables, documentation, etc.
 * Don't use tab character, use 4 spaces instead.
 * For any changes or new lines use single quotes for strings, or double quotes if the string contains a single quote. But keep older code unchanged.
 * Do not use a  prefix on strings, as it is meaningless due to  . But keep older code unchanged.
 * Prefer  instead of modulo operator   for string formatting which is quasi standard in Python 3.
 * If you want to remove a part of code, don't comment it out. Just remove it.
 * Don't use  (carriage return character) in code, Some code editors add it automatically, check and delete them.

Programming Recommendations

 * Code should be written in a way that it is executable for Python version 2.7.4 and higher and 3.4 and higher.
 * Avoid using global variables with defining "global variable" at the beginning of the function.
 * Comparisons to singletons must always done with   or.
 * Use built-in string methods  and   to check for prefixes or suffixes instead of string slicing.