qutebrowser/HACKING

qutebrowser HACKING
===================
The Compiler <mail@qutebrowser.org>
:icons:
:data-uri:
:toc:

I `&lt;3` footnote:[Of course, that says `<3` in HTML.] contributors!

If anything in this document would prevent you from contributing, please let
me know, and contribute anyways! This is only meant to make it easier for me,
but if you don't follow anything in here, I won't be mad at you. I will
probably change it for you then, though.

If you have any problems and need help, I'm more than happy to help you! You
can get help in several ways:

* Send a mail to the mailing list at qutebrowser@lists.qutebrowser.org
(optionally
https://lists.schokokeks.org/mailman/listinfo.cgi/qutebrowser[subscribe]
first).
* Join the IRC channel `#qutebrowser` on http://www.freenode.org/[Freenode].

Finding something to work on
----------------------------

Chances are you already know something to improve or add when you're reading
this. It might be a good idea to ask on the ML or IRC channel to make sure I
agree with your idea -- though I most likely will be okay with it.

If you want to find something useful to do, check the `BUGS` and `TODO` files.

There are also some things to do if you don't want to write code:

* Help the community, e.g. on the mailinglist and IRC channel.
* Improve the documentation.
* Help on the website and graphics (logo, etc.)

Using git
---------

qutebrowser uses http://git-scm.com/[git] for its development. You can clone
the repo like this:

----
git clone git://the-compiler.org/qutebrowser
----

If you don't know git, a http://git-scm.com/[git cheatsheet] might come in
handy. Of course, if using git is the issue which prevents you from
contributing, feel free to send normal patches instead, e.g. generated via
`diff -Nur`.

Finding the correct branch
~~~~~~~~~~~~~~~~~~~~~~~~~~

Currently, qutebrowser is developed in the `master` branch. Feature branches
are used by me occasionally and pushed as a backup, but frequently
force-pushed. Do *not* base your work on any of the feature branches, use
`master` instead.

After v0.1, an additional `development` branch will be added. Then, base new
features on the `development` branch, and bugfixes on the `master` branch.

You can then checkout the correct branch via:

----
git checkout base-branch <1>
----
<1> Of course replace `base-branch` by `development`/`master`.


Getting patches
~~~~~~~~~~~~~~~

After you finished your work and did run `git commit`, you can get patches of
the changes like this:

----
git format-patch origin/master <1>
----
<1> Replace `master` by the branch your work was based on, e.g.
`origin/develop`.

Useful utilities
----------------

Checkers
~~~~~~~~

In the _scripts/_ subfolder, there are a `run_checks.py`.

`run_checks.py` runs a bunch of static checks on all source files. It uses the
following checkers to do so:

* unittests using the Python
https://docs.python.org/3.4/library/unittest.html[unittest] framework
* https://pypi.python.org/pypi/flake8/1.3.1[flake8]
* https://github.com/GreenSteam/pep257/[pep257]
* http://pylint.org/[pylint]
* Custom checkers for untracked git files, whitespace/CRLF problems,
`set_trace` invocations and VCS conflict markers.

If you changed `setup.py`/`MANIFEST.in` and add the `--setup` argument, the
following additional checkers are run:

* https://pypi.python.org/pypi/pyroma/0.9.3[pyroma]
* https://github.com/mgedmin/check-manifest[check-manifest]

Please make sure this script runs without any warnings on your new
contributions. There's of course the possibility of false-positives, and the
following techniques are useful to handle these:

* Use `_foo` for unused parameters, with `foo` being a descriptive name. Using
`_` is discouraged.
* If you think you have a good reason to suppress a message, add the following
comment:
+
----
# pylint: disable=message-name
----
+
Note you can add this per line, per function/class, or per file. Please use the
smallest scope which makes sense. Most of the time, this will be line scope.
+
* If you really think a check shouldn't be done globally as it yields a lot of
false-positives, let me know! I'm still tweaking the parameters.

Profiling
~~~~~~~~~

In the _scripts/_ subfolder there's a `run_profile.py` which profiles the code
and shows a graphical representation of what takes how much time.

It needs https://pypi.python.org/pypi/pyprof2calltree/[pyprof2calltree] and
http://kcachegrind.sourceforge.net/html/Home.html[KCacheGrind]. It uses the
built-in Python https://docs.python.org/3.4/library/profile.html[cProfile]
module.

Debugging
~~~~~~~~~

In the `qutebrowser.utils.debug` and `qutebrowser.utils.signal` modules there
are some useful functions for debugging. In particular you should use
`set_trace` from `qutebrowser.utils.debug` instead of `pdb` to set breakpoints
or you'll get annoying Qt error messages.

When starting qutebrowser with the `--debug` flag you also get useful debug
logs. You can add `--logfilter category[,category,...]` to restrict logging to
the given categories.

With `--debug` there are also some additional `debug-*` commands available, for
example `debug-all-objects` and `debug-all-widgets` which prints a list of all
Qt objects or widgets to the debug log -- this is very useful for finding
memory leaks.

Useful websites
~~~~~~~~~~~~~~~

Some resources which might be handy:

* http://qt-project.org/doc/qt-5/classes.html[The Qt5 reference]
* https://docs.python.org/3/library/index.html[The Python reference]
* http://httpbin.org/[httpbin, a test service for HTTP requests/responses]
* http://requestb.in/[RequestBin, a service to inspect HTTP requests]
* http://greenbytes.de/tech/tc2231/[Test cases for the `Content-Disposition`
header]

Style conventions
-----------------

As you might have noticed, I *really* like clean and consistent code. While I
won't reject your contribution when you don't follow the guidelines, I'd be
really glad if you'd do so.

qutebrowser's coding conventions are based on
http://legacy.python.org/dev/peps/pep-0008/[PEP8] and the https://google-styleguide.googlecode.com/svn/trunk/pyguide.html[Google Python style guidelines] with some additions:

* Methods overriding Qt methods (obviously!) don't follow the naming schemes.
* Everything else does though, even slots.
* Docstring are like described in
http://legacy.python.org/dev/peps/pep-0257/[PEP257] and the google guidelines.
* Class docstrings have additional `Attributes:`, `Class attributes:` and
  `Signals:` sections, method/function docstrings have an `Emit:` section.
+
Example for a class docstring:
+
[source,python]
----
"""Some object.

Attributes:
  blub: The current thing to handle.

Signals:
  valueChanged: When a value changed.
                arg: The new value
"""
----
+
Example for a method/function docstring:
+
[source,python]
----
"""Do something special.

Args:
  foo: ...

Return:
  True if something, False if something else.

Raise:
  ValueError if foo is None

Emit:
  value_changed
"""
----
+
* The layout of a module should be roughly like this:
  - Shebang (`#!/usr/bin/python`, if needed)
  - vim-modeline (`# vim: ft=python fileencoding=utf-8 sts=4 sw=4 et`)
  - Copyright
  - GPL boilerplate
  - Module docstring
  - Python standard library imports
  - PyQt imports
  - qutebrowser imports
  - functions
  - classes
* The layout of a class should be like this:
  - docstring
  - `__magic__` methods
  - properties
  - _private methods
  - public methods
  - `on_*` methods
  - overrides of Qt methods