Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add a troubleshooting section and reproducible example guide #10947

Merged
merged 4 commits into from
Jan 27, 2025
Merged

Add a troubleshooting section and reproducible example guide #10947

merged 4 commits into from
Jan 27, 2025

Conversation

zanieb
Copy link
Member

@zanieb zanieb commented Jan 24, 2025

No description provided.

@zanieb zanieb added the documentation Improvements or additions to documentation label Jan 24, 2025
@zanieb zanieb changed the title Add a troubleshooting section Add a troubleshooting section and reproducible example guide Jan 24, 2025
@zanieb zanieb force-pushed the zb/troubleshooting branch 2 times, most recently from 944beef to d05c029 Compare January 24, 2025 21:19
@zanieb
Copy link
Member Author

zanieb commented Jan 24, 2025

Feedback welcome. I intend to link to this in the bug report issue template where we currently link to StackOverflow's guide.

@zanieb zanieb force-pushed the zb/troubleshooting branch 2 times, most recently from c900677 to 6ed8818 Compare January 24, 2025 21:29
@zanieb zanieb force-pushed the zb/troubleshooting branch from 6ed8818 to ba94c1b Compare January 24, 2025 21:29
zanieb and others added 2 commits January 24, 2025 16:53
@zanieb @edmorley
Update docs/reference/troubleshooting/reproducible-examples.md
0b6e9e9 
Co-authored-by: Ed Morley <501702+edmorley@users.noreply.github.com>
@zanieb @edmorley
Update docs/reference/troubleshooting/index.md
00c81de 
Co-authored-by: Ed Morley <501702+edmorley@users.noreply.github.com>
@zanieb
Copy link
Member Author

zanieb commented Jan 24, 2025

Thanks Ed!

konstin
konstin reviewed Jan 27, 2025
View reviewed changes
docs/reference/troubleshooting/reproducible-examples.md
@@ -0,0 +1,116 @@
# Reproducible examples

A minimal reproducible example (MRE) is essential for fixing bugs. Without an example that can be
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd make this less concept-based and more pragmatically telling users what we need:

Give us all the commands and file contents we need to reproduce your problem, starting from a fresh directory. If you can't minimize your problem this way, share a reproduction starting from a git clone. We need to be able to reproduce your problem to help you. If you're unsure if your problem is actually a bug, consider asking in our discord. Try removing as many dependencies, configuration and files as possible to create a minimal example. If the example is not minimal, [...] stack overflow on MREs [...]

Include:

  • what you're trying to achieve
  • all commands
  • the complete error message
  • the log from the command with -v, e.g. as gist

Having a docker image reproduce is amazing, but considering that most of our users won't be using docker it's a tough first section.

For example, i consider #10438 still a perfect issue, even it doesn't have docker and non-minimal requirements. We should link to some good reference example issue(s) in each section.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is basically what we're already saying in #9452 though

I can try to incorporate some of this regardless

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'll restructure the intro

@zanieb zanieb force-pushed the zb/troubleshooting branch from 6fad7b9 to 60f76aa Compare January 27, 2025 19:27
@zanieb zanieb merged commit 71f0798 into main Jan 27, 2025
61 checks passed
@zanieb zanieb deleted the zb/troubleshooting branch January 27, 2025 19:29
@zanieb
Copy link
Member Author

zanieb commented Jan 27, 2025

Additional commentary welcome, merging and we can iterate on it.

@BrewTestBot BrewTestBot mentioned this pull request Jan 28, 2025
Merged
tmeijn pushed a commit to tmeijn/dotfiles that referenced this pull request Jan 29, 2025
@tmeijn
build(deps): update astral-sh/uv to v0.5.25
685a036 
This MR contains the following updates:

| Package | Update | Change |
|---|---|---|
| [astral-sh/uv](https://github.com/astral-sh/uv) | patch | `0.5.24` -> `0.5.25` |

MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot).

**Proposed changes to behavior should be submitted there as MRs.**

---

### Release Notes

<details>
<summary>astral-sh/uv (astral-sh/uv)</summary>

### [`v0.5.25`](https://github.com/astral-sh/uv/blob/HEAD/CHANGELOG.md#0525)

[Compare Source](astral-sh/uv@0.5.24...0.5.25)

##### Enhancements

