Commit 0a5af425 authored by Alexandru Băluț's avatar Alexandru Băluț

docs: Update hacking formatting and content

Differential Revision: https://phabricator.freedesktop.org/D1051
parent 5085fd17
# Hacking on Pitivi
## The pitivi development environment
## The Pitivi development environment
### Setup pitivi
### Setup Pitivi
The official way of getting your environment up and running is by using
[flatpak](http://flatpak.org/)
[flatpak](http://flatpak.org/).
You first need to [get flatpak](http://flatpak.org/getting.html)
making sure you also install flatpak-builder, which might be provided by an
additional package on some distributions (please tell us if it is the case
for yours so we can make a list here).
Then, create a development environment folder and get the [https://git.gnome.org/browse/pitivi/tree/ Pitivi source code] into it:
Create a development environment folder and get the [Pitivi source code](https://git.gnome.org/browse/pitivi/tree/) into it:
```
$ mkdir pitivi-dev && cd pitivi-dev
$ git clone https://git.gnome.org/browse/pitivi
$ cd pitivi/
```
Finally you just need to run:
Finally to enter the dev env you just need to run:
```
$ source bin/pitivi-env
```
Run `pitivi` while inside the environment to launch Pitivi. Next you should run the unittests.
After you edit the source code simply run `pitivi` to see how your changes work.
```
(ptv-flatpak) $ pitivi
(ptv-flatpak) $ nosetests tests/test_*.py
```
### Update the environment
After you hack the source code simply run `pitivi` again to see how your changes work.
In the `pitivi-env` you can simply run:
### Update the environment
To update the dependencies installed in the dev env run:
```
ptvenv --update
(ptv-flatpak) $ ptvenv --update
```
That will actually clean the prefix, update all dependencies from their
git repos and tarballs as defined in the flatpak manifest (located
in build/flatpak/pitivi.template.json)
git repos and tarballs as defined in the [flatpak manifest](https://git.gnome.org/browse/pitivi/tree/build/flatpak/pitivi.template.json) (located
at build/flatpak/pitivi.template.json)
### Work on some pitivi dependencies in the development environment
### Work on some Pitivi dependencies in the development environment
If you have to work on say, [GStreamer Editing Service](https://gstreamer.freedesktop.org/modules/gst-editing-services.html)
you can clone it into you `pitivi-dev`:
If you have to work on say, [GStreamer Editing Services](https://gstreamer.freedesktop.org/modules/gst-editing-services.html)
you can clone it into your `pitivi-dev` folder:
```
(ptv-flatpak) $ git clone git://anongit.freedesktop.org/gstreamer/gst-editing-services
```
Install it in the sandbox by running in the dev env:
```
git clone git://anongit.freedesktop.org/gstreamer/gst-editing-services
(ptv-flatpak) $ autogen
(ptv-flatpak) $ make install
```
Then you can just hack on it, run `autogen` to run `./autogen.sh` with the right arguments for the flatpak sandbox,
and run `make install` to install your changes inside the sandbox (your changes won’t be taken into accout
without installing).
`autogen` is an alias which runs `./autogen.sh` with the right arguments
for the flatpak sandbox.
`make` is also an alias which runs the real `make` inside the sandbox,
thus `make install` will install your changes in the sandbox.
NOTE: When updating the environment, it will use your
local dependencies repositories instead of remote
......@@ -56,55 +68,72 @@ repositories, which means you have to update them yourself.
Also beware that it will not take into account not committed
changes.
# Coding Style Guide
## Coding Style Guide
- We rely on the Python Style Guide PEP-8
(http://www.python.org/doc/peps/pep-0008/)
We rely on the [Python Style Guide PEP-8](https://www.python.org/dev/peps/pep-0008/)
The only exception to it is regarding the "80 columns" rule.
Since Python is a very concise/compact language, we can afford to be
a little bit more flexible on the line length than languages such as C.
The only exception to it is regarding the "80 columns" rule.
Since Python is a very concise/compact language, we can afford to be
a little bit more flexible on the line length than languages such as C.
When deciding whether or not you should split your line when it exceeds
79 characters, ask yourself: "does it truly improve legibility?"
When deciding whether or not you should split your line when it exceeds
79 characters, ask yourself: "Does it truly improve legibility?"
What this translates to is:
- Try to respect the "80 columns/chars" rule of PEP8 when reasonable,
that is when the line is really too long.
What this translates to is:
- When the contents can fit within the 80 chars,
or when it only "slightly" exceeds that limit, keep it on one line.
Otherwise, it just hurts legibility and gives a weird "shape" to the code.
- Avoid having very long lines.
As you can see, it depends on the context
and what you think makes the most easily readable code.
- When the contents only slightly exceeds the 80 chars limit,
consider keeping it on one line. Otherwise it just hurts legibility and
gives a weird "shape" to the code.
### Names
The function names, method names and other class attributes should be
small_caps_with_underscore. For example:
``` lang=python
def some_function():
return ""
For translatable multiline strings, use Python's implicit line continuation
instead of manually concatenating with the plus (+) sign. For example, this
is incorrect, gettext will consider it as two separate strings:
_("<b>First line</b>\n" +
"Some second line that is too long to fit on the first line anyway"
class MyClass:
Instead, this is the translator-friendly version:
_("<b>First line</b>\n"
"Some second line that is too long to fit on the first line anyway"
def a_really_important_method(self):
self.do_something()
- for method names we use the small_caps_with_underscore style
Ex :
@property
def water_level(self):
"""The level of the water in meters."""
return self.__water_level
```
To illustrate how private a method or other class field is, prepend
one or two underscores:
``` lang=python
class MyClass:
def a_really_important_method(self):
self.do_something()
def public_method(self):
...
def _protected_method(self):
...
def __private_method(self):
...
```
- for callbacks, the name of the methods used should:
- follow same conventions as normal method names
Unused arguments in methods should be prefixed with `unused_`.
The most common place where this would happen is in callbacks from
gobject signals. For example, below we don't use the second argument,
but we do use `pad`.
``` lang=python
def __pad_added_cb(self, unused_element, pad):
self.do_something_with(pad)
```
The name of a callback method should:
- be prepended with two underscores since it's private
- be appended with Cb
Ex :
- be appended with `cb`
``` lang=python
class MyClass:
......@@ -116,36 +145,7 @@ changes.
print "our callback was called"
```
- for function names, we use the small_caps_with_underscore style.
This enables clear separation between functions and methods.
- for other class attributes we use the same calling convention as
for functions:
Ex :
``` lang=python
@property
def water_level(self):
""" The level of the water in meters"""
return self.__water_level
```
- unused arguments in method should be prefixed by 'unused_'.
The most common place where this would happen is in callbacks from gobject
signals:
Ex : (we don't use the second argument, but we do use pad)
``` lang=python
def _padAddedCb(self, unused_element, pad):
...
```
- The following naming should be used for class properties/methods:
* public : <name>
* protected : _<name>
* private : __<name>
- Imported modules should be done in this order:
* system modules
* top-level pitivi modules (ex : pitivi.project)
* modules in the same directory
### Imports order
You can guess the order of the imported modules by looking at some py files.
The pre-commit hook has authority in this case as it will reorder the imports
if the order is not good.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment