Getting started developing
============================
Everyone is welcome to send patches to lago, but we know that not everybody
knows everything, so here's a reference list of technologies and methodologies
that lago uses for reference.
Python!
----------
Lago is written in python 2.7 (for now), so you should get yourself used to
basic-to-medium python constructs and technics like:
* Basic python:
Built-in types, flow control, pythonisms (import this)
* Object oriented programming (OOP) in python:
Magic methods, class inheritance
Some useful resources:
* Base docs: https://docs.python.org/2.7/
* Built-in types: https://docs.python.org/2.7/library/stdtypes.html
* About classes:
https://docs.python.org/2.7/reference/datamodel.html#new-style-and-classic-classes
* The Zen of Python::
> python -c "import this"
The Zen of Python, by Tim Peters
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!
Bash
------
Even though there is not much bash code, the functional tests and some support
scripts use it, so better to get some basics on it. We will try to follow the
same standards for it than the `oVirt project has`_.
Libvirt + qemu/kvm
-----------------------
As we are using intesively libvirt and qemu/kvm, it's a good idea to get
yourself familiar with the main commands and services:
* libvirt: http://libvirt.org
* virsh client: http://libvirt.org/virshcmdref.html
* qemu (qemu-img is useful to deal with vm disk images):
https://en.wikibooks.org/wiki/QEMU/Images
Also, there's a library and a set of tools from the libguestfs_ project that
we use to prepare templates and are very useful when debugging, make sure you
play at least with virt-builder, virt-customize, virt-sparsify and guestmount.
Git + Github
--------------
We use git as code version system, and we host it on Github right now, so if
you are not familiar with any of those tools, you should get started with them,
specially you should be able to:
* Clone a repo from github
* Fork a repo from github
* Create/delete/move to branches (git checkout)
* Move to different points in git history (git reset)
* Create/delete tags (git tag)
* See the history (git log)
* Create/amend commits (git commit)
* Retrieve changes from the upstream repository (git fetch)
* Apply your changes on top of the retrieved ones (git rebase)
* Apply your changes as a merge commit (git merge)
* Squash/reorder existing commits (git rebase --interactive)
* Send your changes to the upstream (git push)
* Create a pull request
You can always go to `the git docs`_ though there is a lot of good literature
on it too.
Unit tests with py.test
--------------------------
Lately we decided to use `py.test`_ for the unit tests, and all the current
unit tests were migrated to it. We encourage adding unit tests to any pull
requests you send.
Functional tests with bats
---------------------------
For the functional tests, we decided to use `bats framework`_. It's completely
written in bash, and if you are modifying or adding any functionality, you
should add/modify those tests accordingly. It has a couple of custom
constructs, so take a look to the `bats docs`_ while reading/writing tests.
Packaging
------------
Our preferred distribution vector is though packages. Right now we are only
building for rpm-based system, so right now you can just take a peek on
`how to build rpms`_. Keep in mind also that we try to move as much of the
packaging logic as posible to the `python packaging system`_ itself too, worth
getting used to it too.
Where to go next
-----------------
You can continue `setting up your environment`_ and try running the examples
in the readme_ to get used to lago. Once you get familiar with it, you can pick
any of the `existing issues`_ and send a pull request to fix it, so you get
used to the `ci process`_ we use to get stuff developed flawlessly and quickly,
welcome!
.. _`oVirt project has`: http://ovirt-infra-docs.readthedocs.org/en/latest/General/Infra_Bash_style_guide.html
.. _`py.test`: http://pytest.org
.. _libguestfs: http://libguestfs.org/
.. _`bats framework`: https://github.com/sstephenson/bats
.. _`bats docs`: https://github.com/sstephenson/bats#writing-tests
.. _`the git docs`: http://www.git-scm.com/docs
.. _`how to build rpms`: http://www.rpm.org/max-rpm/index.html
.. _`python packaging system`: https://packaging.python.org/en/latest/distributing/
.. _`setting up your environment`: Env_Setup.html
.. _`readme`: README.html
.. _`existing issues`: https://github.com/lago-project/lago/issues
.. _`ci process`: CI.html