-   Allow installation of manylinux wheels on loongarch64 ([#&#8203;10927](astral-sh/uv#10927))
-   Allow optional `=` for editables in `requirements.txt` ([#&#8203;10954](astral-sh/uv#10954))
-   Add Windows aarch64 to the release binaries ([#&#8203;10885](astral-sh/uv#10885))

##### Bug fixes

-   Use spec-compliant (`128+n`) exit codes for `uv run` and `uv tool run` on Unix ([#&#8203;10781](astral-sh/uv#10781))
-   Fix best-interpreter lookups when there is an invalid interpreter in the `PATH` ([#&#8203;11030](astral-sh/uv#11030))
-   Guard against concurrent cache writes on Windows ([#&#8203;11007](astral-sh/uv#11007))
-   Prioritize package preferences with greater package versions ([#&#8203;10963](astral-sh/uv#10963))
-   Reject `--editable` flag on non-directory requirements ([#&#8203;10994](astral-sh/uv#10994))
-   Respect `--no-sources` for `uv pip install` workspace discovery ([#&#8203;11003](astral-sh/uv#11003))
-   Set `JEMALLOC_SYS_WITH_LG_PAGE=16` in ARM Docker builds ([#&#8203;10943](astral-sh/uv#10943))
-   Update `riscv64` Python downloads to allow install on `riscv64gc` ([#&#8203;10937](astral-sh/uv#10937))
-   Fix file persist retries on Windows ([#&#8203;11008](astral-sh/uv#11008))
-   Fix incorrect error message when specifying `tool.uv.sources.(package).workspace` with other options ([#&#8203;11013](astral-sh/uv#11013))
-   Improve SIGINT handling in `uv run` ([#&#8203;11009](astral-sh/uv#11009))

##### Documentation

-   Add `SECURITY` policy ([#&#8203;11035](astral-sh/uv#11035))
-   Add `Requires-Python` upper bound behavior to the docs ([#&#8203;10964](astral-sh/uv#10964))
-   Add a troubleshooting section and reproducible example guide ([#&#8203;10947](astral-sh/uv#10947))
-   Add documentation for `uv add -r` ([#&#8203;10926](astral-sh/uv#10926))
-   Amend `requires-python` rules in resolver documentation ([#&#8203;10993](astral-sh/uv#10993))
-   Reference workspaces in `--no-sources` documentation ([#&#8203;10995](astral-sh/uv#10995))
-   Update documentation for activating virtual environments in different shell ([#&#8203;11000](astral-sh/uv#11000))
-   Add Docker SHA pinning tip ([#&#8203;10955](astral-sh/uv#10955))

</details>

---

### Configuration

📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined).

🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied.

♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox.

🔕 **Ignore**: Close this MR and you won't be reminded about this update again.

---

 - [ ] <!-- rebase-check -->If you want to rebase/retry this MR, check this box

---

This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).
<!--renovate-debug:eyJjcmVhdGVkSW5WZXIiOiIzOS4xMzcuMiIsInVwZGF0ZWRJblZlciI6IjM5LjEzNy4yIiwidGFyZ2V0QnJhbmNoIjoibWFpbiIsImxhYmVscyI6WyJSZW5vdmF0ZSBCb3QiXX0=-->
styvane added a commit to styvane/uv that referenced this pull request Jan 29, 2025
@styvane
Merge branch 'main' into fix-8743
c165629 
* main: (22 commits)
  fix async windows file persist retries (astral-sh#11008)
  Respect `--no-sources` for `uv pip install` workspace discovery (astral-sh#11003)
  Remove unnecessary distribution clone (astral-sh#11004)
  Properly format test publish error (astral-sh#11001)
  Reject `--editable` flag on non-directory requirements (astral-sh#10994)
  Add a troubleshooting section and reproducible example guide (astral-sh#10947)
  Update documentation for activating virtual environments in different shell (astral-sh#11000)
  Improve publish test script resilience (astral-sh#10984)
  Update `compile_enumerate_no_versions ` snapshot (astral-sh#10998)
  Reference workspaces in `--no-sources` documentation (astral-sh#10995)
  [docs/integration/docker] add sha pinning tip (astral-sh#10955)
  Update name of "Build binary" job to highlight that these are the "release" binaries (astral-sh#10990)
  Use install action for cargo shear (astral-sh#10983)
  Update Rust crate rustix to v0.38.44 (astral-sh#10974)
  Update Rust crate fs-err to v3.1.0 (astral-sh#10976)
  Update pre-commit hook astral-sh/ruff-pre-commit to v0.9.3 (astral-sh#10975)
  Update Rust crate rkyv to v0.8.10 (astral-sh#10973)
  Update Rust crate jiff to v0.1.27 (astral-sh#10972)
  Update Rust crate insta to v1.42.1 (astral-sh#10971)
  Update Rust crate clap to v4.5.27 (astral-sh#10970)
  ...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@edmorley edmorley edmorley left review comments

@konstin konstin konstin left review comments

@Gankra Gankra Awaiting requested review from Gankra

@charliermarsh charliermarsh Awaiting requested review from charliermarsh

Assignees
No one assigned
Labels
documentation Improvements or additions to documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@zanieb @edmorley @konstin