Manual:Pywikibot/Development/Guidelines

This is a page for helping new people who wants to help and improve pywikibot

Reporting a bug
You have seen a problem in pywikibot? it's not the end of the world, just keep calm and report it in bugzilla, the important notes for reporting bugs are:
 * Get output of  and amend it to your report
 * Include exact steps to reproduce the bug
 * Include the difference between expected output and real output

Bug triage
If you like to help pywikibot is not just writing codes! you can help easily by categorizing, confirming, prioritizing bugs. Just go to the browse project in bugzilla and get the list.

Making a patch
How to submit patches...configure git/gerrit. etc.

Follow steps in Gerrit/Getting started and run this: and after modifying codes follow steps in Gerrit/Tutorial


 * Windows: Developer using Windows may also use Gerrit/TortoiseGit tutorial for further informations.

Example (step-by-step)
So for example if you want to work with compat (formerly known as trunk), do the following, step-by-step:
 * 1) setup your software:
 * 2) if not done already for svn access; create an SSH key, a developer account and add your public key to gerrit as well as to wikitech
 * 3) install 'git' package
 * 4) install 'git-review' package
 * 5) * the one by openstack, NOT the one by Facebook
 * 6) * any version like 1.12, 1.21, but NOT v1.18
 * 7) clone and setup your repo:
 * 8) clone the git repo with all submodules by using (like  )   and wait, this step will take some time
 * 9) enter the directory
 * 10) config git setting for this repo/directory only (not global, in case e.g. you have different pseudo for multiple projects)   and   in order to configure this globally, use the   parameter
 * 11) config your terminal/console to output english messages (in order to work properly with git review, see Gerrit/git-review)   this has to be done every time a new console is started, in order to configure this permanently, put this into your   or similar setup file
 * 12) setup git review for this repo only   and enter your   again, this is an important step - if you forget it, according to Gerrit/Tutorial, the final   below (needed to commit your changes for review) will fail - though this can be still solved then
 * 13) work with the repo, e.g. commit patches for review:
 * 14) switch to the master branch (might not be needed)
 * 15) update the current branch to revision online (like  )
 * 16) create your own local temporary branch for working   and try to choose a   with the help of the branch naming tips available - the branch can be removed when not needed anymore with
 * 17) now write some code; see the Git commands add, rm and mv to add, remove or rename files - when you're ready go to the next step
 * 18) commit your changes to your local temporary branch with   (you can use   instead of   and   instead of  ) and, as used from svn, enter a meaningful commit message, e.g. a short description of your code changes
 * 19) optionally check your changes by looking at the committed data   and make sure that you are sending what you wanted to
 * 20) send the data to the online repository, resp. gerrit for review (like  )
 * 21) finally go to Gerrit, click on your change and write a reviewer name in the input box near the "Add Reviewer" button
 * 22) optionally/opt-in further settings:
 * 23) * enable RCS keywords expansion (like svn:keywords ) by using git hooks (explained in detail here - german only)
 * 24) ** for compat (trunk):
 * 25) ** for core (rewrite):
 * 26) ** (may be we should consider using the git-rcs-keywords module as mentioned in dealing-with-svn-keyword-expansion-with-git-svn)

jenkins-bot messages
https://integration.wikimedia.org/ci/job/pywikibot-core-pep8/46/console : FAILURE in ?s (non-voting) The patchset committed did not pass PEP8 code style checks. That says nothing about the functionality of the code but about the style.

https://integration.wikimedia.org/ci/job/pywikibot-core-pyflakes/46/console : FAILURE in ?s (non-voting) The patchset committed did not pass pyflakes code style checks. That says nothing about the functionality of the code but about the style.

This change could not be automatically merged with the current state of the repository. Please rebase your change and upload a new patchset. The pachset cannot be merged automatically into current HEAD. Please consider Gerrit/Advanced usage for a solution.

More info about this can be found in Gerrit/Tutorial and Gerrit/Tutorial.

Follow pep8
These are some standards for writing codes - pep8 is mainly about writing your codes in a way that would be easy to read. Some of the most important things are:
 * Add a space before and after an equal sign ("=") when you want to define a variable
 * Don't make very long lines, split them into several lines based on what they are
 * Indentation are really important about readability of code, use it properly, use 4 spaces instead of tab character

Follow pep257
This standard is mainly about docstrings (documentation inside codes). 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 codes.

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:

It's really important to list all of usable methods of a class or arguments a script.

Using decorator is highly recommended. There is a help page about them in python.org help wiki

Test via pyflakes
pyflakes is a tool to check correct usage of variables in codes - 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

Miscellany

 * Use "bot" instead of "robot" in naming variables, documentation, etc.
 * Don't use tab character, use 4 spaces instead
 * If you want to remove a part of code, don't comment it out. Just remove it.