[PATCH] docs: Convert to Markdown
Stephen Finucane
stephenfinucane at hotmail.com
Tue Nov 18 08:21:41 AEDT 2014
Make minor changes to bring document in line with Markdown, and add
'.md' extension.
Signed-off-by: Stephen Finucane <stephenfinucane at hotmail.com>
---
docs/HACKING | 69 --------------
docs/HACKING.md | 66 +++++++++++++
docs/INSTALL | 281 --------------------------------------------------------
docs/INSTALL.md | 279 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
4 files changed, 345 insertions(+), 350 deletions(-)
delete mode 100644 docs/HACKING
create mode 100644 docs/HACKING.md
delete mode 100644 docs/INSTALL
create mode 100644 docs/INSTALL.md
diff --git a/docs/HACKING b/docs/HACKING
deleted file mode 100644
index cab59eb..0000000
--- a/docs/HACKING
+++ /dev/null
@@ -1,69 +0,0 @@
-== Using virtualenv
-
-It's always a good idea to use virtualenv to develop python software.
-
-1. Install pip, virtualenv (python-pip, python-virtualenv packages)
-
- Because we're going to recompile our dependencies, we'll also need
- development headers:
-
- - For the MySQL/MariaDB setups: mariadb-devel (Fedora), libmysqlclient-dev
- (Debian)
-
-2. Create a new virtual environement. Virtual environments are "instances" of
- your system python, without any of the extra python packages installed.
- Inside a virtual env, we'll just install the dependencies needed for
- patchwork and run it from there.
-
- Virtual envs are useful to develop and deploy patchwork against a "well
- known" set of dependencies. They can also be used to test patchwork against
- several versions of django, creating a separate virtual env per version.
-
- $ virtualenv django-1.7
-
- will create a virtual env called 'django-1.7' in eponymous directory.
-
-3. Activate a virtual environment
-
- $ sources django-1.7/bin/activate
- (django-1.7)$
-
- The shell prompt is preprended with the virtual env name.
-
-4. Install the required dependencies
-
- To ease this task, it's customary to maintain a list of dependencies in a
- text file and install them in one go. One can maintain such a list of
- dependencies per interesting configuration.
-
- (django-1.7)$ pip install -r docs/requirements-django-1.7-mysql.txt
-
- Of course, this is a one-time step, once installed in the virtual
- environment, no need to to install the requirements everytime.
-
-5. Now one can run patchwork within that environment
-
- (django-1.7)$ ./apps/manage.py --version
- 1.7
- (django-1.7)$ ./apps/manage.py runserver
-
-6. To exit the virtual environment
-
- (django-1.7)$ deactivate
- $
-
-
-== Running tests
-
-- To run all tests:
-
- $ ./manage.py test
-
-- To run all test methods (methods which name starts with 'test') of a TestCase
- subclass:
-
- $ ./manage.py test patchwork.tests.SubjectCleanUpTest
-
-- To run a single test:
-
- $ ./manage.py test patchwork.tests.SubjectCleanUpTest.testSubjectCleanup
diff --git a/docs/HACKING.md b/docs/HACKING.md
new file mode 100644
index 0000000..081c565
--- /dev/null
+++ b/docs/HACKING.md
@@ -0,0 +1,66 @@
+# Using virtualenv
+
+It's always a good idea to use virtualenv to develop python software.
+
+1. Install pip, virtualenv (python-pip, python-virtualenv packages)
+
+ Because we're going to recompile our dependencies, we'll also need
+ development headers. For the MySQL/MariaDB setups these are
+ `mariadb-devel` (Fedora), `libmysqlclient-dev` (Debian)
+
+2. Create a new virtual environement. Virtual environments are "instances" of
+ your system python, without any of the extra python packages installed.
+ Inside a virtual env, we'll just install the dependencies needed for
+ patchwork and run it from there.
+
+ Virtual envs are useful to develop and deploy patchwork against a "well
+ known" set of dependencies. They can also be used to test patchwork against
+ several versions of django, creating a separate virtual env per version.
+
+ $ virtualenv django-1.7
+
+ will create a virtual env called 'django-1.7' in eponymous directory.
+
+3. Activate a virtual environment
+
+ $ sources django-1.7/bin/activate
+ (django-1.7)$
+
+ The shell prompt is preprended with the virtual env name.
+
+4. Install the required dependencies
+
+ To ease this task, it's customary to maintain a list of dependencies in a
+ text file and install them in one go. One can maintain such a list of
+ dependencies per interesting configuration.
+
+ (django-1.7)$ pip install -r docs/requirements-django-1.7-mysql.txt
+
+ Of course, this is a one-time step, once installed in the virtual
+ environment, no need to to install the requirements everytime.
+
+5. Now one can run patchwork within that environment
+
+ (django-1.7)$ ./apps/manage.py --version
+ 1.7
+ (django-1.7)$ ./apps/manage.py runserver
+
+6. To exit the virtual environment
+
+ (django-1.7)$ deactivate
+ $
+
+# Running tests
+
+- To run all tests
+
+ $ ./manage.py test
+
+- To run all test methods (methods which name starts with 'test') of a TestCase
+ subclass
+
+ $ ./manage.py test patchwork.tests.SubjectCleanUpTest
+
+- To run a single test
+
+ $ ./manage.py test patchwork.tests.SubjectCleanUpTest.testSubjectCleanup
diff --git a/docs/INSTALL b/docs/INSTALL
deleted file mode 100644
index d40ddd2..0000000
--- a/docs/INSTALL
+++ /dev/null
@@ -1,281 +0,0 @@
-Deploying Patchwork
-
-Patchwork uses the django framework - there is some background on deploying
-django applications here:
-
- http://www.djangobook.com/en/2.0/chapter12/
-
-You'll need the following (applications used for patchwork development are
-in brackets):
-
- * A python interpreter
- * django >= 1.5
- * A webserver (apache)
- * mod_python or flup
- * A database server (postgresql, mysql)
- * relevant python modules for the database server (e.g: python-mysqldb)
-
-1. Database setup
-
- At present, I've tested with PostgreSQL and (to a lesser extent) MySQL
- database servers. If you have any (positive or negative) experiences with
- either, email me.
-
- For the following commands, a $ prefix signifies that the command should be
- entered at your shell prompt, and a > prefix signifies the commant-line
- client for your sql server (psql or mysql)
-
- Create a database for the system, add accounts for two system users: the
- web user (the user that your web server runs as) and the mail user (the
- user that your mail server runs as). On Ubuntu these are
- www-data and nobody, respectively.
-
- As an alternative, you can use password-based login and a single database
- account. This is described further down.
-
- For PostgreSQL (ident-based)
-
- $ createdb patchwork
- $ createuser www-data
- $ createuser nobody
-
- - postgres uses the standard UNIX authentication, so these users
- will only be accessible for processes running as the same username.
- This means that no passwords need to be set.
-
- For PostgreSQL (password-based)
-
- $ createuser -PE patchwork
- $ createdb -O patchwork patchwork
-
- Once that is done, you need to tell Django about the new Database
- settings, using local_settings.py (see below) to override the defaults
- in settings.py:
-
- DATABASES = {
- 'default': {
- 'ENGINE': 'django.db.backends.postgresql_psycopg2',
- 'HOST': 'localhost',
- 'PORT': '',
- 'USER': 'patchwork',
- 'PASSWORD': 'my_secret_password',
- 'NAME': 'patchwork',
- },
- }
-
- For MySQL:
- $ mysql
- > CREATE DATABASE 'patchwork' CHARACTER SET utf8;
- > CREATE USER 'www-data'@'localhost' IDENTIFIED BY '<password>';
- > CREATE USER 'nobody'@'localhost' IDENTIFIED BY '<password>';
-
- Once that is done, you need to tell Django about the new Database
- settings, using local_settings.py (see below) to override the defaults
- in settings.py:
-
- DATABASES = {
- 'default': {
- 'ENGINE': 'django.db.backends.mysql',
- 'HOST': 'localhost',
- 'PORT': '',
- 'USER': 'patchwork',
- 'PASSWORD': 'my_secret_password',
- 'NAME': 'patchwork',
- 'TEST_CHARSET': 'utf8',
- },
- }
-
- TEST_CHARSET is used when creating tables for the test suite. Without
- it, tests checking for the correct handling of non-ASCII characters
- fail.
-
-2. Django setup
-
- Set up some initial directories in the patchwork base directory:
-
- mkdir -p lib/packages lib/python
-
- lib/packages is for stuff we'll download, lib/python is to add
- to our python path. We'll symlink python modules into lib/python.
-
- At the time of release, patchwork depends on django version 1.5 or
- later. Your distro probably provides this. If not, do a:
-
- cd lib/packages
- git clone https://github.com/django/django.git -b stable/1.5.x
- cd ../python
- ln -s ../packages/django/django ./django
-
- The settings.py file contains default settings for patchwork, you'll
- need to configure settings for your own setup.
-
- Rather than edit settings.py, create a file 'local_settings.py', and
- override or add settings as necessary. You'll need to define the
- following:
-
- SECRET_KEY
- ADMINS
- TIME_ZONE
- LANGUAGE_CODE
- DEFAULT_FROM_EMAIL
- NOTIFICATION_FROM_EMAIL
-
- You can generate the SECRET_KEY with the following python code:
-
- import string, random
- chars = string.letters + string.digits + string.punctuation
- print repr("".join([random.choice(chars) for i in range(0,50)]))
-
- If you wish to enable the XML-RPC interface, add the following to
- your local_settings.py file:
-
- ENABLE_XMLRPC = True
-
- Then, get patchwork to create its tables in your configured database:
-
- cd apps/
- PYTHONPATH=../lib/python ./manage.py syncdb
-
- And add privileges for your mail and web users. This is only needed if
- you use the ident-based approach. If you use password-based database
- authentication, you can skip this step.
-
- Postgresql:
- psql -f lib/sql/grant-all.postgres.sql patchwork
-
- MySQL:
- mysql patchwork < lib/sql/grant-all.mysql.sql
-
-
-3. Apache setup
-
-Example apache configuration files are in lib/apache2/.
-
-wsgi:
- django has built-in support for WSGI, which supersedes the fastcgi
- handler. It is thus the preferred method to run patchwork.
-
- The necessary configuration for Apache2 may be found in
-
- lib/apache2/patchwork.wsgi.conf.
-
- You will need to install/enable mod_wsgi for this to work:
-
- a2enmod wsgi
- apache2ctl restart
-
-mod_python:
-
- An example apache configuration file for mod_python is in:
-
- lib/apache2/patchwork.mod_python.conf
-
- However, mod_python and mod_php may not work well together. So, if your
- web server is used for serving php files, the fastcgi method may suit
- instead.
-
-fastcgi:
-
- django has built-in support for fastcgi, which requires the
- 'flup' python module. An example configuration is in:
-
- lib/apache2/patchwork.fastcgi.conf
-
- - this also requires the mod_rewrite apache module to be loaded.
-
- Once you have apache set up, you can start the fastcgi server with:
-
- cd /srv/patchwork/apps
- ./manage.py runfcgi method=prefork \
- socket=/srv/patchwork/var/fcgi.sock \
- pidfile=/srv/patchwork/var/fcgi.pid
-
-4. Configure patchwork
- Now, you should be able to administer patchwork, by visiting the
- URL:
-
- http://your-host/admin/
-
- You'll probably want to do the following:
-
- * Set up your projects
- * Configure your website address (in the Sites) section of the admin
-
-5. Subscribe a local address to the mailing list
-
- You will need an email address for patchwork to receive email on - for
- example - patchwork@, and this address will need to be subscribed to the
- list. Depending on the mailing list, you will probably need to confirm the
- subscription - temporarily direct the alias to yourself to do this.
-
-6. Setup your MTA to deliver mail to the parsemail script
-
- Your MTA will need to deliver mail to the parsemail script in the email/
- directory. (Note, do not use the parsemail.py script directly). Something
- like this in /etc/aliases is suitable for postfix:
-
- patchwork: "|/srv/patchwork/apps/patchwork/bin/parsemail.sh"
-
- You may need to customise the parsemail.sh script if you haven't installed
- patchwork in /srv/patchwork.
-
- Test that you can deliver a patch to this script:
-
- sudo -u nobody /srv/patchwork/apps/patchwork/bin/parsemail.sh < mail
-
-7. Set up the patchwork cron script
-
- Patchwork uses a cron script to clean up expired registrations, and
- send notifications of patch changes (for projects with this enabled).
-
- Something like this in your crontab should work:
-
- # m h dom mon dow command
- PYTHONPATH=apps:.
- DJANGO_SETTINGS_MODULE=settings
- */10 * * * * cd patchwork; python apps/patchwork/bin/patchwork-cron.py
-
-
- - the frequency should be the same as the NOTIFICATION_DELAY_MINUTES
- setting, which defaults to 10 minutes.
-
-8. Optional: Configure your VCS to automatically update patches
-
- The tools directory of the patchwork distribution contains a file
- named post-receive.hook which is an example git hook that can be
- used to automatically update patches to the Accepted state when
- corresponding comits are pushed via git.
-
- To install this hook, simply copy it to the .git/hooks directory on
- your server, name it post-receive, and make it executable.
-
- This sample hook has support to update patches to different states
- depending on which branch is being pushed to. See the STATE_MAP
- setting in that file.
-
- If you are using a system other than git, you can likely write a
- similar hook using pwclient to update patch state. If you do write
- one, please contribute it.
-
-Some errors:
-
-* __init__() got an unexpected keyword argument 'max_length'
-
- - you're running an old version of django. If your distribution doesn't
- provide a newer version, just download and extract django into
- lib/python/django
-
-* ERROR: permission denied for relation patchwork_...
-
- - the user that patchwork is running as (ie, the user of the web-server)
- doesn't have access to the patchwork tables in the database. Check that
- your web-server user exists in the database, and that it has permissions
- to the tables.
-
-* pwclient fails for actions that require authentication, but a username
- and password is given int ~/.pwclient rc. Server reports "No authentication
- credentials given".
-
- - if you're using the FastCGI interface to apache, you'll need the
- '-pass-header Authorization' option to the FastCGIExternalServer
- configuration directive.
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
new file mode 100644
index 0000000..d7d7ac2
--- /dev/null
+++ b/docs/INSTALL.md
@@ -0,0 +1,279 @@
+# Deploying Patchwork
+
+Patchwork uses the django framework - there is some background on deploying
+django applications here:
+
+ http://www.djangobook.com/en/2.0/chapter12/
+
+You'll need the following (applications used for patchwork development are
+in brackets):
+
+ * A python interpreter
+ * django >= 1.5
+ * A webserver (apache)
+ * mod_python or flup
+ * A database server (postgresql, mysql)
+ * relevant python modules for the database server (e.g: python-mysqldb)
+
+## Database setup
+
+At present, I've tested with PostgreSQL and (to a lesser extent) MySQL
+database servers. If you have any (positive or negative) experiences with
+either, email me.
+
+For the following commands, a `$` prefix signifies that the command should be
+entered at your shell prompt, and a `>` prefix signifies the commant-line
+client for your sql server (`psql` or `mysql`).
+
+Create a database for the system, add accounts for two system users: the
+web user (the user that your web server runs as) and the mail user (the user
+that your mail server runs as). On Ubuntu these are `www-data` and `nobody`,respectively.
+
+As an alternative, you can use password-based login and a single database
+account. This is described further down.
+
+### Create Required Databases and Users
+
+#### PostgreSQL (ident-based):
+
+ $ createdb patchwork
+ $ createuser www-data
+ $ createuser nobody
+
+ - postgres uses the standard UNIX authentication, so these users
+ will only be accessible for processes running as the same username.
+ This means that no passwords need to be set.
+
+#### PostgreSQL (password-based)
+
+ $ createuser -PE patchwork
+ $ createdb -O patchwork patchwork
+
+#### MySQL
+
+ $ mysql
+ > CREATE DATABASE 'patchwork' CHARACTER SET utf8;
+ > CREATE USER 'www-data'@'localhost' IDENTIFIED BY '<password>';
+ > CREATE USER 'nobody'@'localhost' IDENTIFIED BY '<password>';
+
+### Configure `settings.py`
+
+Once that is done, you need to tell Django about the new Database
+settings, using `local_settings.py` (see below) to override the defaults
+in `settings.py`. For PostgreSQL:
+
+ DATABASES = {
+ 'default': {
+ 'ENGINE': 'django.db.backends.postgresql_psycopg2',
+ 'HOST': 'localhost',
+ 'PORT': '',
+ 'USER': 'patchwork',
+ 'PASSWORD': 'my_secret_password',
+ 'NAME': 'patchwork',
+ 'TEST_CHARSET': 'utf8',
+ },
+ }
+
+**NOTE:** `TEST_CHARSET` is used when creating tables for the test suite.
+Without it, tests checking for the correct handling of non-ASCII characters
+fail.
+
+For MySQL:
+
+ DATABASES = {
+ 'default': {
+ 'ENGINE': 'django.db.backends.mysql',
+ 'HOST': 'localhost',
+ 'PORT': '',
+ 'USER': 'patchwork',
+ 'PASSWORD': 'my_secret_password',
+ 'NAME': 'patchwork',
+ },
+ }
+
+## Django Setup
+
+Set up some initial directories in the patchwork base directory:
+
+ mkdir -p lib/packages lib/python
+
+`lib/packages` is for stuff we'll download, `lib/python` is to add
+to our Python path. We'll symlink Python modules into `lib/python`.
+
+At the time of release, patchwork depends on Django version 1.5 or
+later. Your distro probably provides this. If not, install it manually:
+
+ cd lib/packages
+ git clone https://github.com/django/django.git -b stable/1.5.x
+ cd ../python
+ ln -s ../packages/django/django ./django
+
+The `settings.py` file contains default settings for patchwork, you'll
+need to configure settings for your own setup.
+
+Rather than edit `settings.py`, create a file `local_settings.py`, and
+override or add settings as necessary. You'll need to define the following:
+
+ SECRET_KEY
+ ADMINS
+ TIME_ZONE
+ LANGUAGE_CODE
+ DEFAULT_FROM_EMAIL
+ NOTIFICATION_FROM_EMAIL
+
+You can generate the `SECRET_KEY` with the following python code:
+
+ import string, random
+ chars = string.letters + string.digits + string.punctuation
+ print repr("".join([random.choice(chars) for i in range(0,50)]))
+
+If you wish to enable the `XML-RPC` interface, add the following to
+your `local_settings.py` file:
+
+ ENABLE_XMLRPC = True
+
+Then, get patchwork to create its tables in your configured database:
+
+ cd apps/
+ PYTHONPATH=../lib/python ./manage.py syncdb
+
+And add privileges for your mail and web users. This is only needed if
+you use the ident-based approach. If you use password-based database
+authentication, you can skip this step.
+
+For Postgresql:
+ psql -f lib/sql/grant-all.postgres.sql patchwork
+
+For MySQL:
+ mysql patchwork < lib/sql/grant-all.mysql.sql
+
+## Apache Setup
+
+Example apache configuration files are in `lib/apache2/`.
+
+### wsgi
+
+django has built-in support for WSGI, which supersedes the fastcgi
+handler. It is thus the preferred method to run patchwork.
+
+The necessary configuration for Apache2 may be found in
+
+ lib/apache2/patchwork.wsgi.conf.
+
+You will need to install/enable mod_wsgi for this to work:
+
+ a2enmod wsgi
+ apache2ctl restart
+
+### mod_python
+
+An example apache configuration file for mod_python is in:
+
+ lib/apache2/patchwork.mod_python.conf
+
+However, mod_python and mod_php may not work well together. So, if your
+web server is used for serving php files, the fastcgi method may suit
+instead.
+
+### fastcgi
+
+Django has built-in support for fastcgi, which requires the `flup` Python
+module. An example configuration is in:
+
+ lib/apache2/patchwork.fastcgi.conf
+
+This also requires the `mod_rewrite` Apache module to be loaded.
+
+Once you have Apache set up, you can start the fastcgi server with:
+
+ cd /srv/patchwork/apps
+ ./manage.py runfcgi method=prefork \
+ socket=/srv/patchwork/var/fcgi.sock \
+ pidfile=/srv/patchwork/var/fcgi.pid
+
+## Configure patchwork
+
+Now, you should be able to administer patchwork, by visiting the
+URL:
+
+ http://your-host/admin/
+
+You'll probably want to do the following:
+
+* Set up your projects
+* Configure your website address (in the Sites) section of the admin
+
+## Subscribe a Local Address to the Mailing List
+
+You will need an email address for patchwork to receive email on - for
+example - `patchwork at your-host`, and this address will need to be subscribed
+to the list. Depending on the mailing list, you will probably need to confirm
+the subscription - temporarily direct the alias to yourself to do this.
+
+## Setup your MTA to Deliver Mail to the Parsemail Script
+
+Your MTA will need to deliver mail to the parsemail script in the email/
+directory. (Note, do not use the `parsemail.py` script directly). Something
+like this in /etc/aliases is suitable for postfix:
+
+ patchwork: "|/srv/patchwork/apps/patchwork/bin/parsemail.sh"
+
+You may need to customise the `parsemail.sh` script if you haven't installed
+patchwork in `/srv/patchwork`.
+
+Test that you can deliver a patch to this script:
+
+ sudo -u nobody /srv/patchwork/apps/patchwork/bin/parsemail.sh < mail
+
+## Set up the patchwork cron script
+
+Patchwork uses a cron script to clean up expired registrations, and send
+notifications of patch changes (for projects with this enabled).
+
+Something like this in your crontab should work:
+
+ # m h dom mon dow command
+ PYTHONPATH=apps:.
+ DJANGO_SETTINGS_MODULE=settings
+ */10 * * * * cd patchwork; python apps/patchwork/bin/patchwork-cron.py
+
+The frequency should be the same as the `NOTIFICATION_DELAY_MINUTES`
+setting, which defaults to 10 minutes.
+
+## (Optional) Configure your VCS to Automatically Update Patches
+
+The tools directory of the patchwork distribution contains a file
+named `post-receive.hook` which is a sample git hook that can be
+used to automatically update patches to the `Accepted` state when
+corresponding comits are pushed via git.
+
+To install this hook, simply copy it to the `.git/hooks` directory on
+your server, name it `post-receive`, and make it executable.
+
+This sample hook has support to update patches to different states
+depending on which branch is being pushed to. See the `STATE_MAP`
+setting in that file.
+
+If you are using a system other than git, you can likely write a
+similar hook using `pwclient` to update patch state. If you do write
+one, please contribute it.
+
+Some errors:
+
+* `__init__() got an unexpected keyword argument 'max_length'`
+ You're running an old version of django. If your distribution doesn't
+ provide a newer version, just download and extract django into
+ `lib/python/django` as described [above](#Django Setup)
+
+* `ERROR: permission denied for relation patchwork_...`
+ The user that patchwork is running as (ie, the user of the web-server)
+ doesn't have access to the patchwork tables in the database. Check that
+ your web-server user exists in the database, and that it has permissions
+ to the tables.
+
+* pwclient fails for actions that require authentication, but a username
+and password is given int ~/.pwclient rc. Server reports "No authentication
+credentials given".
+ if you're using the FastCGI interface to apache, you'll need the
+ `-pass-header Authorization` option to the FastCGIExternalServer
+ configuration directive.
--
1.9.3
More information about the Patchwork
mailing list