diff options
author | Stephen Finucane <stephen.finucane@intel.com> | 2016-03-25 21:30:50 +0000 |
---|---|---|
committer | Stephen Finucane <stephen.finucane@intel.com> | 2016-03-29 11:28:44 +0100 |
commit | 8320efcd6412050ddc12f6475a43c19ecd92b14f (patch) | |
tree | 66b6a5958172b65d819e062759973582c1b72c89 /docs | |
parent | 144558ef0b38a7f488afc723b049e48bf0c08da5 (diff) | |
download | patchwork-8320efcd6412050ddc12f6475a43c19ecd92b14f.tar patchwork-8320efcd6412050ddc12f6475a43c19ecd92b14f.tar.gz |
docs: Refer to 'Patchwork' consistently
The docs referred to both 'patchwork' and 'Patchwork'. Use the title
case variant consistently.
Signed-off-by: Stephen Finucane <stephen.finucane@intel.com>
Diffstat (limited to 'docs')
-rw-r--r-- | docs/api.md | 6 | ||||
-rw-r--r-- | docs/contributing.md | 6 | ||||
-rw-r--r-- | docs/deployment.md | 44 | ||||
-rw-r--r-- | docs/development.md | 40 | ||||
-rw-r--r-- | docs/index.md | 30 | ||||
-rw-r--r-- | docs/releasing.md | 6 | ||||
-rw-r--r-- | docs/upgrading.md | 32 |
7 files changed, 82 insertions, 82 deletions
diff --git a/docs/api.md b/docs/api.md index 04026d8..b7164a5 100644 --- a/docs/api.md +++ b/docs/api.md @@ -13,16 +13,16 @@ You can find this at the following URL: http://patchwork.example.com/xmlrpc/ -Where `patchwork.example.com` refers to the URL of your patchwork instance. +Where `patchwork.example.com` refers to the URL of your Patchwork instance. -**NOTE:** Automatic documentation generation for the patchwork API was +**NOTE:** Automatic documentation generation for the Patchwork API was introduced in Patchwork v1.1. Prior versions of Patchwork do not offer this functionality. ## Developing Your Own Client You need to connect to the server. Some methods require authentication (via -HTTP Basic Auth) while others do not. Authentication uses your patchwork +HTTP Basic Auth) while others do not. Authentication uses your Patchwork account and the on-server documention will indicate where it is necessary. We will only cover the unauthenticated method here for brevity - please consult the [`xmlrpclib`] documentation for more detailed examples: diff --git a/docs/contributing.md b/docs/contributing.md index 1e61b7f..fc70301 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -13,12 +13,12 @@ below for more information on usage of this tool. ## Testing -patchwork includes a [tox][ref-tox] script to automate testing. This requires +Patchwork includes a [tox][ref-tox] script to automate testing. This requires a functional database and some Python requirements like `tox`. Please refer to the [development guide][doc-development] for information on how to configure these. -Assuming these requirements are met, actually testing patchwork is quite easy +Assuming these requirements are met, actually testing Patchwork is quite easy to do. To start, you can show the default targets like so: $ tox --list @@ -36,7 +36,7 @@ command: $ tox -e py27-django18 patchwork.tests.SubjectCleanUpTest -Because patchwork support multiple versions of Django, it's very important +Because Patchwork support multiple versions of Django, it's very important that you test against all supported versions. When run without argument, tox will do this: diff --git a/docs/deployment.md b/docs/deployment.md index f53d27f..e8dcd0f 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -1,19 +1,19 @@ # Deployment -This document describes the necessary steps to configure patchwork in a +This document describes the necessary steps to configure Patchwork in a production environment. This requires a significantly "harder" deployment than -the one used for development. If you are interested in developing patchwork, +the one used for development. If you are interested in developing Patchwork, please refer to [the development guide][doc-development] instead. -This document describes a two-node installation of patchwork, consisting of +This document describes a two-node installation of Patchwork, consisting of a database sever and an application server. It should be possible to combine -these machines for smaller patchwork instances. It should also be possible to +these machines for smaller Patchwork instances. It should also be possible to configure high availability deployment through use of additional database and application machines, though this is out of the scope of this document. ## Deployment Guides, Provisioning Tools and Platform-as-a-Service -Before continuing, it's worth noting that patchwork is a Django application. +Before continuing, it's worth noting that Patchwork is a Django application. With the exception of the handling of incoming mail (described below), it can be deployed like any other Django application. This means there are tens, if not hundreds, of existing articles and blogs detailing how to deploy an @@ -46,8 +46,8 @@ For the purpose of this guide, we will assume the following machines: | application | 10.1.1.2 | We will use the database server to, ostensibly enough, host the database for -the patchwork instance. The application server, on the other hand, will host -the patchwork instance along with the required reverse proxy and WSGI HTTP +the Patchwork instance. The application server, on the other hand, will host +the Patchwork instance along with the required reverse proxy and WSGI HTTP servers. We expect a Ubuntu 15.04 installation on each of these hosts: commands, @@ -71,7 +71,7 @@ should be exported on all systems: <dt>PW_DB_NAME=patchwork</dt> <dd>Name of the database</dd> <dt>PW_DB_USER=www-data</dt> - <dd>Username that the patchwork app will access the database with</dd> + <dd>Username that the Patchwork app will access the database with</dd> </dl> ## Database @@ -91,7 +91,7 @@ different RDBMS. Install the required packages. ### Configure Database PostgreSQL created a user account called `postgres`; you will need to run -commands as this user. Use this account to create the database that patchwork +commands as this user. Use this account to create the database that Patchwork will use, using the credentials we configured earlier. $ sudo -u postgres createdb $PW_DB_NAME @@ -109,7 +109,7 @@ These steps should be run on the application server. ### Install Packages -The first requirement is patchwork itself. It can be downloaded like so: +The first requirement is Patchwork itself. It can be downloaded like so: $ wget https://github.com/getpatchwork/patchwork/archive/v1.1.0.tar.gz @@ -124,7 +124,7 @@ that people may be able to view your code over the Web. This is a security risk. Next we require Python. If not already installed, then you should do so now. -patchwork supports both Python 2.7 and Python 3.3+, though we would suggest +Patchwork supports both Python 2.7 and Python 3.3+, though we would suggest using the latter to ease future upgrades: $ sudo apt-get install python3 # or 'python' if using Python 2.7 @@ -141,11 +141,11 @@ corresponding distro package for each of these requirements. For example: **NOTE:** The [pkgs.org][ref-pkgs] website provides a great reference for identifying the name of these dependencies. -### Configure patchwork +### Configure Patchwork You will also need to configure a [settings][ref-django-settings] file for Django. A sample settings file is provided that defines default settings for -patchwork. You'll need to configure settings for your own setup and save this +Patchwork. You'll need to configure settings for your own setup and save this as `production.py`. $ cp patchwork/settings/production.example.py \ @@ -248,7 +248,7 @@ These steps should be run on the application server. ### Install Packages -We will use nginx and uWSGI to deploy patchwork, acting as reverse proxy server +We will use nginx and uWSGI to deploy Patchwork, acting as reverse proxy server and WSGI HTTP server respectively. Other options are available, such as Apache+mod_wsgi or nginx+Gunicorn. While we don't document these, sample configuration files for the former case are provided in `lib/apache2/`. @@ -258,7 +258,7 @@ configuration files for the former case are provided in `lib/apache2/`. ### Configure nginx and uWSGI Configuration files for nginx and uWSGI are provided in the `lib` subdirectory -of the patchwork source code. These can be modified as necessary, but for now +of the Patchwork source code. These can be modified as necessary, but for now we will simply copy them. First, let's load the provided configuration for nginx: @@ -321,7 +321,7 @@ Next up, restart the nginx service: $ sudo systemctl nginx restart $ sudo systemctl nginx status -patchwork uses a cron script to clean up expired registrations and send +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. @@ -338,7 +338,7 @@ website address (in the Sites section of the admin console, found at `/admin`). ## Incoming Email -patchwork is designed to parse incoming mails which means you need an address +Patchwork is designed to parse incoming mails which means you need an address to receive email at. This is a problem that has been solved for many webapps, thus there are many ways to go about this. Some of these ways are discussed below. @@ -347,9 +347,9 @@ below. The most flexible option is to configure our own mail transfer agent (MTA) and Postfix is as good a choice as any. While we don't cover setting up Postfix -here (it's complicated and there are many guides already available), patchwork +here (it's complicated and there are many guides already available), Patchwork does include a script to take received mails and create the relevant entries -in patchwork for you. To use this, you should configure your system to forward +in Patchwork for you. To use this, you should configure your system to forward all emails to a given localpart (the bit before the `@`) to this script. Using the `patchwork` localpart (e.g. `patchwork@example.com`) you can do this like so: @@ -378,7 +378,7 @@ One could also use an email account provided by a run-of-the-mill email provider and retrieve mail using IMAP or POP3. This may be suitable for low-volume mailing lists but be warned: this will introduce a significant lag between when a patch is submitted to a mailing list and when it appears in -patchwork. +Patchwork. ### Use a Email-as-a-Service Provider @@ -388,14 +388,14 @@ are a variety of web services available that offer "Email-as-as-Service". These services typically convert received emails into HTTP POST requests to your endpoint of choice, allowing you to sidestep configuration issues. We don't cover this here, but a simple wrapper script coupled with one of these -services can be more than to get email into patchwork. +services can be more than to get email into Patchwork. You can also create such as service yourself using a PaaS provider that supports incoming mail and writing a little web app. ## (Optional) Configure your VCS to Automatically Update Patches -The `tools` directory of the patchwork distribution contains a file named +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 commits are pushed via git. diff --git a/docs/development.md b/docs/development.md index ace9e59..ddfbcb4 100644 --- a/docs/development.md +++ b/docs/development.md @@ -1,7 +1,7 @@ # Development -This document describes the necessary steps to configure patchwork in a -development environment. If you are interested in deploying patchwork in a +This document describes the necessary steps to configure Patchwork in a +development environment. If you are interested in deploying Patchwork in a production environment, please refer to [the deployment guide][doc-deployment] instead. @@ -13,8 +13,8 @@ The latest version of Patchwork is available with git. To download: ## Vagrant-Based Installation -patchwork provides a Vagrantfile that can be used to quickly configure -patchwork in a delopment environment. Like any Vagrant VM, you can start this +Patchwork provides a Vagrantfile that can be used to quickly configure +Patchwork in a delopment environment. Like any Vagrant VM, you can start this using the `vagrant up` command: $ cd patchwork # the path to the repo you cloned above @@ -27,7 +27,7 @@ Alternatively, manual installation steps are provided below. ## Install Required Packages -There are a number of different requirements for developing patchwork: +There are a number of different requirements for developing Patchwork: * Python and libraries * A supported RDBMS @@ -44,15 +44,15 @@ on many installations, though they can also be installed manually using the It's a good idea to use [virtual environments][ref-venv] to develop Python software. Virtual environments are "instances" of your system Python without any of the additional Python packages installed. They are useful to develop and -possibly deploy patchwork against a "well known" set of dependencies, but they -can also be used to test patchwork against several versions of Django. +possibly deploy Patchwork against a "well known" set of dependencies, but they +can also be used to test Patchwork against several versions of Django. If you do not have `virtualenv` installed then you should install it now. This can be installed using the `python-virtualenv` or `python3-virtualenv` packages. Alternatively you can install these using `pip`. It is also helpful to install [`tox`][ref-tox] which is used for running tests -in patchwork. This can be installed using the `python-tox` or `python3-tox` +in Patchwork. This can be installed using the `python-tox` or `python3-tox` packages, or via `pip`. ### Database Requirements @@ -64,16 +64,16 @@ on Debian-based Debian-based distros like Ubuntu and `mysql-devel` or `postgresql-devel` on RHEL-based distros. **NOTE:** While Django provides support for -[multiple database backends][ref-django-db], patchwork itself is only tested +[multiple database backends][ref-django-db], Patchwork itself is only tested against MySQL/MariaDB and PostgreSQL. Should you wish to use a different backend, ensure you validate this first (and perhaps [upstream][doc-contributing] any changes you may find necessary). -**NOTE:** You may be tempted to use SQLite to develop patchwork. We'd advise +**NOTE:** You may be tempted to use SQLite to develop Patchwork. We'd advise against doing this. SQLite supports a subset of the functionality of "full" RDBMS like MySQL: for example, case-sensitive matching of Unicode [is not supported][ref-sqlite-utf8]. You will find some tests provided by -patchwork fail and some patches you develop may fail in production due to these +Patchwork fail and some patches you develop may fail in production due to these differences. ### Example Installations @@ -95,7 +95,7 @@ the above command. ## Configure Virtual Environment -**NOTE:** If you are interested in simply [testing patchwork][doc-testing], +**NOTE:** If you are interested in simply [testing Patchwork][doc-testing], many of the the below steps are not required. tox will automatically install dependencies and use virtual environments when testing. @@ -113,7 +113,7 @@ Now install the packages. Patchwork provides three requirements files. * `requirements-dev.txt`: Packages required to configure a development environment -* `requirements-prod.txt`: Packages required for deploying patchwork in +* `requirements-prod.txt`: Packages required for deploying Patchwork in production * `requirements-test.txt`: Packages required to run tests @@ -123,7 +123,7 @@ We're going to install the first of these, which can be done like so: (.venv)$ pip install -r requirements-dev.txt **NOTE:** Once configured this does not need to be done again *unless* the -requirements change, e.g. patchwork requires an updated version of Django. +requirements change, e.g. Patchwork requires an updated version of Django. ## Initialize the Database @@ -157,7 +157,7 @@ hardcoded and change the value of `DJANGO_SETTINGS_MODULE` as described below. ## Load Initial Data Before continuing, we need to tell Django where it can find our configuration. -patchwork provides a default development `settings.py` file for this purpose. +Patchwork provides a default development `settings.py` file for this purpose. To use this, export the `DJANGO_SETTINGS_MODULE` environment variable as described below: @@ -171,10 +171,10 @@ the `migrate` command of the `manage.py` executable: (.venv)$ ./manage.py migrate -Next, you should load the initial fixtures into patchwork. These initial +Next, you should load the initial fixtures into Patchwork. These initial fixtures provide. -* `default_tags.xml`: The tags that patchwork will extract from mails. +* `default_tags.xml`: The tags that Patchwork will extract from mails. Examples: `Acked-By`, `Reviewed-By` * `default_states.xml`: The states that a patch can be in. Examples: `Accepted`, `Rejected` @@ -204,12 +204,12 @@ tool. You can do this like so: Where `mm_user` and `mm_pass` are the username and password you have registered with on the Mailman instance found at `mm_host`. -**NOTE:** We provide instructions for downloading archives from the patchwork +**NOTE:** We provide instructions for downloading archives from the Patchwork mailing list, but almost any instance of Mailman will allow downloading of archives as seen above; simply change the `pw_url` variable defined. You can find more informations about this [here][ref-mman-bulk]. -Load these archives into patchwork. Depending on the size of the downloaded +Load these archives into Patchwork. Depending on the size of the downloaded archives this may take some time: (.venv)$ PYTHONPATH=. ./patchwork/bin/parsearchive.py \ @@ -231,7 +231,7 @@ script again. ## Django Debug Toolbar -patchwork installs and enables the 'Django Debug Toolbar' by default. However, +Patchwork installs and enables the 'Django Debug Toolbar' by default. However, by default this is only displayed if you are developing on localhost. If developing on a different machine, you should configure an SSH tunnel such that, for example, `localhost:8000` points to `[DEV_MACHINE_IP]:8000`. diff --git a/docs/index.md b/docs/index.md index 6c9aa5a..601ab12 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,6 @@ -# patchwork +# Patchwork -patchwork is a patch tracking system for community-based projects. It is +Patchwork is a patch tracking system for community-based projects. It is intended to make the patch management process easier for both the project's contributors and maintainers, leaving time for the more important (and more interesting) stuff. @@ -11,7 +11,7 @@ to the patch page too. The project's maintainer can then scan through the list of patches, marking each with a certain state, such as Accepted, Rejected or Under Review. Old patches can be sent to the archive or deleted. -Currently, patchwork is being used for a number of open-source projects, mostly +Currently, Patchwork is being used for a number of open-source projects, mostly subsystems of the Linux kernel. Although Patchwork has been developed with the kernel workflow in mind, the aim is to be flexible enough to suit the majority of community projects. @@ -26,41 +26,41 @@ Patchwork is distributed under the [GNU General Public License][ref-gpl]. # Design -## patchwork should supplement mailing lists, not replace them +## Patchwork should supplement mailing lists, not replace them Patchwork isn't intended to replace a community mailing list; that's why you -can't comment on a patch in patchwork. If this were the case, then there would +can't comment on a patch in Patchwork. If this were the case, then there would be two forums of discussion on patches, which fragments the patch review -process. Developers who don't use patchwork would get left out of the +process. Developers who don't use Patchwork would get left out of the discussion. -However, a future development item for patchwork is to facilitate on-list +However, a future development item for Patchwork is to facilitate on-list commenting, by providing a "send a reply to the list" feature for logged-in users. -## Don't pollute the project's changelogs with patchwork poop +## Don't pollute the project's changelogs with Patchwork poop -A project's changelogs are valuable - we don't want to add patchwork-specific +A project's changelogs are valuable - we don't want to add Patchwork-specific metadata. -## patchwork users shouldn't require a specific version control system +## Patchwork users shouldn't require a specific version control system Not everyone uses git for kernel development, and not everyone uses git for -patchwork-tracked projects. +Patchwork-tracked projects. -It's still possible to hook other programs into patchwork, using the pwclient -command-line client for patchwork, or directly to the XML RPC interface. +It's still possible to hook other programs into Patchwork, using the pwclient +command-line client for Patchwork, or directly to the XML RPC interface. # Getting Started You should check out the [deployment][doc-deployment] and [development][doc-development] guides for information on how to configure -patchwork for production and development environments, respectively. +Patchwork for production and development environments, respectively. # Support All questions and contributions should be sent to the -[patchwork mailing list][ref-pw-ml]. +[Patchwork mailing list][ref-pw-ml]. [ref-gpl]: http://www.gnu.org/licenses/gpl-2.0.html [ref-pw-ml]: https://ozlabs.org/mailman/listinfo/patchwork diff --git a/docs/releasing.md b/docs/releasing.md index d8e005d..5974da2 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -2,7 +2,7 @@ ## Versioning -Since version 1.0, patchwork has implemented a version of +Since version 1.0, Patchwork has implemented a version of [Semantic Versioning][ref-semver]. To summarise, releases take the format **MAJOR.MINOR.PATCH** (or just **MAJOR.MINOR**). We increment: @@ -22,11 +22,11 @@ There is no cadence for releases: they are made available as necessary. Typically all development should occur on `master`. While we will backport bugfixes and security updates, we will not backport any new features. This -is to ensure stability for users of these versions of patchwork. +is to ensure stability for users of these versions of Patchwork. ## Release Checklist * Documentation has been updated with latest release version * Documentation references latest supported version of Django -[ref-semver]: http://semver.org/
\ No newline at end of file +[ref-semver]: http://semver.org/ diff --git a/docs/upgrading.md b/docs/upgrading.md index 5f97950..453ae94 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -1,10 +1,10 @@ # Upgrading **NOTE:** This document provides some general tips and tricks that one can use -when upgrading an existing, production installation of patchwork. If you are +when upgrading an existing, production installation of Patchwork. If you are interested in the specific changes between each release, please refer to the [`UPGRADING` document][gh-upgrading] instead. If this is your first time -installing patchwork. please refer to the +installing Patchwork. please refer to the [installation guide][doc-installation] instead. ## Before You Start @@ -13,14 +13,14 @@ Before doing anything, always **backup your data**. This generally means backing up your database, but it might also be a good idea to backup your environment in case you encounter issues during the upgrade process. -While patchwork won't explicity prevent it, it's generally wise to avoid +While Patchwork won't explicity prevent it, it's generally wise to avoid upgrades spanning multiple releases in one go. An iterative upgrade approach will provide an easier, if slower, upgrade process. ## Identify Changed Scripts, Requirements, etc. The `UPGRADING` document provides a comprehensive listing of all -backwards-incompatible changes that occur between releases of patchwork. +backwards-incompatible changes that occur between releases of Patchwork. Examples of such changes include: * Moved/removed scripts and files @@ -32,7 +32,7 @@ may have, such as systemd/upstart scripts, are modified accordingly. ## Understand What Requirements Have Changed -New versions of patchwork can often require additional or updated version of +New versions of Patchwork can often require additional or updated version of dependencies, e.g. newer versions of Django. It is important that you understand these requirements and can fulfil them. This is particularly true for users relying on distro-provided packages, who may have to deal with older @@ -42,7 +42,7 @@ you can also diff the `requirements.txt` files in each release for comparison. ## Collect Static Files -New versions of patchwork generally contain changes to the additional files +New versions of Patchwork generally contain changes to the additional files like images, CSS and JavaScript. To do this, run the `collectstatic` management commands: @@ -52,7 +52,7 @@ management commands: Migrations of the database can be tricky. Prior to [`v1.0.0`][gh-v1], database migrations were provided by way of manual, SQL migration scripts. After this -release, patchwork moved to support [Django migrations][ref-django-migrate]. +release, Patchwork moved to support [Django migrations][ref-django-migrate]. If you are upgrading from `v1.0.0` or later, it is likely that you can rely entirely on the later to bring your database up-to-date. This can be done like so: @@ -64,7 +64,7 @@ the provided SQL migrations or provide your own: * You are using Django < 1.6 - patchwork supports Django 1.6. However, Django Migrations was added in 1.7 + Patchwork supports Django 1.6. However, Django Migrations was added in 1.7 and is [not available for previous versions][ref-south2]. As such, you must continue to use manual migrations or upgrade your version of Django. For many of the migrations, this can be done automatically: @@ -75,13 +75,13 @@ the provided SQL migrations or provide your own: however, this will fail. In this cases, these migrations will need to be handwritten. -* You are using Django > 1.6, but upgrading from patchwork < 1.0.0 +* You are using Django > 1.6, but upgrading from Patchwork < 1.0.0 - patchwork only started providing migrations in `v1.0.0`. SQL migrations are + Patchwork only started providing migrations in `v1.0.0`. SQL migrations are provided for versions prior to this and must be applied to get the database to the "initial" state that Django migrations expects. -* You have diverged from upstream patchwork +* You have diverged from upstream Patchwork If you have applied custom patches that change the database models, the database in an "inconsistent state" and the provided migrations will likely @@ -89,7 +89,7 @@ the provided SQL migrations or provide your own: Steps to handle the latter two of these are described below. -### Upgrading a pre-v1.0.0 patchwork instance +### Upgrading a pre-v1.0.0 Patchwork instance The process for this type of upgrade is quite simple: upgrade using manual SQL upgrades until better options become available. As such, you should apply @@ -97,11 +97,11 @@ all unapplied SQL migrations that are not duplicated by Django migrations. Once such duplication occurs, rely on the Django migrations only and continue to do so going forward. -### Upgrading a "diverged" patchwork instance +### Upgrading a "diverged" Patchwork instance This type of upgrade is a little trickier. There are two options you can take: -1. Bring your patchwork instance back in sync with upstream +1. Bring your Patchwork instance back in sync with upstream 2. Provide your own migrations The former option is particularly suitable if you decide to upstream your @@ -120,12 +120,12 @@ possible to return to using upstream code rather than maintaining a fork. The latter option is best chosen if you wish to retain the aforementioned fork. How you do this depends on the extensiveness of your changes, but getting the -latest version of patchwork, deleting the provided migrations, applying any +latest version of Patchwork, deleting the provided migrations, applying any patches you may have and regenerating the migrations seems like the best option. **NOTE**: To prevent the latter case above from occuring, we'd ask that you -submit any patches you may have to the upstream patchwork so that the wider +submit any patches you may have to the upstream Patchwork so that the wider community can benefit from this new functionality. Please see [the contributing document][doc-contributing] for more informtion on this process. |