(not strictly a bug but I felt this was the most fitting category)

The how-to section for declaring new hooks suggests xdist as an example, but links to an old commit.

Besides a change in project layout, the main difference I can see is that the current version marks the hook specs explicitly with @pytest.hookspec. From what I understand, this is not strictly necessary, and pytest will still detect hook specs by name, but will raise a deprecation warning if old-style markers are used for customizing the spec (e.g. for setting firstresult).

Assuming the old link is not intentional, would it be better to link to the master version instead of that hardcoded commit? (although I appreciate this adds a maintenance cost if they diverge again)

Similarly, should the guide more explicitly suggest the use of @hookspec? Or is that only intended for specs with non-default behaviour, and the general intention is to mostly rely on detection via the pytest_ prefix ? (and similarly for @hookimpl, which is shown in more examples but not always)

I'm happy to put in a PR for the docs page but not sure what the expected usage is!