Enable the wiki

[pfmoore]

What's the problem this feature will solve?
There are some aspects of pip which deserve an extended discussion, where information is currently scattered across various issues, online forums, etc. Having a single location where users can find this sort of information would be beneficial, as it would make it easier to avoid having to answer the same questions repeatedly.

Describe the solution you'd like
We could enable the wiki functionality here and use that for such documents. I'd suggest keeping the structure very flexible, initially just a series of pages, linked from the home page. If we get enough documents, we can add structure later.

Some examples of topics that would (IMO) be reasonable to cover here:

1. Common upgrade issues (the sorts of things covered in ImportError in system pip wrappers after an upgrade #5599).
2. A discussion of the resolver's backtracking logic and the constraints it works under (a response to comments like https://twitter.com/codewithanthony/status/1402426117202485249, which is what prompted me to think of this).

I'm thinking of content like design background - why a particular feature works the way it does. A lot of that currently ends up being scattered around PR discussions and in people's heads.

Honestly, it doesn't have to have a lot of content - even if there's only a couple of items that's fine (IMO).

Alternative Solutions
The obvious alternative would be to put this sort of information in the documentation. But the docs are already quite large, and the structure is fairly fixed, with no obvious place where such information would go. So the barrier to adding a discussion is a lot higher (to be specific, I probably wouldn't add something to the docs in a lot of cases where I'd happily write a "blog-style" discussion post).

It's also something that could be put on a personal blog. But keeping things together has some benefit. (Also, I don't personally have a blog...)

Additional context
We'd need to make sure not to end up with this looking like we're being defensive about pip's behaviour - the articles should be about cases where there's genuinely no "ideal" answer that we can see, and where the reasons why "obvious" options don't work as well as people might immediately think.

I don't know how permissions work on the wiki. We'd want to allow the community to offer updates but still retain editorial control, so we can fact-check the information there (as it would be a fairly official source of information).

[DiddiLeija]

I agree with @pfmoore .

Another point in favor of GitHub wikis, is the possibility of making a footer (named _Footer) and a sidebar (named _Sidebar) to customize.

I don't know how permissions work on the wiki.

Me neither. But I can investigate on the documentation, and later I will tell you what I found.

[DiddiLeija]

I only found this page about editing the wiki permissions on the GitHub docs:

https://docs.github.com/en/communities/documenting-your-project-with-wikis/changing-access-permissions-for-wikis

[pfmoore]

Thanks. So pip developers only by default, which sounds like what we'd want. But I don't know if non-committers can make edits and submit them as PRs. Not a big deal - if it's not possible then so be it. (I suspect it is, though).

[DiddiLeija]

But I don't know if non-committers can make edits and submit them as PRs. Not a big deal - if it's not possible then so be it. (I suspect it is, though).

Maybe we can try. But I don't really think they will be able to submit them as PRs, because the wiki files are not part of the repository code (well, that's what I understand).

[pradyunsg]

I'm inclined to say that we should just have this in pip's existing documentation as-is. We already have established skeleton for all of it, and there's not really much that we'd need to change to accommodate such content.

We'd want to allow the community to offer updates but still retain editorial control

This isn't possible sadly. The way Github's wiki works is that we choose one of:

• Non-committers won't be able to make PRs or suggest improvements directly.
• No restrictions and anyone can make edits.

It's a toggle between "wiki with no moderation" and "set of pages written by the committers that you can't easily contribute to".

But the docs are already quite large, and the structure is fairly fixed, with no obvious place where such information would go.

FWIW, making it easier to cover things like this in the documentation rewrite is something that I want to make possible through #9474.

• The "constraints of pip's XYZ design" would belong under Architecture section from Documentation rewrite (Q1 2021) #9474.
• "Common upgrade issues" would be a part of the (planned new) "common errors" section, which would also be something that's optimised for SEO on those terms.

the barrier to adding a discussion is a lot higher

If it helps reduce the barriers, I'm a 100% fine with a bunch of these pages just being dumped in the documentation under a new "Kitchen Sink" section - a place to put all the things we think are useful to note and might need to clean up a bit before moving them to a "proper" place in the documentation.

I also want to note that we have literal brain dumps in our existing documentation (see https://pip.pypa.io/en/stable/development/architecture/overview/ and https://pip.pypa.io/en/stable/development/architecture/anatomy/) so the bar for what we add there in general is honestly not that high right now.

[DiddiLeija]

We already have established skeleton for all of it, and there's not really much that we'd need to change to accommodate such content.

I didn't know. But if extending the documentation is easier than creating a wiki, just go ahead. I just recommended the wikis because I thought they were easier to edit and maintain than the pip's documentation.

[uranusjr]

Does anyone know how GitHub wiki works for editors (rolling back contributions, allow flagging, block inappropriate usages, etc.). To me, a wiki is most valuable when it can be edited by almost everyone and reflect real-time changes. If it requires maintainers to merge changes, it is basically just another place to host pip’s documentation, and would only increase confusion (where do I find the correct content?) rather than avoid. So I’m +1 only if the wiki is both open by default and offers a good enough audit mechanism, otherwise -0.

[pradyunsg]

Oh, if we're putting numbers, then I'm a -1 on enabling the Wiki.

Does anyone know how GitHub wiki works for editors (rolling back contributions, allow flagging, block inappropriate usages, etc.)?

I do! toml-lang/toml has had a Wiki since before I got involved. There is no moderated-wiki style here - it's either "free for all" or "locked down to only folks with the Write bit". For TOML, I take a look at it every few months (when I see that someone made edits when I go to the GitHub home page) and validate the changes.

I don't think that'd work for pip, since I expect an order of magnitude more traffic on pip's Wiki compared to TOML's, and as I said above, I don't see much point in something like that over our existing docs workflow. You already mentioned the "where do I put this" concern. :)

As a fun little "maybe interesting" fact , the Wiki itself is actually just an additional git repository.

[uranusjr]

So for free for all, there’s no way to block someone, or at least some UI tools to easily review and roll back past changes? That would not work :(

[pfmoore]

I'd only be interested in maintainer-only, and given the general view here, I guess that's not going to happen. I completely concede that my main reason for wanting it was to host stuff that could go in the docs but isn't an obvious fit¹, combined with the fact that I'll write stuff in a Github-style markdown UI relatively happily when I have a spare moment, whereas I find writing docs (editing offline without a good preview, having to use a Sphinx edit-build cycle, needing a pip checkout, branch/commit/PR/merge cycles, etc) way too much effort so I'll essentially never bother.

So I think I'll drop this idea - thanks for the responses.

¹ In the case I had in mind, "Explanation" style documentation using the categorisation from here, which doesn't have an obvious "home" in our current docs structure.

[pradyunsg]

FWIW, if you have a pip checkout, nox -s docs-live should give you a fairly decent writing experience for pip's documentation. That's basically how I've been writing #9475 stuff, and I think it works pretty well. :)

[pfmoore]

I'm going to close this, as it seems like people are generally not in favour.

I will note that one of my original motivations was "write up something about how the resolver works". My progress on #10247 might explain why I thought a wiki page might be useful for that 😉