docs: Add FAQ on reasons for need to downgrade dependencies

[matthewfeickert]

Description

Resolves #1513

Add FAQ explaining how reasons why users might have to manually downgrade dependencies.

Checklist Before Requesting Reviewer

• Tests are passing
• "WIP" removed from the title of the pull request
• Selected an Assignee for the PR to be responsible for the log summary

Before Merging

For the PR Assignees:

• Summarize commit messages into a comprehensive review of the PR

* Add FAQ explaining how reasons why users might have to manually downgrade dependencies.
   - c.f. PR #1979 for context

[codecov]

Codecov Report

Base: 98.28% // Head: 98.28% // No change to project coverage 👍

Coverage data is based on head (a6ff6dc) compared to base (8c5d930).
Patch has no changes to coverable lines.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #1529   +/-   ##
=======================================
  Coverage   98.28%   98.28%           
=======================================
  Files          68       68           
  Lines        4479     4479           
  Branches      730      730           
=======================================
  Hits         4402     4402           
  Misses         45       45           
  Partials       32       32           

Flag	Coverage Δ
contrib	27.61% <ø> (ø)
doctest	61.30% <ø> (ø)
unittests-3.10	96.22% <ø> (ø)
unittests-3.7	96.20% <ø> (ø)
unittests-3.8	96.24% <ø> (ø)
unittests-3.9	96.27% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

☔ View full report at Codecov.
📢 Do you have feedback about the report comment? Let us know in this issue.

[matthewfeickert]

@alexander-held @henryiii if you also have time to let me know if this seems clear (and not too verbose) that would nice.

[alexander-held]

This looks good to me and seems helpful to have. What do you think about adding the required pip command for the example? Something like

python -m pip install --upgrade "click<8"

for the click example. Maybe being very explicit here could help users who are getting started with Python and have not had to deal with specifying versions before. On the other hand, this is not a Python tutorial so it also seems reasonable to not go into that detail. The instructions can be found elsewhere on the internet.

[henryiii]

To me this looks more like a bug in Click that happened to get added in version 8 than an intentional change. Once it's discovered I think you might want to do a bug report to Click. I'm not sure a document like this is all that useful; this is mostly not specific to PyHF, or any other library that has dependencies. If you depend on something, that something could change - or even just not work on a new platform. Even one that "caps" all dependencies is susceptible to bugs creeping into dependencies, etc. If you provide a "known working version lockfile" perhaps, but in general, as long as the library is being actively developed, this shouldn't be a problem.

[matthewfeickert]

Maybe being very explicit here could help users who are getting started with Python and have not had to deal with specifying versions before.

@alexander-held This is somewhat the reason that I put them in a requirements.txt as an example to indicate that there was a relationship between them. I'd probably prefer to not give too many commands here though.

To me this looks more like a bug in Click that happened to get added in version 8 than an intentional change. Once it's discovered I think you might want to do a bug report to Click.

@henryiii if you have time can you elaborate a bit more on this (or maybe over on Issue #1506)? There was some past discussion on the IRIS-HEP Slack where it seemed like this was our fault due to using a weakref.

If you depend on something, that something could change - or even just not work on a new platform. Even one that "caps" all dependencies is susceptible to bugs creeping into dependencies, etc.

Here you're talking about users needing to be responsible for controlling their own dependencies for an application, correct? If so, that is what I was trying to convey.

If you provide a "known working version lockfile" perhaps, but in general, as long as the library is being actively developed, this shouldn't be a problem.

I agree that most of the time it shouldn't be an issue, but we're running into this now and while we've been busy with conferences the last few weeks pyhf is decently actively developed and Alex's original issue is well over two weeks old at this point (though this is also the first time we've run into something like this).

[matthewfeickert]

Relevant RTD page: https://pyhf--1529.org.readthedocs.build/en/1529/faq.html#i-installed-an-old-pyhf-release-from-pypi-why-am-i-getting-an-error-from-a-dependency