Remove obsolete git-branch recipe #465
Conversation
The git-branch recipe says: »Note that the next release will probably allow repo.listall_branches().« Concluding from the README, Repository.listall_branches() was included in some release prior to 0.20.0, so at least that statement is obsolete. However, since pygit2.org brings up fairly accurate results for a search on »list all branches«, I figured that the whole recipe isn't needed anymore. Therefore delete it.
|
The recipes are about how one would map git's commands and options to pygit2's methods. Since we do have |
|
But is this really the purpose of a recipe? The documentation of So suppose we have proper documentation on 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 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 |
|
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. |
|
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 |
|
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. |
Add a description of the possible flags and turn the "tuple" into a "list", as it had already happened in code and part of the documentation in aa5877e.
|
The pull request mechanism surprised me again, but I think it's okay like that. |
The git-branch recipe says: »Note that the next release will probably
allow repo.listall_branches().« Concluding from the README,
Repository.listall_branches() was included in some release prior to
0.20.0, so at least that statement is obsolete.
However, since pygit2.org brings up fairly accurate results for a search
on »list all branches«, I figured that the whole recipe isn't needed
anymore. Therefore delete it.
(If my messing with pull requests bothered you, sorry for that. I was a bit confused about how to correct a pull request, but I get it now.)