look into patch theory

[aspiers]

There is quite a lot of prior art in the area of patch theory (in particular from the darcs community), e.g.

• http://darcs.net/Theory/Motivation
• http://en.wikibooks.org/wiki/Understanding_Darcs/Patch_theory and subsequent pages
• http://darcs.net/Theory/Questions
• http://darcs.net/Theory/MergersDocumentation
• http://darcs.net/Theory/GaneshPatchAlgebra
• ftp://ftp.math.ucla.edu/pub/camreport/cam09-83.pdf
• https://github.com/tummychow/git-scripts/blob/master/git-absorb.md#interlude-patch-theory

We should look into these and see what can be applied to git-deps.

[waldyrious]

@aspiers I suspect some background on git-deps would be necessary for others to help out in this task -- plus, it would be a net positive either way, documentation-wise.

Do you think you could provide a brief summary of git-deps's architecture (conceptual overview) and inner workings (implementation notes), either in README.md or CONTRIBUTING.md?

[aspiers]

@waldyrious I'd be happy to try to help improve the docs. Could you give me some hints on more precisely what you think is missing? I thought that the README.md already did a reasonable job, with its "Background theory" section, plus the screencasts, plus the link to the GitMinutes episode, but I acknowledge more could be added. Are you talking about information like the following?

• git-deps is a CLI tool which enables
  • interactive usage via a shell
  • non-interactive usage from other programs
  • a standalone Flask web server which serves interactive visualisations of commit dependency trees via a web browser
• git-deps interacts with git repositories via pygit2, which uses libgit2 under the hood
• More in-depth explanation of the dependency detection algorithm. The heart of the algorithm is already well commented and should be quite readable, but yes it could be documented. IIRC I also explained it in the podcast.
• I'm working on converting the whole thing to a proper Python module but haven't yet figured out a good way to bundle a bunch of npm modules within a Python module build, in a way that they're servable from Flask at run-time.

[waldyrious]

I listened to the GitMinutes episode after writing the comment above, and in the notes there is something that would be useful:

Technologies used in git-deps

• https://github.com/libgit2/pygit2
• http://d3js.org/
• https://github.com/tgdwyer/WebCola
• https://github.com/cpettitt/dagre
• http://flask.pocoo.org/

IMO, it helps to present information in this kind of layered way: a very brief and high-level overview first, with links to further details later in the same document or in a separate document. In this case, presenting just the list of technologies upfront is good to give people an idea of both the complexity they can expect from the project before diving in, and whether they're familiar with any of the pieces involved.

More notes on what I think would be useful:

• It's good that the README leads with the demonstration video, which does a great job at explaining what git-deps is about and what one can expect from it. Your summary ("git-deps is a CLI tool with enables...") would complement it nicely.
• The README is too long for a comfortable first read, IMO. Perhaps the motivation section could be moved to a separate document.
• The installation process seems quite involved. Something simpler would lower the barrier for experimenting with the tool, resulting in more users and potential contributors. I suppose the conversion to a module would indeed make great strides towards this.
• It's great that you documented the code extensively, but it is not comfortable to read that way. I'd love to see the code documentation rendered using pycco or some similar approach.

Let me know what you think :) I am at best a curious layman when it comes to Python programming, but I could help out with the other tasks like README splitting, etc. Or, with some guidance, I'd love to tackle the pycco stuff.

[waldyrious]

ps - yes, the "background theory" in the README provides a nice overview of the main ideas behind git-deps, but I can't help but feel it contains an awkward mix of abstract descriptions (the first and last paragraphs) and concrete/implementation-specific information (the two middle paragraphs).

I guess the fact that the second paragraph starts as if it is going to continue in the same level of abstraction as the first one, but then shifts gears into implementation details, threw me off a little.

[aspiers]

Thanks a lot for the great suggestions and really sorry for the incredibly slow response! I agree with everything you wrote, and would gladly welcome the help with improving the docs, even if you aren't inclined to touch the code.

[aspiers]

Having said that, I just remembered that this issue is about patch theory, not docs :-) I'll open another one about your suggestions.

[aspiers]

Filed as #69.

[aspiers]

See also https://github.com/tummychow/git-scripts/blob/master/git-absorb.md#interlude-patch-theory