From 83208b499174b63ad1b9fb7a91296ad0a0400b6d Mon Sep 17 00:00:00 2001 From: wxiaoguang Date: Tue, 29 Aug 2023 06:37:39 +0800 Subject: [PATCH] Improve the "bug report" template and "support options" document (#26753) * `/help/support` is a better document than `/administration/logging-config` for bug reporting * Improve `support.en-us.md` * Move/add detailed contents into `Advanced Bug Report Tips` section * Merge `Chinese Support` section into `Support Options` --- .github/ISSUE_TEMPLATE/bug-report.yaml | 9 ++-- docs/content/help/support.en-us.md | 67 +++++++++++++++++--------- 2 files changed, 48 insertions(+), 28 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug-report.yaml b/.github/ISSUE_TEMPLATE/bug-report.yaml index 5ab498cb7..1004c55de 100644 --- a/.github/ISSUE_TEMPLATE/bug-report.yaml +++ b/.github/ISSUE_TEMPLATE/bug-report.yaml @@ -1,6 +1,6 @@ name: Bug Report description: Found something you weren't expecting? Report it here! -labels: kind/bug +labels: ["kind/bug"] body: - type: markdown attributes: @@ -15,11 +15,8 @@ body: 3. Make sure you are using the latest release and take a moment to check that your issue hasn't been reported before. 4. Make sure it's not mentioned in the FAQ (https://docs.gitea.com/help/faq) - 5. Please give all relevant information below for bug reports, because + 5. It's really important to provide pertinent details and logs (https://docs.gitea.com/help/support), incomplete details will be handled as an invalid report. - 6. In particular it's really important to provide pertinent logs. You must give us DEBUG level logs. - Please read https://docs.gitea.com/administration/logging-config#collecting-logs-for-help - In addition, if your problem relates to git commands set `RUN_MODE=dev` at the top of app.ini - type: textarea id: description attributes: @@ -89,6 +86,6 @@ body: description: What database system are you running? options: - PostgreSQL - - MySQL + - MySQL/MariaDB - MSSQL - SQLite diff --git a/docs/content/help/support.en-us.md b/docs/content/help/support.en-us.md index 24afe67bb..db735b812 100644 --- a/docs/content/help/support.en-us.md +++ b/docs/content/help/support.en-us.md @@ -22,34 +22,57 @@ menu: - [Discourse Forum](https://discourse.gitea.io/) - [Matrix](https://matrix.to/#/#gitea-space:matrix.org) - NOTE: Most of the Matrix channels are bridged with their counterpart in Discord and may experience some degree of flakiness with the bridge process. +- Chinese Support + - [Discourse Chinese Category](https://discourse.gitea.io/c/5-category/5) + - QQ Group 328432459 + +# Bug Report + +If you found a bug, please [create an issue on GitHub](https://github.com/go-gitea/gitea/issues). **NOTE:** When asking for support, it may be a good idea to have the following available so that the person helping has all the info they need: 1. Your `app.ini` (with any sensitive data scrubbed as necessary). -2. The Gitea logs, and any other appropriate log files for the situation. - - When using systemd, use `journalctl --lines 1000 --unit gitea` to collect logs. - - When using docker, use `docker logs --tail 1000 ` to collect logs. - - By default, the logs are outputted to console. If you need to collect logs from files, - you could copy the following config into your `app.ini` (remove all other `[log]` sections), - then you can find the `*.log` files in Gitea's log directory (default: `%(GITEA_WORK_DIR)/log`). - - ```ini - ; To show all SQL logs, you can also set LOG_SQL=true in the [database] section - [log] - LEVEL=debug - MODE=console,file - ``` - -3. Any error messages you are seeing. -4. When possible, try to replicate the issue on [try.gitea.io](https://try.gitea.io) and include steps so that others can reproduce the issue. - - This will greatly improve the chance that the root of the issue can be quickly discovered and resolved. -5. If you encounter slow/hanging/deadlock problems, please report the stack trace when the problem occurs. +2. Any error messages you are seeing. +3. The Gitea logs, and all other related logs for the situation. + - It's more useful to collect `trace` / `debug` level logs (see the next section). + - When using systemd, use `journalctl --lines 1000 --unit gitea` to collect logs. + - When using docker, use `docker logs --tail 1000 ` to collect logs. +4. Reproducible steps so that others could reproduce and understand the problem more quickly and easily. + - [try.gitea.io](https://try.gitea.io) could be used to reproduce the problem. +5. If you encounter slow/hanging/deadlock problems, please report the stacktrace when the problem occurs. Go to the "Site Admin" -> "Monitoring" -> "Stacktrace" -> "Download diagnosis report". -## Bugs +# Advanced Bug Report Tips -If you found a bug, please create an [issue on GitHub](https://github.com/go-gitea/gitea/issues). +## More Config Options for Logs -## Chinese Support +By default, the logs are outputted to console with `info` level. +If you need to set log level and/or collect logs from files, +you could just copy the following config into your `app.ini` (remove all other `[log]` sections), +then you will find the `*.log` files in Gitea's log directory (default: `%(GITEA_WORK_DIR)/log`). -Support for the Chinese language is provided at [Our discourse](https://discourse.gitea.io/c/5-category/5) or QQ Group 328432459. +```ini +; To show all SQL logs, you can also set LOG_SQL=true in the [database] section +[log] +LEVEL=debug +MODE=console,file +``` + +## Collecting Stacktrace by Command Line + +Gitea could use Golang's pprof handler and toolchain to collect stacktrace and other runtime information. + +If the web UI stops working, you could try to collect the stacktrace by command line: + +1. Set `app.ini`: + + ``` + [server] + ENABLE_PPROF = true + ``` + +2. Restart Gitea + +3. Try to trigger the bug, when the requests get stuck for a while, + use `curl` or browser to visit: `http://127.0.0.1:6060/debug/pprof/goroutine?debug=1` to get the stacktrace.