======================
Contributing to ediwo
======================

As an free software project, ediwo welcomes contributions of many forms.

Examples of contributions include:

* Code patches
* Documentation improvements
* Bug reports and patch reviews
* Translations

By contributing, contributors agree to the Contributor License Agreement cla.txt which can be found in the source root.


Philosophy
==========

The principal development philosophy is KISS, Keep it simple and stupid:
https://en.wikipedia.org/wiki/KISS_principle

The project aims for maximum benefit for society as a whole and the planet.
Therefore:

* standards compatibility is a main goal
* old software and hardware on the server and client should be supported
* resource consumption should be held to a minimum

The project aims for separation of data logic and presentation logic.
Logic that belongs to the data should be in the database. (views, triggers, rls...)
The Django code should as far as possible only contain presentation logic.
It should be easy to write other representation programs on top of the database
(Cli, GUI, Mobile App etc.) in any language without redundant data logic in each client.

Client logic and requirements should be held to a minimum, to avoid client
compatibility problems and code redundancy. If something can be solved on the server side it should
be done there.


External dependencies, versions
===============================

The goal is to minimize administration effort for running the site.
Therefore all external dependencies must be in the Debian stable repository or
in an well maintained Debian stable compatible external repository which has:

* automatic security updates for the life time of Debian stable LTS
* a stable branch with extensive testing before stable release
* strong security measures as good or better than Debian

Unfortunately PyPi does not meet those criterias at the moment.

All code must be compatible with the software versions in the current Debian stable
repository and be actively maintained.

Exceptions from that rules have to be thoroughly justified and approved by the maintainer.

This program is developed and tested under Debian stable, but should work on other platforms.
Although multi platform is not a primary concern.
Python 2 is not supported.


Issues
======

Bugs, enhancements proposals and road maps are maintained in the todo.org file in the root
directory. Although it is an Emacs Organizer Mode file it can be edited with any text editor.
https://orgmode.org/


Patches
=======

Please export your changes from your local repository and email them to code<at>ediwo<dot>com
https://www.mercurial-scm.org/wiki/TutorialExport


Coding Style / Tests / Documentation
====================================

Code language is English.

Unless otherwise specified, follow PEP 8.
https://www.python.org/dev/peps/pep-0008/

Please write unit tests to automatically verify your code.
We do not aim for 100% test coverage, but at least all external URLs must be tested with all
supported HTTP methods.

All user facing functionality patches must include also a patch for the user
documentation, at least the English one.

Please comment your code.


Source Repository
=================

ediwo uses mercurial for source control.
The main repo is at:

https://hg.ediwo.com/ediwo

command to clone a local copy::

  $ hg clone https://hg.ediwo.com/ediwo my-ediwo

see https://www.mercurial-scm.org/wiki/TutorialClone


Installation for development
============================

* install python

* install dependencies in debian_install.sh
  This is a bash shell file for automatic debian stable installation. The information
  in it is also valuable for manual installation on other platforms. Please
  install the versions that are in Debian stable.
  Only Postgresql is supported as a database backend.

* copy ediwo/settings/__init__.py_template to ediwo/settings/__init__.py and
  configure your install specific settings (database, secret_key etc.)

* configure Postgresql pg_hba.conf so that your database user can access your database and
  the test database (same name but with prefix 'test_').
  Example lines::

  local   ediwodb      ediwo                                   trust
  local   test_ediwodb ediwo                                   trust

  restart Postgresql::

  $ sudo systemctl restart postgresql

* create the Postgresql database::
  $ ./setup_pgdb.sh


Contributors
============

* Gregor Horvath, 2020 : idea, development, project lead
* Franz Gratzer,  2020 : design ideas, mock-up, usability testing


Contact maintainer
==================

mailto: code<at>ediwo<dot>com