1
0
mirror of https://github.com/EDCD/EDMarketConnector.git synced 2025-07-14 15:41:09 +03:00

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.
Athanasius 2020-10-09 10:27:57 +01:00
parent eedefef083
commit 5b52aef783
2 changed files with 36 additions and 12 deletions

@ -1,17 +1,22 @@
Running from source 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 <directory you want ot be the parent of the source>`
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) 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 `stable` will contain the latest released code, or possibly some extra
commits leading up to the next release. If you're feeling slightly 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) braver you could use 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 (or `git checkout main`) instead which might contain newer code that we
the next release. consider stable enough for the next release.
You can `git clone` the repository instead and use the appropriate
branch that way if you prefer.
*NB: Do not use the `master` branch*, it's almost empty! The name is *NB: Do not use the `master` branch*, it's almost empty! The name is
deprecated and we use `main` instead. 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` . 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` . * 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) 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: 1. Run this application:

@ -242,9 +242,17 @@ If your configuration has been corrupted, or badly set, such that you can't run
-- --
# Reporting a problem # 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=). 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=).
. **Do not decide you do not need to use the Bug Report template. All of the
Be sure to attach a relevant log file as detailed below (Debug log file information it asks for is vital in diagnosing any bugs.**
preferred).
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 ## Debug Log Files
If you are using 4.1.0, or later (including betas of 4.1.0) then there is a new 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 whereas the file detailed below only contains raw `print()` output and anything
logged at the level you have configured. 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 ## Plain Log File
Prior to EDMC 4.1.0 the only logfile is re-created on each run of the program. 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: 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` * Windows: `%TEMP%\EDMarketConnector.log`
* Mac: `$TMPDIR/EDMarketConnector.log` * Mac: `$TMPDIR/EDMarketConnector.log`
* Linux: `$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.