Commit 3c263deb authored by Arkadiusz Hiler's avatar Arkadiusz Hiler

Add a help page on Patchwork's concept of series

and link to it from the messages about series being incomplete/strange.
Signed-off-by: default avatarArkadiusz Hiler <arkadiusz.hiler@intel.com>
parent f3bd0565
{% extends "base.html" %}
{% block title %}Series Explained{% endblock %}
{% block heading %} - How Patchwork Groups Patches?{% endblock %}
{% block body %}
<div style="width: 100ch">
<h2>The Series</h2>
<p>
A series is an ordered collection of related patches that should be applied and
tested together.
</p>
<p>
Patchwork, when parsing emails, assumes that series is sent via <tt>git
send-email</tt>.
</p>
<p>
The very first patch (or the cover letter) in the series is sent as top level
message (i.e. no <tt>In-Reply-To</tt> header) and all the following patches are
sent <tt>In-Reply-To</tt> that first patch.
</p>
<p>
<b>Example:</b>
</p>
<pre>
[0/2] Cover Letter
|-&gt; [1/2] The First Patch
|-&gt; [2/2] The Second Patch
</pre>
<pre>
[1/3] The First Patch
|-&gt; [2/3] The First Patch
|-&gt; [3/3] The Second Patch
</pre>
<p>
When in doubt please refer to <tt>git send-email --help</tt>.
</p>
<h2>Updating A Single Patch In A Series</h2>
<p>
If you send another patch as a reply to one of the existing patches it will be
considered an updated version. Patchwork will create a new revision of the
series with that patch updated.
</p>
<p>
You have to reply to the particular mail you are updating
(<tt>git send-email --in-reply-to=...</tt>)
</p>
<pre>
[1/3] The First Patch
|-&gt; [2/3] The Second Patch
|-&gt; [v2 2/3] Revised Second Patch
|-&gt; [3/3] The Third Patch
</pre>
<p>
<b>NOTE:</b> It may not work as intended if you don't have a cover letter and
you are replying to the very first patch.
</p>
<p>
<b>NOTE2:</b> If you are sending/formatting just a single patch from the series,
the patch numbers (<tt>[X/Y]</tt>) won't be included, and the series will be
marked as "strange" by the Patchwork. You can avoid that by adding the numbers
by hand to the <tt>.patch</tt> file or by using <tt>--annotate</tt> with <tt>git
send-email</tt>.
</p>
<h2>Updating More Patches In A Series</h2>
<p>
Usually you are better of re-sending the whole series.
</p>
<h2>Sending Patches That Failed To Send</h2>
<p>
If you send only part of your series (e.g. SMTP refused to work half-way) you
can easily send the remaining patches.
</p>
<p>
Format the whole series using <tt>git format-patch</tt> and then send only the
patches that failed to send via <tt>git send-email --in-reply-to=... --no-thread
0005-foo.patch 0006-bar.patch</tt>
</p>
<h2>Series Marked Strange/Incomplete</h2>
<p>
If you series is marked as <b>"strange"</b> it means that something is off with
patch ordering. This usually happen when you reply with an updated patch but
forget to add the number (<tt>[X/Y]</tt>). If you have inspected the list of the
patches and it looks correct to you there's nothing to worry about.
</p>
<p>
If your series is marked as <b>"incomplete"</b> it means that Patchwork is
missing some of the expected patches. The patch numbers in the subject
(<tt>[X/Y]</tt>) are very important - it tells Patchwork how many patches to
expect for the series (<tt>Y</tt>) and how to order incoming patches
(<tt>X</tt>). This may happen if some of the patches haven't reached Patchwork
or the series was not threaded correctly or the patches had inconsistent
numbers.
</p>
</div>
{% endblock %}
......@@ -218,10 +218,12 @@ $(document).ready(function() {
{% if not revision.is_complete %}
<div class="alert alert-danger">
<strong>SERIES REVISION IS NOT COMPLETE.</strong> We've got {{ revision.patches_count }} out of {{ revision.n_patches }} expected patches.
<a href="{% url 'help' path="series/" %}">More info.</a>
</div>
{% elif revision.is_strange %}
<div class="alert alert-warning">
<strong>SERIES REVISION LOOKS STRANGE.</strong> Please double-check patch list and the ordering before proceeding.
<a href="{% url 'help' path="series/" %}">More info.</a>
</div>
{% endif %}
......
......@@ -150,6 +150,7 @@ def user_complete(request):
help_pages = {'': 'index.html',
'about/': 'about.html',
'series/': 'series-explained.html',
}
if settings.ENABLE_XMLRPC:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment