The recipes are about how one would map git's commands and options to pygit2's methods. Since we do have listall_branches() which takes the flags, we should rather update the recipe to show what -r and -a would look like.

But is this really the purpose of a recipe? The documentation of listall_branches() only says that it takes flags, but not, which flags and what they mean. That has to be fixed, for sure. (I wanted to do it myself, but couldn't find it out by just looking at the method's source code. I could dig deeper, of course, but that would be a waste of time, since someone else probably already knows it.)

So suppose we have proper documentation on listall_branches(), wouldn't it be fairly redundant to write this down again as a mapping from git command to Python source? I mean, if you want to list only remote branches and the search for "list remote branches" leads you to the documentation for listall_branches() and its flags instantly, what do you need the recipe for?

In my opinion (and sorry for intruding, since I haven't contributed anything else to this project), a recipe should only be written if the user isn't immediately able to find out how to do something. For example, if she wants to do X and X involves several method calls that have to be searched individually and are tricky to put together in the correct order, a recipe would be necessary.

The flags are described here https://libgit2.github.com/libgit2/#HEAD/group/branch/git_branch_iterator_new

The recipes have received very little attention overall. I myself prefer to work on the reference.

Maybe we should move the recipes to the wiki, https://github.com/libgit2/pygit2/wiki
Avoiding the PR cycle would low the barrier to contributors, maybe that way the recipes would receive more attention and be in a better shape.

What do you think?

I guess this question is directed to the general public and not to me specifically? Because I'm not a regular contributor to pygit2 and I'm not planning to become one. Anyway, I do think that you could be right. PRs are a barrier (for a good reason, though) and putting the recipes on the wiki is worth a try.

So I could start it off by improving the documentation on listall_branches() and putting some first recipe on the wiki.

On the other side, having the documentation in the sources makes offline consulting way easier.

That's an interesting objection. However, if offline consulting really is important, one could just clone the wiki to the local machine.

But having them in the source mean you have the right version.
One can download an older version of the pygit2 and still have the appropriate documentation.

Okay, let's say we leave the recipes with the source. What is your opinion about the original subject then? And everyone else's opinion. I mean, we still have the outdated recipe and the incomplete documentation (focusing on listall_branches) and I'm not sure what to do with my pull request.

First, there's the question of what is a recipe. There are two answers so far.

The idea about mapping Git commands to the API. This is the approach of libgit2sharp, see https://github.com/libgit2/libgit2sharp/wiki/LibGit2Sharp-Hitchhiker%27s-Guide-to-Git (but they also state: we currently lack proper documentation, see https://github.com/libgit2/libgit2sharp/wiki#documentation).

In my opinion such approach would lead to duplicated information, both in the recipes and the reference, twice the work to maintain. The reference is already supposed to include examples to illustrate the API.

I agree with the @rmoehn description of what a recipe should be, the kind of stuff you find in a cookbook style book. So straightforward recipes should be removed. But if they contain any information not yet in the reference, then such information should be put in the reference first.

The pull request mechanism surprised me again, but I think it's okay like that.