diff options
Diffstat (limited to 'docs/usage')
| -rw-r--r-- | docs/usage/delegation.md | 45 | ||||
| -rw-r--r-- | docs/usage/headers.md | 34 | ||||
| -rw-r--r-- | docs/usage/overview.md | 313 | ||||
| -rw-r--r-- | docs/usage/rest.md | 56 | ||||
| -rw-r--r-- | docs/usage/xmlrpc.md | 39 |
5 files changed, 0 insertions, 487 deletions
diff --git a/docs/usage/delegation.md b/docs/usage/delegation.md deleted file mode 100644 index 7e86cfb..0000000 --- a/docs/usage/delegation.md +++ /dev/null @@ -1,45 +0,0 @@ -# Autodelegation - -Autodelegation allows patches to be automatically delegated to a user based on -the files modified by the patch. To do this, a number of rules can be -configured in the project administration page. This can usually be found at -`/admin/patchwork/project/<project_id>/change`. - -**NOTE:** Autodelegation can only be configured by Patchwork administrators, -i.e. those that can access the 'admin' panel. If you require configuration of -autodelegation rules on a local instance, contact your Patchwork administrator. - -In this section there are the following fields: - -- User - - The patchwork user that should be autodelegated to the patch - -- Priority - - The priority of the rule relative to other patches. Higher values indicate - higher priority. If two rules have the same priority, ordering will be - based on the path. - -- Path - - A path in [fnmatch](https://docs.python.org/2/library/fnmatch.html) format. - The fnmatch library allows for limited, Unix shell-style wildcarding. - Filenames are extracted from patch lines beginning with `--- ` or `+++ `. - Note that for projects using Git or Mercurial, the tools these VCS provide - for producing patches are prefixed with `a` or `b`. You should account for - this in your path. For example, to match the path `patchwork/views` - (relative to the top of a Git repo) your pattern should be: - - ?/patchwork/views/* - - It is also possible to use relative paths, such as: - - */manage.py - - For projects using other VCSs like Subversion can simply use a bare path: - - patchwork/views/* - -Rules are configured by setting the above fields and saving the rules. These -rules will be applied at patch parse time. diff --git a/docs/usage/headers.md b/docs/usage/headers.md deleted file mode 100644 index dc87397..0000000 --- a/docs/usage/headers.md +++ /dev/null @@ -1,34 +0,0 @@ -# Hint Headers - -Patchwork provides a number of special email headers to control how a patch is -handled when it is received. The examples provided below use `git-send-email`, -but custom headers can also be set when using tools like `mutt`. - -## `X-Patchwork-Ignore` - -Valid values: * - -When set, the mere presence of this header will ensure the provided email is -not parsed by Patchwork. For example: - - $ git send-email --add-header="X-Patchwork-Ignore: test" master - -## `X-Patchwork-Delegate` - -Valid values: An email address associated with a Patchwork user - -If set and valid, the user corresponding to the provided email address will be -assigned as the delegate of any patch parsed. If invalid, it will be ignored. -For example: - - $ git send-email --add-header="X-Patchwork-Delegate: a@example.com" master - -## `X-Patchwork-State` - -Valid values: Varies between deployments. This can usually be one of -"Accepted", "Rejected", "RFC" or "Awaiting Upstream", among others. - -If set and valid, the state provided will be assigned as the state of any patch -parsed. If invalid, it will be ignored. For example: - - $ git send-email --add-header="X-Patchwork-State: RFC" master diff --git a/docs/usage/overview.md b/docs/usage/overview.md deleted file mode 100644 index de808c8..0000000 --- a/docs/usage/overview.md +++ /dev/null @@ -1,313 +0,0 @@ -# Overview - -The key concepts or models of Patchwork are outlined below. - -## Projects - -Projects typically represent a software project or sub-project. A Patchwork -server can host multiple projects. Each project can have multiple maintainers. -Projects usually have a 1:1 mapping with a mailing list, though it's also -possible to have multiple projects in the same list using the subject as -filter. Patches, cover letters, and series are all associated with a single -project. - -## People - -People are anyone who has submitted a patch, cover letter, or comment to a -Patchwork instance. - -## Users - -Users are anyone who has created an account on a given Patchwork instance. - -### Standard Users - -A standard user can associate multiple email addresses with their user account, -create bundles and store TODO lists. - -### Maintainers - -Maintainers are a special type of user that with permissions to do certain -operations that regular Patchwork users can't. Patchwork maintainers usually -have a 1:1 mapping with a project's code maintainers though this is not -necessary. - -The operations that a maintainer can invoke include: - -- Change the state of a patch -- Archive a patch -- Delegate a patch, or be delegated a patch - -## Submissions - -Patchwork captures three types of mail to mailing lists: patches, cover -letters, and replies to either patches or cover letters, a.k.a. comments. Any -mail that does not fit one of these categories is ignored. - -### Patches - -Patches are the central object in Patchwork structure. A patch contains both a -diff and some metadata, such as the name, the description, the author, the -version of the patch etc. Patchwork stores not only the patch itself but also -various metadata associated with the email that the patch was parsed from, such -as the message headers or the date the message itself was received. - -### Cover Letters - -Cover letters provide a way to offer a "big picture" overview of a series of -patches. When using Git, these mails can be recognised by way of their `0/N` -subject prefix, e.g. `[00/11] A sample series`. Like patches, Patchwork stores -not only the various aspects of the cover letter itself, such as the name and -body of the cover letter, but also various metadata associated with the email -that the cover letter was parsed from. - -### Comments - -Comments are replies to a submission - either a patch or a cover letter. Unlike -a Mail User Agent (MUA) like Gmail, Patchwork does not thread comments. -Instead, every comment is associated with either a patch or a cover letter, and -organized by date. - -## Patch Metadata - -Patchwork allows users to store various metadata against patches. This metadata -is only configurable by a maintainer. - -### States - -States track the state of patch in its lifecycle. States vary from project to -project, but generally a minimum subset of "new", "rejected" and "accepted" -will exist. - -### Delegates - -Delegates are Patchwork users who are responsible for both reviewing a patch -and setting its eventual state in Patchwork. This makes them akin to reviewers -in other tools. Delegation works particularly well for larger projects where -various subsystems, each with their own maintainer(s), can be identified. Only -one delegate can be assigned to a patch. - -**NOTE:** Patchwork supports automatic delegation of patches. Refer to the -[Autodelegation Guide][doc-autodelegation] for more information. - -### Tags - -Tags are specially formatted metadata appended to the foot the body of a patch -or a comment on a patch. Patchwork extracts these tags at parse time and -associates them with the patch. You add extra tags to an email by replying to -the email. The following tags are available on a standard Patchwork install: - -- Acked-by: - - For example: - - Acked-by: Stephen Finucane <stephen@that.guru> - -- Tested-by: - - For example: - - Tested-by: Stephen Finucane <stephen@that.guru> - -- Reviewed-by: - - For example: - - Tested-by: Stephen Finucane <stephen@that.guru> - -The available tags, along with the significance of said tags, varies from -project to project and Patchwork instance to Patchwork instance. The [kernel -project documentation][ref-kernel-submission] provides an overview of the -supported tags for the Linux kernel project. - -### Checks - -Checks store the results of any tests executed (or executing) for a given -patch. This is useful, for example, when using a continuous integration (CI) -system to test patches. Checks have a number of fields associated with them: - -- Context - - A label to discern check from the checks of other testing systems - -- Description - - A brief, optional description of the check - -- Target URL - - A target URL where a user can find information related to this check, such - as test logs. - -- State - - The state of the check. One of: pending, success, warning, fail - -- User - - The user creating the check - -**NOTE:** Checks can only be created through the Patchwork APIs. Refer to the -[API documentation][doc-api] for more information. - -**TODO:** Provide information on building a CI system that reports check -results back to Patchwork. - -## Collections - -Patchwork provides a number of ways to store groups of patches. Some of these -are automatically generated, while others are user-defined. - -### Series - -Series are groups of patches, along with an optional cover letter. Series are -mostly dumb containers, though they also contain some metadata themselves such -as a version (which is inherited by the patches and cover letter) and a count -of the number of patches found in the series. - -### Bundles - -Bundles are custom, user-defined groups of patches. Bundles can be used to keep -patch lists, preserving order, for future inclusion in a tree. There's no -restriction of number of patches and they don't even need to be in the same -project. A single patch also can be part of multiple bundles at the same time. -An example of Bundle usage would be keeping track of the Patches that are ready -for merge to the tree. - -### To-do Lists - -Patchwork users can store a to-do list of patches. - -## Events - -Events are raised whenever patches are created or modified. - -All events have a number of common properties, along with some event-specific -properties: - -<dl> - <dt>category</dt> - <dd>The type of event</dd> - <dt>project<dt> - <dd>The project this event belongs to</dd> - <dt>date</dt> - <dd>When this event was created</dd> -</dl> - -**NOTE:** Checks can only be created and read through the Patchwork APIs. Refer -to the [API documentation][doc-api] for more information. - -### Cover Letter Created - -Sent when a cover letter is created. - -<dl> - <dt>category</dt> - <dd><code>cover-created</code></dd> - <dt>cover<dt> - <dd>Created cover letter</dd> -</dl> - -### Patch Created - -Sent when a patch is created. - -<dl> - <dt>category</dt> - <dd><code>patch-created</code></dd> - <dt>patch<dt> - <dd>Created patch</dd> -</dl> - -### Patch Completed - -Sent when a patch in a series has its dependencies met, or when a patch that is -not in a series is created (since that patch has no dependencies). - -<dl> - <dt>category</dt> - <dd><code>patch-completed</code></dd> - <dt>patch<dt> - <dd>Completed patch</dd> - <dt>series<dt> - <dd>Series from which patch dependencies were extracted, if any</dd> -</dl> - -### Patch Delegated - -Sent when a patch's delegate is changed. - -<dl> - <dt>category</dt> - <dd><code>patch-delegated</code></dd> - <dt>patch<dt> - <dd>Updated patch</dd> - <dt>previous</dt> - <dd>Previous delegate, if any</dd> - <dt>current</dt> - <dd>Current delegate, if any</dd> -</dl> - -### Patch State Changed - -Sent when a patch's state is changed. - -<dl> - <dt>category</dt> - <dd><code>patch-state-changed</code></dd> - <dt>patch<dt> - <dd>Updated patch</dd> - <dt>previous</dt> - <dd>Previous state</dd> - <dt>current</dt> - <dd>Current state</dd> -</dl> - -### Check Created - -Sent when a patch check is created. - -<dl> - <dt>category</dt> - <dd><code>check-created</code></dd> - <dt>check<dt> - <dd>Created check</dd> -</dl> - - -### Series Created - -Sent when a series is created. - -<dl> - <dt>category</dt> - <dd><code>series-created</code></dd> - <dt>series<dt> - <dd>Created series</dd> -</dl> - -### Series Completed - -Sent when a series is completed. - -<dl> - <dt>category</dt> - <dd><code>series-completed</code></dd> - <dt>series<dt> - <dd>Completed series</dd> -</dl> - -### What's Not Exposed - -* Bundles - - We don't expose an "added to bundle" event as it's unlikely that this will - be useful to either users or CI setters. - -* Comments - - Like Bundles, there likely isn't much value in exposing these via the API. - -[doc-api]: rest.md -[doc-autodelegation]: delegation.md -[ref-kernel-submission]: https://www.kernel.org/doc/Documentation/SubmittingPatches diff --git a/docs/usage/rest.md b/docs/usage/rest.md deleted file mode 100644 index e0fbf24..0000000 --- a/docs/usage/rest.md +++ /dev/null @@ -1,56 +0,0 @@ -# The REST API - -Patchwork provides a REST API. This API can be used to retrieve and modify -information about patches, projects and more. - -**NOTE:** The REST API was introduced in Patchwork v2.0. Users of earlier -Patchwork versions should instead refer to the [XML-RPC API -documentation][doc-xmlrpc]. - -## Patchwork REST API documentation - -Patchwork provides automatically generated documentation for the RESET API. -You can find this at the following URL: - - http://patchwork.example.com/api/ - -where `patchwork.example.com` refers to the URL of your Patchwork instance. - -## Interacting with the API - -REST APIs run over plain HTTP(S), thus, the API can be interfaced using -applications or libraries that support this widespread protocol. One such -application is [`curl`][ref-curl], which can be used to both retrieve and send -information to the REST API. For example, to get the version of the REST API -for a Patchwork instance hosted at `patchwork.example.com`, run: - - $ curl -s http://localhost:8000/api/1.0/ | python -m json.tool - { - "patches": "http://localhost:8000/api/1.0/patches/", - "people": "http://localhost:8000/api/1.0/people/", - "projects": "http://localhost:8000/api/1.0/projects/", - "users": "http://localhost:8000/api/1.0/users/" - } - -In addition, a huge variety of libraries are avaiable for interacting with and -parsing the output of REST APIs. The [`requests`][ref-requests] library is -wide-spread and well-supported. To repeat the above example using `requests`: - - $ python - >>> import json - >>> import requests - >>> r = requests.get('http://patchwork.example.com/api/1.0/') - >>> print(json.dumps(r.json(), indent=2)) - { - "users": "http://localhost:8000/api/1.0/users/", - "patches": "http://localhost:8000/api/1.0/patches/", - "projects": "http://localhost:8000/api/1.0/projects/", - "people": "http://localhost:8000/api/1.0/people/" - } - -Tools like `curl` and libraries like `requests` can be used to build anything -from small utilities to full-fledged clients targeting the REST API. - -[doc-xmlrpc]: xmlrpc.md -[ref-curl]: https://curl.haxx.se/ -[ref-requests]: http://docs.python-requests.org/en/master/ diff --git a/docs/usage/xmlrpc.md b/docs/usage/xmlrpc.md deleted file mode 100644 index 782edae..0000000 --- a/docs/usage/xmlrpc.md +++ /dev/null @@ -1,39 +0,0 @@ -# The XML-RPC API - -**NOTE:** This guide covers usage information for the Patchwork XML-RPC API. -For information on using the REST API, refer to the [REST API -documentation][doc-rest]. For information on developing custom applications or -clients for this API, refer to the [developers documentation][doc-development]. - -Patchwork provides an XML-RPC API. This API can be used to be used to retrieve -and modify information about patches, projects and more. - -**NOTE:** The XML-RPC API can be enabled/disabled by the administrator: it may -not be available in every instance. - -## pwclient - -The `pwclient` application, provided with Patchwork, can be used to interact -with Patchwork from the command line. Functionality provided by `pwclient` -includes: - -* Listing patches, projects, and checks -* Downloading and applying patches to a local code base -* Modifying the status of patches -* Creating new checks - -pwclient can be downloaded from the [Ozlabs Patchwork instance][ref-pw-oz], or -at the following path for other Patchwork instances: - - http://patchwork.example.com/pwclient/ - -where `patchwork.example.com` corresponds to the URL a Patchwork instance is -hosted at. - -Once downloaded, to view information about all the operations supported by -`pwclient`, run: - - $ pwclient --help - -[doc-development]: ../development/xmlrpc.md -[doc-rest]: rest.md |