From 5b52aef783593440ef79f53da33659a10bcf15b4 Mon Sep 17 00:00:00 2001 From: Athanasius Date: Fri, 9 Oct 2020 10:27:57 +0100 Subject: [PATCH] Expand on running from git, and emphasise about Bug Reports and Log Files * Direct 'run from source' git users to use `stable` branch. * Direct people to attempt installing a 'pip' with `--user` if they don't have it already. * Tweak mention of Debian/Ubuntu/derivatives. * Emphasise the need to use the Bug Report issue template. * Emphasise, all over, the difference between the plain and debug log files and that we need both. --- Running-from-source.md | 25 ++++++++++++++++--------- Troubleshooting.md | 23 ++++++++++++++++++++--- 2 files changed, 36 insertions(+), 12 deletions(-) diff --git a/Running-from-source.md b/Running-from-source.md index 16a6506..667c46b 100644 --- a/Running-from-source.md +++ b/Running-from-source.md @@ -1,17 +1,22 @@ Running from source === -1. Download and extract the [latest stable source code](https://github.com/EDCD/EDMarketConnector/archive/stable.zip). +1. You have two choices: + 1. Using a zip of the latest stable source. Download and extract the + [latest stable source code](https://github.com/EDCD/EDMarketConnector/archive/stable.zip). + + 1. OR Clone and checkout the source using git: + 1. `cd ` + 1. `git clone git@github.com:EDCD/EDMarketConnector.git` + 1. `cd EDMarketConnector` + 1. `git checkout stable` As per [Contributing.md](https://github.com/EDCD/EDMarketConnector/blob/main/Contributing.md#git-branch-structure-and-tag-conventions) `stable` will contain the latest released code, or possibly some extra commits leading up to the next release. If you're feeling slightly -braver you could download and extract the [main branch source code](https://github.com/EDCD/EDMarketConnector/archive/main.zip) -instead which might contain newer code that we consider stable enough for -the next release. - - You can `git clone` the repository instead and use the appropriate - branch that way if you prefer. +braver you could use the [main branch source code](https://github.com/EDCD/EDMarketConnector/archive/main.zip) +(or `git checkout main`) instead which might contain newer code that we +consider stable enough for the next release. *NB: Do not use the `master` branch*, it's almost empty! The name is deprecated and we use `main` instead. @@ -20,10 +25,12 @@ the next release. 1. Ensure additional necessary Python modules are installed with `pip install -r requirements.txt` . * Note that on Debian (at least up to and including 10.x aka 'Buster') you'll `pip3 install -r requirements.txt` . - * If you get 'command not found' or similar for the 'pip' command then try: `python -m pip install -r requirements.txt` . + * If you get 'command not found' or similar for the 'pip' command then + first try: `python -m pip --user install pip`. 1. Ensure you have tkinter installed if required (such as on Linux) - * On Debian / *buntu / *buntu derivatives the package you want is `python3-tk` + * On Debian / Ubuntu / other Debian derivatives the package you want is + `python3-tk`. 1. Run this application: diff --git a/Troubleshooting.md b/Troubleshooting.md index 9847448..863b8ef 100644 --- a/Troubleshooting.md +++ b/Troubleshooting.md @@ -242,9 +242,17 @@ If your configuration has been corrupted, or badly set, such that you can't run -- # Reporting a problem Please report a problem as a new GitHub [issue](https://github.com/EDCD/EDMarketConnector/issues/new?assignees=&labels=bug%2C+unconfirmed&template=bug_report.md&title=). -. -Be sure to attach a relevant log file as detailed below (Debug log file -preferred). +**Do not decide you do not need to use the Bug Report template. All of the +information it asks for is vital in diagnosing any bugs.** + +Be sure to attach both: + + 1. A relevant [debug log file](#debug-log-file) - these are always at DEBUG + level, or even TRACE if you use the `--trace` command-line option, so might + contain information not in... + 1. The [plain log file](#plain-log-file) **immediately** *after the bug + occurs*. In addition to actually logged output this contains any other + output which won't be in the debug log file. ## Debug Log Files If you are using 4.1.0, or later (including betas of 4.1.0) then there is a new @@ -263,6 +271,10 @@ These files also *always* contain DEBUG output, whereas the file detailed below only contains raw `print()` output and anything logged at the level you have configured. +They do **not contain** plain `print(..)` and other non-logged output, so we +still need you to also supply the [plain log file](#plain-log-file) in bug +reports as well. + ## Plain Log File Prior to EDMC 4.1.0 the only logfile is re-created on each run of the program. As such you will need to re-create the issue and then make a copy of the file: @@ -270,3 +282,8 @@ As such you will need to re-create the issue and then make a copy of the file: * Windows: `%TEMP%\EDMarketConnector.log` * Mac: `$TMPDIR/EDMarketConnector.log` * Linux: `$TMPDIR/EDMarketConnector.log` + +This file contains redirected "standard and error output", i.e. all console +output of the program. As such it might contain output not present in the +[debug log files](#debug-log-files) and it is vital you attach *this* file +to bug reports as well. \ No newline at end of file