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 :ref:`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 :ref:`patches` section. .. _issue-tracker: 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: Patches ------- If you have some programming skills, you can hack Defernia system by yourself. To setup the local development environment of Defernia, read :ref:`using-virtualenv` and :doc:`start` 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: .. sourcecode:: console $ hg clone https://bitbucket.org/dahlia/defernia For hacking Defernia system there are several :ref:`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 :guilabel:`fork` button in the web page. .. image:: _static/bitbucket-fork.png :alt: 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. .. image:: _static/bitbucket-pull-request.png :alt: 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. .. _Mercurial: http://mercurial.selenic.com/ .. _Bitbucket: https://bitbucket.org/dahlia/defernia .. _GitHub: https://github.com/ .. _prerequisite-knowledges: 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/ __ http://learnpythonthehardway.org/ Mercurial_ As written below, the source code is mananaged by Mercurial. Moreover, the core of :mod:`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. __ http://hginit.com/ 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. __ http://flask.pocoo.org/docs/ SQLAlchemy_ SQLAlchemy is a high level abstraction for relational databases. We use it to deal with data stored in :abbr:`RDBMS (Relational Database Management System)`. 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 :ref:`ormtutorial_toplevel` 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 :abbr:`RDBMS (Relational Database Management System)`. 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 :doc:`API reference ` can help for you. .. _Python: http://python.org/ .. _Flask: http://flask.pocoo.org/ .. _SQLAlchemy: http://www.sqlalchemy.org/ .. _PostgreSQL: http://www.postgresql.org/ .. _SQLite: http://sqlite.org/ 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 :file:`erniatests` directory. You should attach regression tests also for bug patches. .. _Sphinx: http://sphinx.pocoo.org/ .. _reStructuredText: http://docutils.sourceforge.net/rst.html Unit testing ------------ .. image:: https://drone.io/bitbucket.org/dahlia/defernia/status.png :alt: Build Status :target: https://drone.io/bitbucket.org/dahlia/defernia/latest We encourage to write unit tests including contributed codes as well. You can run unit tests using :program:`tox`. Install tox using :program:`pip` or packaging system software of your operating system (e.g. :program:`apt-get`, :program:`yum`) if you don't have :program:`tox`. .. sourcecode:: console $ tox All test codes are in :file:`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. :abbr:`IRC (Internet Relay Chat)` --------------------------------- 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. .. _Ozinger: http://ozinger.org/