From d1c91b7d27f81e3db5973472e0f22a3853ff5c19 Mon Sep 17 00:00:00 2001
From: John Huddleston <huddlej@gmail.com>
Date: Tue, 14 Nov 2023 10:26:22 -0800
Subject: [PATCH 1/3] Add log recommendations to Snakemake style guide

Adds two recommendations about logging to the Snakemake style guide
based on recent difficulty troubleshooting workflow issues with users.
---
 src/reference/snakemake-style-guide.rst | 33 +++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/src/reference/snakemake-style-guide.rst b/src/reference/snakemake-style-guide.rst
index dc8f234f..2db18a58 100644
--- a/src/reference/snakemake-style-guide.rst
+++ b/src/reference/snakemake-style-guide.rst
@@ -193,3 +193,36 @@ Example:
            --output-sequences {output.sequences:q} \
            --output-metadata {output.metadata:q}
        """
+
+Log standard out and error output to log files and the terminal
+===============================================================
+
+Use `the Snakemake ``log`` directive <https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#log-files>`__ for each rule that writes output to either standard out or error and direct output to the corresponding log file.
+Use the ``tee`` command to ensure that output gets written to both the log file and the terminal, so users can track their workflow progress interactively and use the log file later for debugging.
+
+Example:
+
+.. code-block:: python
+
+   rule filter:
+       input:
+           metadata="results/metadata.tsv",
+       output:
+           metadata="results/filtered_metadata.tsv",
+       log:
+           "logs/filter.txt"
+       shell:
+           """
+           augur filter \
+               --metadata {input.metadata} \
+               --output-metadata {output.metadata} 2>&1 | tee {log}
+           """
+
+Before using ``tee``, ensure that your workflow uses bash's ``pipefail`` option so successful ``tee`` execution does not mask errors from earlier commands in the pipe.
+Snakemake enables this option by default.
+
+Run workflows with ``--show-failed-logs``
+=========================================
+
+Run workflows with the ``--show-failed-logs`` which will print the logs for failed jobs to the terminal when the workflow exits.
+This pattern helps users identify error messages without first finding the corresponding log file.

From f1bf402a825894beeefeaf8b9f6f31a9c412d608 Mon Sep 17 00:00:00 2001
From: John Huddleston <huddlej@gmail.com>
Date: Tue, 14 Nov 2023 16:05:01 -0800
Subject: [PATCH 2/3] Fix link and commas

---
 src/reference/snakemake-style-guide.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/reference/snakemake-style-guide.rst b/src/reference/snakemake-style-guide.rst
index 2db18a58..d40c8f3a 100644
--- a/src/reference/snakemake-style-guide.rst
+++ b/src/reference/snakemake-style-guide.rst
@@ -197,7 +197,7 @@ Example:
 Log standard out and error output to log files and the terminal
 ===============================================================
 
-Use `the Snakemake ``log`` directive <https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#log-files>`__ for each rule that writes output to either standard out or error and direct output to the corresponding log file.
+Use `the Snakemake log directive <https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#log-files>`_ for each rule that writes output to either standard out or error and direct output to the corresponding log file.
 Use the ``tee`` command to ensure that output gets written to both the log file and the terminal, so users can track their workflow progress interactively and use the log file later for debugging.
 
 Example:
@@ -218,7 +218,7 @@ Example:
                --output-metadata {output.metadata} 2>&1 | tee {log}
            """
 
-Before using ``tee``, ensure that your workflow uses bash's ``pipefail`` option so successful ``tee`` execution does not mask errors from earlier commands in the pipe.
+Before using ``tee``, ensure that your workflow uses bash's ``pipefail`` option, so successful ``tee`` execution does not mask errors from earlier commands in the pipe.
 Snakemake enables this option by default.
 
 Run workflows with ``--show-failed-logs``

From 1664eecee098ca572270ddf08cb5f1a72b99b739 Mon Sep 17 00:00:00 2001
From: John Huddleston <huddlej@gmail.com>
Date: Wed, 15 Nov 2023 09:44:59 -0800
Subject: [PATCH 3/3] Add more details about the pipefail option

Link to docs on bash's strict mode and provide examples of how
Snakemake's default use of this mode might be overridden in a workflow.
---
 src/reference/snakemake-style-guide.rst | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/reference/snakemake-style-guide.rst b/src/reference/snakemake-style-guide.rst
index d40c8f3a..4db75316 100644
--- a/src/reference/snakemake-style-guide.rst
+++ b/src/reference/snakemake-style-guide.rst
@@ -218,8 +218,9 @@ Example:
                --output-metadata {output.metadata} 2>&1 | tee {log}
            """
 
-Before using ``tee``, ensure that your workflow uses bash's ``pipefail`` option, so successful ``tee`` execution does not mask errors from earlier commands in the pipe.
-Snakemake enables this option by default.
+Before using ``tee``, ensure that your workflow uses `bash's pipefail option <http://redsymbol.net/articles/unofficial-bash-strict-mode/>`_, so successful ``tee`` execution does not mask errors from earlier commands in the pipe.
+Snakemake uses bash's strict mode by default, so the pipefail option should be enabled by default.
+However, some workflows may override the defaults `locally at specific rules <https://snakemake.readthedocs.io/en/stable/project_info/faq.html#my-shell-command-fails-with-exit-code-0-from-within-a-pipe-what-s-wrong>`_ or globally as with `a custom shell prefix <https://github.com/nextstrain/ncov/pull/751>`_.
 
 Run workflows with ``--show-failed-logs``
 =========================================