From patchwork Sun Apr 15 22:54:05 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 898342 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.ozlabs.org (lists.ozlabs.org [203.11.71.2]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 40PRkW5DdPz9s1R for ; Mon, 16 Apr 2018 08:58:11 +1000 (AEST) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=that.guru Authentication-Results: ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b="pMBAfKnh"; dkim-atps=neutral Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) by lists.ozlabs.org (Postfix) with ESMTP id 40PRkW3mXjzDqvH for ; Mon, 16 Apr 2018 08:58:11 +1000 (AEST) Authentication-Results: lists.ozlabs.org; dmarc=none (p=none dis=none) header.from=that.guru Authentication-Results: lists.ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b="pMBAfKnh"; dkim-atps=neutral X-Original-To: patchwork@lists.ozlabs.org Delivered-To: patchwork@lists.ozlabs.org Authentication-Results: lists.ozlabs.org; spf=none (mailfrom) smtp.mailfrom=that.guru (client-ip=23.83.222.35; helo=chocolate.ash.relay.mailchannels.net; envelope-from=stephen@that.guru; receiver=) Authentication-Results: lists.ozlabs.org; dmarc=none (p=none dis=none) header.from=that.guru Authentication-Results: lists.ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b="pMBAfKnh"; dkim-atps=neutral Received: from chocolate.ash.relay.mailchannels.net (chocolate.ash.relay.mailchannels.net [23.83.222.35]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id 40PRfG0vlFzF1sY for ; Mon, 16 Apr 2018 08:54:29 +1000 (AEST) X-Sender-Id: 5xi41l16bi|x-authuser|stephen@that.guru Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id 71D265E1014 for ; Sun, 15 Apr 2018 22:54:23 +0000 (UTC) Received: from one.mxroute.com (unknown [100.96.20.22]) (Authenticated sender: 5xi41l16bi) by relay.mailchannels.net (Postfix) with ESMTPA id 0C97E5E0E02 for ; Sun, 15 Apr 2018 22:54:22 +0000 (UTC) X-Sender-Id: 5xi41l16bi|x-authuser|stephen@that.guru Received: from one.mxroute.com (one-outgoing.mxroute.com [172.19.36.130]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.14.1); Sun, 15 Apr 2018 22:54:23 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: 5xi41l16bi|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: 5xi41l16bi X-Vacuous-Imminent: 22b9f014008d6502_1523832863375_995023945 X-MC-Loop-Signature: 1523832863375:2294995644 X-MC-Ingress-Time: 1523832863375 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=that.guru; s=default; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Sender:Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=+uigowkcvV74KXPMgDrYdkBSa+o+g+QsTQcngXyf6E4=; b=pMBAfKnh5K3Hy7RNZJcFxi+TSQ KXIpOXcIbc2WXjhpJt0oi2gujchUkYiIvCld3GTfj5xqSmD4mmJJXgQNsb99mRpNzJD+mG/t8pNPa NljYY/wcOAene+k9L5igXqiC3n58QZSHBYzr4TbKKZG9wSNgXQocuXOgKG64cnKZwEVdu2DWQS47g GZnUHGmuNQAL4gXi8HKBs5Omr7SFX2b2oCiiVZPI3whejDeoZARU0SNy13irayB9jOQNtwBhjgG6j xP7S2Tn3XN0fh/hql69JSZAps84O502e1nB5t2TPtTElCiLMqglFwwPuL9amp1Cg7ppKlkqS+94DI HUP+skXg==; From: Stephen Finucane To: patchwork@lists.ozlabs.org Subject: [PATCH 11/11] docs: Random fixes Date: Sun, 15 Apr 2018 23:54:05 +0100 Message-Id: <20180415225405.1354-12-stephen@that.guru> X-Mailer: git-send-email 2.14.3 In-Reply-To: <20180415225405.1354-1-stephen@that.guru> References: <20180415225405.1354-1-stephen@that.guru> X-AuthUser: stephen@that.guru X-BeenThere: patchwork@lists.ozlabs.org X-Mailman-Version: 2.1.26 Precedence: list List-Id: Patchwork development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: patchwork-bounces+incoming=patchwork.ozlabs.org@lists.ozlabs.org Sender: "Patchwork" Remove an unnecessary 'toctree' from the index page and fix some definition lists. Signed-off-by: Stephen Finucane --- docs/api/index.rst | 2 + docs/deployment/index.rst | 2 + docs/development/api.rst | 6 +- docs/development/index.rst | 2 + docs/index.rst | 19 ------ docs/releases/index.rst | 2 + docs/usage/delegation.rst | 3 - docs/usage/index.rst | 2 + docs/usage/overview.rst | 141 ++++++++++++++++++--------------------------- 9 files changed, 69 insertions(+), 110 deletions(-) diff --git a/docs/api/index.rst b/docs/api/index.rst index b2e93e01..82481509 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -1,3 +1,5 @@ +:orphan: + API Documentation ================= diff --git a/docs/deployment/index.rst b/docs/deployment/index.rst index d7b3fa37..984e8a5f 100644 --- a/docs/deployment/index.rst +++ b/docs/deployment/index.rst @@ -1,3 +1,5 @@ +:orphan: + Deployment Documentation ======================== diff --git a/docs/development/api.rst b/docs/development/api.rst index 3cfefdb8..bcb1f695 100644 --- a/docs/development/api.rst +++ b/docs/development/api.rst @@ -1,3 +1,5 @@ +:orphan: + Using the APIs ============== @@ -5,6 +7,6 @@ Patchwork provides two APIs: the legacy :doc:`XML-RPC API <../api/xmlrpc>` and the :doc:`REST API <../api/rest>`. You can use these APIs to interact with Patchwork programmatically and to develop your own clients. -For quick usage examples of the APIs, refer to the :ref:`documentation -`. For examples of existing clients, refer to +For quick usage examples of the APIs, refer to the :doc:`documentation +<../api/index>`. For examples of existing clients, refer to :doc:`../usage/clients`. diff --git a/docs/development/index.rst b/docs/development/index.rst index 4447453c..7c3d8040 100644 --- a/docs/development/index.rst +++ b/docs/development/index.rst @@ -1,3 +1,5 @@ +:orphan: + Development Documention ======================= diff --git a/docs/index.rst b/docs/index.rst index 2c2b92d4..9cbd6ebe 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,8 +17,6 @@ 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. -.. _user-docs: - .. toctree:: :maxdepth: 2 :caption: Usage Documentation @@ -29,8 +27,6 @@ of community projects. usage/headers usage/clients -.. _deployment-docs: - .. toctree:: :maxdepth: 2 :caption: Deployment Documentation @@ -40,8 +36,6 @@ of community projects. deployment/management deployment/upgrading -.. _development-docs: - .. toctree:: :maxdepth: 2 :caption: Development Documentation @@ -52,8 +46,6 @@ of community projects. development/api development/assets -.. _api-docs: - .. toctree:: :maxdepth: 2 :caption: API Documentation @@ -61,8 +53,6 @@ of community projects. api/rest api/xmlrpc -.. _release-note-docs: - .. toctree:: :maxdepth: 2 :caption: Release Notes @@ -72,12 +62,3 @@ of community projects. releases/cashmere releases/burlap releases/alpaca - -.. toctree:: - :hidden: - - usage/index - deployment/index - development/index - api/index - releases/index diff --git a/docs/releases/index.rst b/docs/releases/index.rst index 8ddaafb2..3549e30a 100644 --- a/docs/releases/index.rst +++ b/docs/releases/index.rst @@ -1,3 +1,5 @@ +:orphan: + Release Notes ============= diff --git a/docs/usage/delegation.rst b/docs/usage/delegation.rst index 8b99871a..b9e620bb 100644 --- a/docs/usage/delegation.rst +++ b/docs/usage/delegation.rst @@ -17,17 +17,14 @@ configured in the project administration page. This can usually be found at: 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`__ format. The fnmatch library allows for limited, Unix shell-style wildcarding. Filenames are extracted from patch lines beginning with ``---`` or ``+++``. diff --git a/docs/usage/index.rst b/docs/usage/index.rst index 79d10d83..9d7dcf01 100644 --- a/docs/usage/index.rst +++ b/docs/usage/index.rst @@ -1,3 +1,5 @@ +:orphan: + Usage Documentation =================== diff --git a/docs/usage/overview.rst b/docs/usage/overview.rst index 335e8dea..27bab29b 100644 --- a/docs/usage/overview.rst +++ b/docs/usage/overview.rst @@ -3,6 +3,9 @@ Overview The key concepts or models of Patchwork are outlined below. +.. contents:: + + Projects -------- @@ -13,12 +16,14 @@ 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 ----- @@ -44,6 +49,7 @@ The operations that a maintainer can invoke include: - Archive a patch - Delegate a patch, or be delegated a patch + Submissions ----------- @@ -70,14 +76,16 @@ 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 -------------- @@ -115,20 +123,17 @@ 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: - +``Acked-by:`` For example:: Acked-by: Stephen Finucane -Tested-by: - +``Tested-by:`` For example:: Tested-by: Stephen Finucane -Reviewed-by: - +``Reviewed-by:`` For example:: Reviewed-by: Stephen Finucane @@ -159,25 +164,21 @@ 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 - +**Context** A label to discern check from the checks of other testing systems -Description - +**Description** A brief, optional description of the check -Target URL - +**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 +**State** + The state of the check. One of: ``pending``, ``success``, ``warning``, + ``fail`` +**User** The user creating the check .. note:: @@ -190,6 +191,7 @@ User Provide information on building a CI system that reports check results back to Patchwork. + Collections ----------- @@ -219,6 +221,7 @@ To-do Lists Patchwork users can store a to-do list of patches. + Events ------ @@ -227,146 +230,112 @@ Events are raised whenever patches are created or modified. All events have a number of common properties, along with some event-specific properties: -`category` - +``category`` The type of event -`project` - +``project`` The project this event belongs to -`date` - +``date`` When this event was created -.. note:: - - Checks can only be created and read through the Patchwork APIs. Refer to - `../api/index` for more information. +``payload`` + Additional information Cover Letter Created ~~~~~~~~~~~~~~~~~~~~ -Sent when a cover letter is created. - -`category` +:Category: ``cover-created`` - ``cover-created`` - -`cover` +Sent when a cover letter is created. +``cover`` Created cover letter Patch Created ~~~~~~~~~~~~~ -Sent when a patch is created. - -`category` - - ``patch-created`` +:Category: ``patch-created`` -`patch` +Sent when a patch is created. +``patch`` Created patch Patch Completed ~~~~~~~~~~~~~~~ +:Category: ``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). -`category` - - ``patch-completed`` - -`patch` - +``patch`` Completed patch -`series` - +``series`` Series from which patch dependencies were extracted, if any Patch Delegated ~~~~~~~~~~~~~~~ -Sent when a patch's delegate is changed. - -`category` +:Category: ``patch-delegated`` - ``patch-delegated`` - -`patch` +Sent when a patch's delegate is changed. +``patch`` Updated patch -`previous` - +``previous`` Previous delegate, if any -`current` - +``current`` Current delegate, if any Patch State Changed ~~~~~~~~~~~~~~~~~~~ -Sent when a patch's state is changed. - -`category` - - ``patch-state-changed`` +:Category: ``patch-state-changed`` -`patch` +Sent when a patch's state is changed. +``patch`` Updated patch -`previous` - +``previous`` Previous state -`current` - +``current`` Current state Check Created ~~~~~~~~~~~~~ -Sent when a patch check is created. - -`category` - - ``check-created`` +:Category: ``check-created`` -`check` +Sent when a patch check is created. +``check`` Created check Series Created ~~~~~~~~~~~~~~ -Sent when a series is created. +:Category: ``series-created`` -`category` - - ``series-created`` - -`series` +Sent when a series is created. +``series`` Created series Series Completed ~~~~~~~~~~~~~~~~ -Sent when a series is completed. +:Category: ``series-completed`` -`category` - - ``series-completed`` - -`series` +Sent when a series is completed. +``series`` Completed series What's Not Exposed