DOC ONLY: update bug report section

More detail on why it's important to supply .debs or .rpms which
precisely match core files. Probably won't help, but we can try...

Change-Id: I7842eaea0ef921b934e84b7f18f6a333b1381292
Signed-off-by: Dave Barach <dave@barachs.net>

docs/troubleshooting/reportingissues/reportingissues.rst

@@ -5,15 +5,15 @@
 Reporting Bugs
 ==============
 
-Although every situation is different, this page describes how to
+Although every situation is different, this section describes how to
 collect data which will help make efficient use of everyone's time
 when dealing with vpp bugs.
 
 Before you press the Jira button to create a bug report - or email
 vpp-dev@lists.fd.io - please ask yourself whether there's enough
-information for someone else to understand and possibly to reproduce
+information for someone else to understand and to reproduce the issue
-the issue given a reasonable amount of effort. **Unicast emails to
+given a reasonable amount of effort. **Unicast emails to maintainers,
-maintainers, committers, and the project PTL are strongly discouraged.**
+committers, and the project PTL are strongly discouraged.**
 
 A good strategy for clear-cut bugs: file a detailed Jira ticket, and
 then send a short description of the issue to vpp-dev@lists.fd.io,
@@ -48,7 +48,7 @@ With respect to the operating environment: if misbehavior involving a
 specific VM / container / bare-metal environment is involved, please
 describe the environment in detail:
 
-* Linux Distro (e.g. Ubuntu 14.04.3 LTS, CentOS-7, etc.)
+* Linux Distro (e.g. Ubuntu 18.04.2 LTS, CentOS-7, etc.)
 * NIC type(s) (ixgbe, i40e, enic, etc. etc.), vhost-user, tuntap
 * NUMA configuration if applicable
 
@@ -60,15 +60,24 @@ unmodified master/latest software.
 "Show" command output
 ---------------------
 
-Every situation is different. If the issue involves a sequence of debug CLI command, please enable CLI command logging, and send the sequence involved. Note that the debug CLI is a developer's tool - **no warranty express or implied** - and that we may choose not to fix debug CLI bugs.
+Every situation is different. If the issue involves a sequence of
+debug CLI command, please enable CLI command logging, and send the
+sequence involved. Note that the debug CLI is a developer's tool -
+**no warranty express or implied** - and that we may choose not to fix
+debug CLI bugs.
 
-Please include "show error" [error counter] output. It's often helpful to "clear error", send a bit of traffic, then "show error" particularly when running vpp on a noisy networks.
+Please include "show error" [error counter] output. It's often helpful
+to "clear error", send a bit of traffic, then "show error"
+particularly when running vpp on noisy networks.
 
-Please include ip4 / ip6 / mpls FIB contents ("show ip fib", "show ip6 fib", "show mpls fib", "show mpls tunnel").
+Please include ip4 / ip6 / mpls FIB contents ("show ip fib", "show ip6
+fib", "show mpls fib", "show mpls tunnel").
 
-Please include "show hardware", "show interface", and "show interface address" output
+Please include "show hardware", "show interface", and "show interface
+address" output
 
-Here is a consolidated set of commands that are generally useful before/after sending traffic.  Before sending traffic.
+Here is a consolidated set of commands that are generally useful
+before/after sending traffic.  Before sending traffic:
 
 .. code-block:: console
 
@@ -196,21 +205,39 @@ Make sure to leave the default stanza "... unix { ... full-coredump
 /etc/vpp/startup.conf, or to include it in the command line arguments
 passed by orchestration software.
 
-Core files from private, modified images are discouraged. If it's
+Core files from private images require special handling. If it's
-necessary to go that route, please copy the **exact** Debian
+necessary to go that route, copy the **exact** Debian packages (or
-packages (or RPMs) corresponding to the core file to the same public
+RPMs) which correspond to the core file to the same public place as
-place as the core file. In particular.
+the core file. A no-excuses-allowed, hard-and-fast requirement.
 
-* vpp_<version>_<arch>.deb         # the vpp executable
+In particular:
-* vpp-dbg_<version>_<arch>.deb     # debug symbols
-* vpp-dev_<version>_<arch>.deb     # development package 
-* vpp-lib_<version>_<arch>.deb     # shared libraries
-* vpp-plugins_<version>_<arch>.deb # plugins
 
-Please include the full commit-ID the Jira ticket.
+.. code-block:: console
+
+  libvppinfra_<version>_<arch>.deb # vppinfra library
+  libvppinfra-dev_<version>_<arch>.deb # vppinfra library development pkg
+  vpp_<version>_<arch>.deb         # the vpp executable
+  vpp-dbg_<version>_<arch>.deb     # debug symbols
+  vpp-dev_<version>_<arch>.deb     # vpp development pkg
+  vpp-lib_<version>_<arch>.deb     # shared libraries
+  vpp-plugin-core_<version>_<arch>.deb # core plugins
+  vpp-plugin-dpdk_<version>_<arch>.deb # dpdk plugin
+
+For reference, please include git commit-ID, branch, and git repo
+information [for repos other than gerrit.fd.io] in the Jira ticket.
+
+Note that git commit-ids are crypto sums of the head [latest]
+**merged** patch. They say **nothing whatsoever** about local
+workspace modifications, branching, or the git repo in question.
+
+Even given a byte-for-byte identical source tree, it's easy to build
+dramatically different binary artifacts. All it takes is a different
+toolchain version.
+
+Bottom line: please follow core file handling instructions to the
+letter. It's not complicated. Simply copy the exact Debian packages or
+RPMs which correspond to core files to accessible locations.
 
 If we go through the setup process only to discover that the image and
-core files don't match, it will simply delay resolution of the
+core files don't match, it will simply delay resolution of the issue;
-issue. And it will annoy the heck out of the engineer who just wasted
+to say nothing of irritating the person who just wasted their time.
-their time. Exact means **exact**, not "oh, gee, I added a few lines
-of debug scaffolding since then..."