From 6098eb3fd530df060a54276c32c7b80230ded1e4 Mon Sep 17 00:00:00 2001
From: Jendrik Seipp <jendrik.seipp@liu.se>
Date: Sat, 21 Oct 2023 15:19:13 +0200
Subject: [PATCH] Add upgrade instructions.

---
 docs/faq.rst  | 31 +++++++++++++++++++++++++++++++
 docs/news.rst | 12 ++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/docs/faq.rst b/docs/faq.rst
index 73b323b55..b89876ae5 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -45,6 +45,37 @@ documentation <lab.parser.html>`_ for how to amend your parsers and then run the
     ./my-exp.py parse
 
 
+.. _portparsers:
+
+How do I port my parsers to version 8.x?
+----------------------------------------
+
+Since version 8.0, Lab has a dedicated "parse" experiment step. First of all,
+what are the benefits of this?
+
+* No need to write parsers in separate files.
+* Log output from solvers and parsers remains separate.
+* No need for ``exp.add_parse_again_step()``. Parsing and re-parsing is now
+  exactly the same.
+* Parsers are checked for syntax errors before the experiment is run.
+* Parsing runs much faster (for an experiment with 3 algorithms and 5 parsers
+  the parsing time went down from 51 minutes to 5 minutes, both measured on
+  cold file system caches).
+* As before, you can let the Slurm environment do the parsing for you and get
+  notified when the report is finished: ``./myexp.py build start parse fetch
+  report``
+
+To adapt your parsers to this new API, you need to make the following changes:
+
+* Your parser module (e.g., "custom_parser.py") does not have to be executable
+  anymore, but it must be importable and expose a :class:`Parser
+  <lab.parser.Parser>` instance. Then, instead of
+  ``exp.add_parser("custom_parser.py")`` use ``from custom_parser import
+  MyParser`` and ``exp.add_parser(MyParser())``.
+* Remove ``exp.add_parse_again_step()`` and insert ``exp.add_step("parse",
+  exp.parse)`` after ``exp.add_step("start", exp.start_runs)``.
+
+
 How can I compute a new attribute from multiple runs?
 -----------------------------------------------------
 
diff --git a/docs/news.rst b/docs/news.rst
index bdb636616..ba9091ff8 100644
--- a/docs/news.rst
+++ b/docs/news.rst
@@ -1,6 +1,18 @@
 Changelog
 =========
 
+v8.0 (2023-10-21)
+-----------------
+
+Lab
+^^^
+* Make parsing a separate experiment step, see :ref:`FAQs <portparsers>` for motivation and upgrade instructions (Jendrik Seipp).
+
+Downward Lab
+^^^^^^^^^^^^
+* None.
+
+
 v7.5 (2023-10-21)
 -----------------