Contributors’ guide

Note

It is not saying about contents of the fictional world Ernia. If you are interested in contributing to contents of the Ernia world, just go to http://defernia.org/ and then contribute to there.

If you want to contribute to Defernia system, there are several ways to do it. The most end-level contributions are bug reporting and feature request. In these case you can use Issue tracker. The deeper, quicker and more advanced contribution is to submit patches. It is available only if you have some programming skills like programming languages. In this case read Patches section.

Issue tracker

Do you have some ideas for enhancements of Defernia system? Did you face a bug of Defernia system? So, you can report it to our issue tracker and then we will really thank you.

Issue tracker is a thing like customer service for open source softwares. Defernia system is not developed by a commercial company for enterprise, but free developers for hobby. Nobody pays, nobody makes any profit. There are still users but they are not customer. Issue tracker is the official channel of feedback by users to developers and support by developers to users.

Our issue tracker is here:

https://bitbucket.org/dahlia/defernia/issues

To request a feature or report a bug, you should create a new issue:

https://bitbucket.org/dahlia/defernia/issues/new

Before do that, there are some instructions you check first: search already reported issues first. There possibly are the same issues already. If you ignore this and just create an yet another one, it will become just a duplicate reporting that doesn’t help us but just obstructs us.

If you’d search but can’t find anything, creating a new issue is just okay.

Note

Currently the officially allowed languages are English and Korean. There are no developers who speak any other languages in our team yet.

Patches

If you have some programming skills, you can hack Defernia system by yourself. To setup the local development environment of Defernia, read Using virtualenv and Getting started first.

Our source code is maintained by Mercurial, a popular distributed version control system written in Python, and hosted under Bitbucket, a project hosting service. You can check out the source code by the following command:

$ hg clone https://bitbucket.org/dahlia/defernia

For hacking Defernia system there are several Prerequisite knowledges.

To submit your patches, you have to use pull requests feature (originated by GitHub, anyway) of Bitbucket. If you don’t have Bitbucket account, make one first. And then fork our project repository: you can find fork button in the web page.

Forking in Bitbucket repository

And then push your commits into your forked repository. Now you can send the pull request to the Defernia upstream repository.

Sending pull request in Bitbucket repository

If you send the patches by pull requests, we would review your patch and possibly merge these patches into the upstream.

Note

The traditional way to submit patch by attaching diffs into issue tracker is also acceptable but not preferred. There are several reason to prefer pull requests over diff-attached issues/mails:

  • Diff-attached patches lost the correct metadata about its contributor. It also makes hard to blame parts of codes in the future.
  • Maintainers have to download attached diff files and merges them into the repository manually. It’s very boring work.
  • Pull requests can archive contributions originated from outside of development team effectively and in integrated way.

Prerequisite knowledges

Here is the minimum list of prerequisite knowledges:

Python

Defernia is mostly written in Python, a general-purpose programming language. The version we use is 2.6 or higher. We do not use Python 3 or higher.

Our recommended learning material is Learn Python The Hard Way written by Zed Shaw. You can read it legally free from the web:

http://learnpythonthehardway.org/book/

Mercurial

As written below, the source code is mananaged by Mercurial. Moreover, the core of defernia.world module heavily depends on Mercurial. (The world data are stored in Mercurial repositories.)

Our recommended learning material is Hg Init: a Mercurial tutorial written by Joel Spolsky. You can read it legally free.

Flask

The web frontend part of Defernia system is written in Flask web framework. It is easy and comfortable to learn and use. Of course it’s also Python.

The official documentation could be a very good point to start learning Flask.

SQLAlchemy

SQLAlchemy is a high level abstraction for relational databases. We use it to deal with data stored in RDBMS. It’s also Python but contains a number of black magics, so you should learn about several hidden features under the hood of Python to master this large framework.

So, don’t try to master it from scratch. Our recommendation is just to start it from reading Object Relational Tutorial and stop learning about it and then just use it. (Of course, in order to hack core parts of Defernia system you should know SQLAlchemy in depth.)

PostgreSQL or SQLite
We store any data other than about (con)world, users for example, into RDBMS. We use PostgreSQL in production and recommend one of PostgreSQL or SQLite for development purpose.

Of course you have to know about the legacy codebase of Defernia system as well, but this development guide and API reference can help for you.

Convention

Our Python coding style follows the standard of Python: read PEP 8 first. Don’t use hardtab; we only use soft tabs except for Makefile.

We do documentation most of codes in Sphinx and reStructuredText (RST).

Some core parts of Defernia system have unit tests and regression tests in erniatests directory. You should attach regression tests also for bug patches.

Unit testing

Build Status

We encourage to write unit tests including contributed codes as well. You can run unit tests using tox. Install tox using pip or packaging system software of your operating system (e.g. apt-get, yum) if you don’t have tox.

$ tox

All test codes are in erniatests/ directory. Add new test cases into that.

Development team

The authors and maintainers of Defernia system are:

  • Hong Minhee is the founder of Defernia system and the co-founder of The Chronicle of Ernia. He’s the leader of Defernia development team.
  • Hyojin Seo is the co-founder of The Chronicle of Ernia. He’s even not an advanced programmer, still has some programming knowledges. He mostly helps to decide the big picture and the roadmap of Defernia system.

IRC

There is the IRC channel for real-time communication of development team.

irc://irc.ozinger.org/ernia

The IRC network we use is Ozinger. The most of members are always in the channel. You can freely ask us questions related hacking Defernia system. We speak English and Korean both, but we prefer Korean over English frankly.

Project Versions

Table Of Contents

Previous topic

Getting started

Next topic

manage_defernia.py — Defernia manager script

This Page