Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

update README

  • Loading branch information...
commit dd26f39004f4a1f0a9e05e9157638da80c66a822 1 parent 0df109c
@ofri authored
Showing with 129 additions and 164 deletions.
  1. +77 −98 README
  2. +52 −66 README.markdown
View
175 README
@@ -1,103 +1,82 @@
-Get the Code:
-============
-
-Fork code repository:
-Browse to http://github.com/hasadna/Open-Knesset
-and click Fork
-Browse to your Open-Knesset fork and click the SSH button.
-Copy the SSH address and run the following command (widows users - use git bash)
-$ git clone paste_the_ssh_address_here.git
-
-
-Installation:
-=============
-
-For Ubuntu, make sure the following packages are installed:
-
- sudo apt-get install python python-imaging python-setuptools python-vobject python-gdata
-
-$ python bootstrap.py
-$ bin/buildout
-$ bin/test
-$ bin/django syncdb --migrate # do not create a superuser account
-$ bin/django loaddata dev
-$ bin/django createsuperuser # to create your superuser account
-$ bin/django runserver
-# create your local setting file to store a bunch of things that you do NOT want to push to everyone
-# NOTE: NEVER push settings.py with local changes!
-$ vi src/knesset/local_settings.py
-$ DATABASE_NAME = '<your-local-path>dev.db' # Or path to database file if using sqlite3.
-
-TROUBLE?
-=====
-
-- Some of the mirrors are flaky so you might need to run the buildout several times until all downloads succeed*
+# Installation #
+
+## Get the code ##
+- Make sure you have git installed, and have an account on github.com. Sign into github. see http://linux.yyz.us/git-howto.html for a short list of options with git and github.com help for more.
+- Fork the repository (https://github.com/ofri/Open-Knesset, top right of page). This creates a copy of the repository under your user.
+- Clone the repository: `git clone https://github.com/your-username/Open-Knesset.git` . This creates a copy of the project on your local machine.
+If you haven't done so already:
+- `git config --local user.name "Your Name"`
+- `git config --local user.email "your@email.com"`
+
+## Prerequisites ##
+- Python 2.x (including dev files)
+- python-setuptools
+
+In Ubuntu this can be done with:
+
+ sudo apt-get install python python-dev python-setuptools
+
+## Installation process ##
+- `python bootstrap.py`
+- `bin/buildout` (if you have a problem, see "Trouble?" below)
+- `bin/test`
+- `bin/django syncdb --migrate` # do not create a superuser account
+- `bin/django loaddata dev`
+- `bin/django createsuperuser` # to create your superuser account
+- `bin/django runserver`
+- `vi src/knesset/local_settings.py` # create your local setting file to store a bunch of things that you do NOT want to push to everyone # NOTE: NEVER push settings.py with local changes!
+- sample input for local_settings.py: `DATABASE_NAME = '<your-local-path>dev.db'` # Or path to database file if using sqlite3.
+
+## Trouble? ##
+- Some of the mirrors are flaky so you might need to run the buildout several times until all downloads succeed.
- currently using MySQL as the database engine is not supported
-- on bin/buildout, problems with getting distribution for 'PIL' can be fixed
- by installing the python-dev package or commenting out 'pil' in setup.py
-
-Update - get your branch updated with the changes done by others
-======
-
-$ cd Open-Knesset
-$ git pull git://github.com/hasadna/Open-Knesset.git master
-$ bin/buildout # only needed if the file buildout.cfg was changed; but can't hurt you if you run it every time.
-$ bin/django syncdb --migrate # do not create a superuser account
-$ bin/test
-$ bin/django runserver
-
-# if you get the add_persons_aliases alert try this:
-$ bin/django migrate --fake persons 0001
-
-Updating the translation strings:
-================================
-$ cd src/knesset
-$ ../../bin/django makemessages -a -e txt,html
-<edit src/knesset/locale/he/LC_MESSAGES/django.po, find your strings and change it to the correct translation>
-$ ../../bin/django compilemessages
-
-Windows Users:
---------------
+- on bin/buildout, problems with getting distribution for 'PIL' can be fixed
+ by installing the python-dev package
+## Windows Users ##
Prerequisites:
-Download and install Python 2.7 from http://www.python.org/download/windows/
-Make sure python and svn are in the system path (control panel->system->advanced->environment variables)
-Download and install svn client from http://www.sliksvn.com/en/download
-Download and install git by following http://help.github.com/win-git-installation/
-Generate an ssh key to your git account by following http://help.github.com/msysgit-key-setup/
+- Download and install Python 2.7 from http://www.python.org/download/windows/
+- Download and install git by following http://help.github.com/win-git-installation/
+- Generate an ssh key to your git account by following http://help.github.com/msysgit-key-setup/
Running the installation instructions:
-open command line change dir to the Open-Knesset folder
-run the installation instructions above (Without the $ ofcourse and with backslashes)
-
-Checking in
-==============
-see http://linux.yyz.us/git-howto.html for a short list of options with git
-
-First time
-----------
-
-Every other time
------------------
-
-$ git diff # to know what changed since your last commit
-$ git add -filename # if you added new files (commit doesn't add new files)
-$ git commit -a # commit all changes to your local repository
-# commit note should include fix#: [number] of the redline bug number youre fixing (if any)
-$ git push # push changes to git repo
-# go to git, do a "pull request" from [release manager] so code will get to production
-
-Updating Text
-==============
-
-Adding a field to existing model
-================================
-
-# add the field you want to model sample_model
-# see our naming conventions for migrations: under the directory "migrations" under the model's folder - notice the number is added automatically
-# so 0003_add_members_blog is actually add_members_blog
-$ bin/django schemamigration knesset.sample_model --auto naming_convention_change_name
-$ bin/django syncdb --migrate
-
-
-
+- open command line change dir to the Open-Knesset folder
+- run the installation instructions above (Without the $ ofcourse and with backslashes)
+
+# Working process #
+
+## Before you code ##
+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/ofri/Open-Knesset.git master
+- bin/buildout # only needed if the file buildout.cfg was changed; but can't hurt you if you run it every time.
+- bin/django syncdb --migrate # do not create a superuser account
+- bin/test # if there are any failures, contact the other developers to see if that's something you should worry about.
+- bin/django runserver # now you can play with the site using your browser
+
+if you get the add_persons_aliases alert try `bin/django migrate --fake persons 0001`
+
+## When you code ##
+### General ###
+- Write tests for everything that you write.
+- Keep performance in mind - test the number of db queries your code performs using `bin/django runserver` and access a page that runs the code you changed. See the output of the dev-server before and after your change.
+
+### Adding a field to existing model ###
+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
+- bin/django 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.
+- bin/django syncdb --migrate # run the migration.
+- don't forget to git add/commit the migration file.
+
+### Updating the translation strings ###
+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.
+
+## After you code ##
+- bin/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.
View
118 README.markdown
@@ -1,61 +1,41 @@
-Installation:
-=============
+# Installation #
-For Ubuntu, make sure the following packages are installed:
+## Get the code ##
+- Make sure you have git installed, and have an account on github.com. Sign into github. see http://linux.yyz.us/git-howto.html for a short list of options with git and github.com help for more.
+- Fork the repository (https://github.com/ofri/Open-Knesset, top right of page). This creates a copy of the repository under your user.
+- Clone the repository: `git clone https://github.com/your-username/Open-Knesset.git` . This creates a copy of the project on your local machine.
+If you haven't done so already:
+- `git config --local user.name "Your Name"`
+- `git config --local user.email "your@email.com"`
- sudo apt-get install python python-dev python-imaging python-setuptools python-vobject python-gdata
+## Prerequisites ##
+- Python 2.x (including dev files)
+- python-setuptools
-- `python bootstrap.py`
+In Ubuntu this can be done with:
-- `bin/buildout` (if you have a problem, see "Trouble?" below)
+ sudo apt-get install python python-dev python-setuptools
+## Installation process ##
+- `python bootstrap.py`
+- `bin/buildout` (if you have a problem, see "Trouble?" below)
- `bin/test`
-
- `bin/django syncdb --migrate` # do not create a superuser account
-
- `bin/django loaddata dev`
-
- `bin/django createsuperuser` # to create your superuser account
-
- `bin/django runserver`
-
- `vi src/knesset/local_settings.py` # create your local setting file to store a bunch of things that you do NOT want to push to everyone # NOTE: NEVER push settings.py with local changes!
-
- sample input for local_settings.py: `DATABASE_NAME = '<your-local-path>dev.db'` # Or path to database file if using sqlite3.
-Trouble?
-=======
+## Trouble? ##
- Some of the mirrors are flaky so you might need to run the buildout several times until all downloads succeed.
- currently using MySQL as the database engine is not supported
-- on bin/buildout, problems with getting distribution for 'PIL' can be fixed
+- on bin/buildout, problems with getting distribution for 'PIL' can be fixed
by installing the python-dev package
-Update - get your branch updated with the changes done by others
-======
-
-- cd Open-Knesset
-- git pull git://github.com/hasadna/Open-Knesset.git master
-- bin/buildout # only needed if the file buildout.cfg was changed; but can't hurt you if you run it every time.
-- bin/django syncdb --migrate # do not create a superuser account
-- bin/test
-- bin/django runserver
-
-if you get the add_persons_aliases alert try `bin/django migrate --fake persons 0001`
-
-Updating the translation strings:
-================================
-- cd src/knesset
-- ../../bin/django makemessages -a -e txt,html
-<edit src/knesset/locale/he/LC_MESSAGES/django.po, find your strings and change it to the correct translation>
-- ../../bin/django compilemessages
-
-Windows Users:
---------------
-
+## Windows Users ##
Prerequisites:
- Download and install Python 2.7 from http://www.python.org/download/windows/
-- Make sure python and svn are in the system path (control panel->system->advanced->environment variables)
-- Download and install svn client from http://www.sliksvn.com/en/download
- Download and install git by following http://help.github.com/win-git-installation/
- Generate an ssh key to your git account by following http://help.github.com/msysgit-key-setup/
@@ -63,34 +43,40 @@ Running the installation instructions:
- open command line change dir to the Open-Knesset folder
- run the installation instructions above (Without the $ ofcourse and with backslashes)
-Checking in
-==============
-see http://linux.yyz.us/git-howto.html for a short list of options with git
+# Working process #
-First time
-----------
-
-Every other time
------------------
-
-- git diff # to know what changed since your last commit
-- git add -filename # if you added new files (commit doesn't add new files)
-- git commit -a # commit all changes to your local repository
-- commit note should include fix#: [number] of the redline bug number youre fixing (if any)
-- git push # push changes to git repo
-- go to git, do a "pull request" from [release manager] so code will get to production
+## Before you code ##
+Get your branch updated with the changes done by others. Please do this every time before you start developing:
-Updating Text
-==============
-
-Adding a field to existing model
-================================
-
-- add the field you want to model sample_model
-- see our naming conventions for migrations: under the directory "migrations" under the model's folder - notice the number is added automatically
-- so 0003_add_members_blog is actually add_members_blog
-- bin/django schemamigration knesset.sample_model --auto naming_convention_change_name
-- bin/django syncdb --migrate
+- cd Open-Knesset
+- git pull git://github.com/ofri/Open-Knesset.git master
+- bin/buildout # only needed if the file buildout.cfg was changed; but can't hurt you if you run it every time.
+- bin/django syncdb --migrate # do not create a superuser account
+- bin/test # if there are any failures, contact the other developers to see if that's something you should worry about.
+- bin/django runserver # now you can play with the site using your browser
+if you get the add_persons_aliases alert try `bin/django migrate --fake persons 0001`
-
+## When you code ##
+### General ###
+- Write tests for everything that you write.
+- Keep performance in mind - test the number of db queries your code performs using `bin/django runserver` and access a page that runs the code you changed. See the output of the dev-server before and after your change.
+
+### Adding a field to existing model ###
+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
+- bin/django 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.
+- bin/django syncdb --migrate # run the migration.
+- don't forget to git add/commit the migration file.
+
+### Updating the translation strings ###
+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.
+
+## After you code ##
+- bin/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.
Please sign in to comment.
Something went wrong with that request. Please try again.