look into patch theory #39

Open
aspiers opened this Issue Feb 7, 2015 · 7 comments

Comments

Projects
None yet
2 participants
@aspiers
Owner

aspiers commented Feb 7, 2015

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

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

@aspiers aspiers added the help wanted label Feb 7, 2015

@waldyrious

This comment has been minimized.

Show comment
Hide comment
@waldyrious

waldyrious Apr 11, 2017

@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 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

This comment has been minimized.

Show comment
Hide comment
@aspiers

aspiers Apr 11, 2017

Owner

@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.
Owner

aspiers commented Apr 11, 2017

@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

This comment has been minimized.

Show comment
Hide comment
@waldyrious

waldyrious Apr 11, 2017

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

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 commented Apr 11, 2017

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

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

This comment has been minimized.

Show comment
Hide comment
@waldyrious

waldyrious Apr 11, 2017

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.

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

This comment has been minimized.

Show comment
Hide comment
@aspiers

aspiers Feb 10, 2018

Owner

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.

Owner

aspiers commented Feb 10, 2018

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 aspiers added documentation and removed documentation labels Feb 10, 2018

@aspiers

This comment has been minimized.

Show comment
Hide comment
@aspiers

aspiers Feb 10, 2018

Owner

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

Owner

aspiers commented Feb 10, 2018

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

@aspiers

This comment has been minimized.

Show comment
Hide comment
@aspiers

aspiers Feb 10, 2018

Owner

Filed as #69.

Owner

aspiers commented Feb 10, 2018

Filed as #69.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment