search

spacedentist / spr

Submit pull requests for individual, amendable, rebaseable commits to GitHub
https://getcord.github.io/spr/
MIT License
392 stars 41 forks source link

Add a reference to how it works for simple PRs #126

Open joneshf opened 2 years ago

joneshf commented 2 years ago

This can be helpful to understand what's going on under the hood.

I was trying to explain how spr works to a coworker and it got kind of confusing. I went looking for an explanation, but didn't see one. So, I decided to throw this together in case it would be helpful for anyone else.

This is based on my understanding of what happens from both using spr and from reading the code. This might not be the most accurate thing, so any improvements are welcome.

This uses the Gitgraph diagram of Mermaid.js to show what happens with git. This should render on GitHub, since they added support for Mermaid.js not too long ago.

Since the spr website uses mdBook, it should be possible to use the mdbook-mermaid preprocessor to render these diagrams as well. However, I haven't tested this yet personally.

If there's a want for this kind of documentation, explaining how the stacked workflow works will probably be even more useful. It's a bit more complex, so understanding that can be very helpful to know what's happening. I didn't add that right away, since it's a non-trivial amount of work so I wanted to make sure this kind of documentation is even wanted first.

Test Plan: This is documentation, so aside from it making sense and being wanted the test is whether or not it renders properly.

sven-of-cord commented 2 years ago

This is good stuff. Sorry, I haven't had little time lately for spr. I'm about to go on vacation for a week and a half. Will be back in the office in September, and reserve some time for spr. On this PR, we should make it so that it renders correct in the book. I had a quick go at it, and it worked nicely just by installing mdbook-mermaid and adding it to book.toml. The thing I haven't had time to look at is what a good way is to get that extension in the GitHub workflow. Currently I'm using an action that installs a binary build of mdbook from somewhere, but not sure if we can get that for mdbook-mermaid. Maybe we have to install Rust and cargo install...

adamdicarlo0 commented 1 year ago

Super helpful for me, checking out the repo and thinking about trying spr.

It seems like the workflow ends up being similar to using Gerrit? The simple case for gerrit looks identical, client-side. The only difference, I think, is that Gerrit's git server understands that an amended commit is actually version 2 of a change set. (But only because of a special identifier inserted into the commit message -- all changes get pushed to the same remote ref with Gerrit. Really a virtual ref, I guess.)