• Make sure you have an account on GitHub, and you're logged in.
• Fork the repository (top right of page). This creates a copy of the repository under your user.
• See http://linux.yyz.us/git-howto.html for a short list of options with git and github.com help for more.

• Install initial requirements (since we're gonna comile PIL into the environemnt, we'll also need development tools):

  Debian and derivatives like Ubuntu and Mint

  sudo apt-get install build-essential git python python-dev python-setuptools python-virtualenv python-pip
  sudo apt-get build-dep python-imaging
  sudo apt-get build-dep python-lxml

  Fedora

  sudo yum groupinstall "Development Tools" "Development Libraries"
  sudo yum install git python python-devel python-setuptools python-virtualenv python-pip libjpeg-turbo-devel libpng-devel libxml2-devel libxslt-devel

• If you haven't done so already:

  git config --local user.name "Your Name"
  git config --local user.email "your@email.com"

• Clone the repository:

  git clone https://github.com/your-username/Open-Knesset.git

  This creates a copy of the project on your local machine.

• Create the virtual environment, activate it and install dependecies:

  cd Open-Knesset
  virtualenv .
  . bin/activate
  pip install -r requirements.txt

  and wait ...

• Run the tests:

  python manage.py test

• Download the latest Python 2.7 MSI installer matching your architecture (32 or 64 bit). As of this writing, the latest one is 2.7.3. Install it.
• Download distribute for your architecture and install it.

• Open command windows and:

  cd c:\Python27\Scripts
  easy_install pip
  pip install virtualenv

• Download and install the installers matching your architecture for PIL, lxml (version 2.3.x) and ujson.
• Download and install GitHub for Windows.
• Run the GitHub program (should have an icon on the desktop). Sign in with your username and password.

• Run Git Shell (should have an icon on desktop). In that shell create the virtualenv:

  cd C:\
  C:\Python27\Scripts\virtualenv --distribute --system-site-packages oknesset

• Still in that shell activate the virutalenv:

  cd oknesset
  Scripts\activate

  Note the changed prompt with includes the virtualenv's name.

• If you haven't already forked the repository (top right of page), do so.
• Clone the repository. In the oknesset directory and run git clone git@github.com:your-name/Open-Knesset.git
• Install requirements: pip install -r Open-Knesset\requirements.txt and wait.

• Run the tests:

  cd Open-Knesset
  python manage.py test

• Install command line tools. Goto https://developer.apple.com/downloads, Search for "command line tools", download and install the version right for your OS

• Install pip and virtualenv:

  sudo easy_install pip
  sudo pip install virtualenv

• Install homebrew: ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)"

• Install binary python libraries build dependencies:

  brew install jpeg libpng libxml2 libxslt

• We need UTF-8, Add locale settings (in case you're not UTF-8), put in your ~/.profile:

  export LANG="en_US.UTF-8"
  export LC_COLLATE="en_US.UTF-8"
  export LC_CTYPE="en_US.UTF-8"
  export LC_MESSAGES="en_US.UTF-8"
  export LC_MONETARY="en_US.UTF-8"
  export LC_NUMERIC="en_US.UTF-8"
  export LC_TIME="en_US.UTF-8"
  export LC_ALL=

  Once done, source them (to have them updated in the current shell):

  source ~/.profile

• Create the virtual environment. In the terminal cd to the directory you want the environment create it and run:

  virtualenv oknesset

• Activate the virutalenv:

  cd oknesset; . bin/activate

  Note the changed prompt which includes the virtualenv's name.

• Clone the repository:

  git clone https://github.com/your-username/Open-Knesset.git

  This creates a copy of the project on your local machine.

• Install required packages:

  pip install -r Open-Knesset/requirements.txt

  and wait ...

• Run the tests:

  cd Open-Knesset
  python manage.py test

• Run the tests: python manage.py test
• Download and extract dev.db.zip or dev.db.bz2 (bz2 is smaller), place dev.db into the Open-Knesset directory
• Make sure db schema is upated: python manage.py migrate
• Create a superuser if needed: python manage.py createsuperuser
• To run the development server: python manage.py runserver. Once done, you can access it via http://localhost:8000

Let's describe some development workflow.

Make it easier for you and the maintainers, increasing the chances of a pull request getting accepted:

• No big Pull Requests. It makes reviewing and ensuring correctness hard. If possible, break it to smaller commits/pulls, each related to a specific issue.
• Always work on a specific issue from our issue tracker. Open new issue if needed and claim it in the comments.
• Discuss big things in the Open Knesset Developers group.

Get your branch updated with the changes done by others. Please do this every time before you start developing.

• cd Open-Knesset
• git pull git@github.com:hasadna/Open-Knesset.git master Running this command requires having SSH keys registered with github. You can replace 'git@' with 'https://' instead.
• pip install -r requirements.txt # only needed if the file requirements.txt was changed; but can't hurt you if you run it every time.
• python manage.py migrate # do not create a superuser account
• python manage.py test # if there are any failures, contact the other developers to see if that's something you should worry about.
• python manage.py runserver # now you can play with the site using your browser

• Write tests for everything that you write.
• Keep performance in mind - test the number of db queries your code performs using python manage.py runserver and access a page that runs the code you changed. See the output of the dev-server before and after your change.

We use south to manage database migration. The work process looks something like:

• add the field you want to model sample_model in app sample_app
• python manage.py schemamigration sample_app --auto this generates a new migration under src/knesset/sample_app/migrations. You should review it to make sure it does what you expect.
• python manage.py migrate To run the migration (make the changes on the db).
• don't forget to git add/commit the migration file.

Currently, there is no need to update translation (po) files. Its a real headache to merge when there are conflicts, so simply add a note to the commit message "need translations" if you added any _('...') or {% trans '...' %} to the code.

• python manage.py test # make sure you didn't break anything
• git status # to see what changes you made
• git diff filename # to see what changed in a specific file
• git add filename # for each file you changed/added.

• git commit -m "commit message"

  Please write a sensible commit message, and include "fix#: [number]" of the issue number you're working on (if any).

• git push # push changes to git repo
• Go to github.com and send a "pull request" so your code will be reviewed and pulled into the main branch, make sure the base repo is hasadna/Open-Knesset.

• Some of the mirrors may be flaky so you might need to install requirements.txt several times until all downloads succeed.
• Currently using MySQL as the database engine is not supported