Thanks for the reply. What do you think turns people off documentation? I hear about doc rot etc. Sounds like you've really seen the light. One of the issues I've had with docs is that they are quite non-visual, I tend to diagram quite a lot to get a sense of how things hang together.
Docs can include pictures, even rudimentary ones made in the simplest drawing tools.
Programmers don't like writing docs because it's work, not fun like having code. In some companies that's "someone else's job" which is terrible.
When youre young you think you'll remember every line of code you ever wrote. (Spoiler alert, over a 40 year career you'll write a LOT of code).
Code is just code. Docs make the code usable. I get paid when the code is used (well, purchased) so my incentives were clear. Plus it makes customer support a Lot easier.
Yeah nice! I have a gridded moleskine for the same purpose. Trouble is I tend to just write notes as I go and then not really refer back to them. Effectively an ephemeral scratch pad.
This is a really interesting set of insights. I definitely see the theoretical benefits of stacking but as you indicate it feels like it requires a pretty good grip of git to manage. Do you have tooling to support with this in your team? To your last point, so let's say you've got 5 stacked PRs chained off of each other, you then need to merge master into each of them individually?
On a previous team we did create a wrapper command around git which did the parent-child branch tracking and added some convenience commands. On my current team we don't and it's OK because conflicting changes are rare so merging in from master is infrequently necessary and our code review tool can't make effective use of the extra stack information anyways.
Suppose you have the stacked PRs in the following sequence: A, B, C, D, E, F
If you implement stacked PRs using branches in git, then they will be a series of branches. For example, A will be a child branch of master, and B a child of A. To bring new changes in from master all the way down to F requires at least three commands and a build per stack member:
git fetch
git checkout A
git merge master
build_and_run_tests
git checkout B
git merge A
build_and_run_tests
git checkout C
git merge B
build_and_run_tests
...
Failure to do this for every PR in the stack tends to create confusing diffs in the code review system. For example, if you only merged the changes from master as far as C, then the code review system will probably try to show the diff between D and C:head which will contain the removal of a bunch of new master code. The code review really should be showing the diff between D and C:d_merge_base, but some code review tools don't support that and others need help, like the wrapper tool I mentioned previously.
The wrapper was named "gut". I don't recall all the details so the names below are approximate. It wrapped the git command and added project-specific options (like --first-parent) to existing git commands, introduced new ones (like "gut check" which ran the build and tests), or hid native git command which were discouraged (like rebase).
"gut sync" merged in all the changes from the branch's parent into a single child branch, fetching if appropriate. We never got around to automating sequential syncing since the CI setup was weak in this project.
"gut create" created a new cascaded branch with the necessary tracking information from an arbitrary parent branch.
"gut review" posted the cascaded branch to the code review system so the diff would turn out correct.
"gut pdiff" would show the diff of the branch relative to the merge-base of the parent.
"gut reparent" would change the parent of a branch.
"gut insert" would insert a new cascaded branch between two existing branches -- useful for inserting refactors earlier in the series.
"gut merge" which merged the branch into the parent only once various checks, like review approval and passing tests and being at the head of the stack, were satisfied.
Nice that sounds like a really neat workflow. I haven't used stacked PRs before, I feel like everywhere I've worked has generally been: work on a feature, PR/MR the branch and try to keep it small. Any idea what it isn't more common?
there are like 3 devs that don't like it because they are used to the github way of doing things, they always have the github tab open and prefer not to have notifications in slack.
We disabled pullpo for these people. However they can still collaborate with the people that use pullpo. The comments they send to github are brought to slack too and viceversa.
Yeah I did a bit of a deep dive on Pullpo - it looks great, small passionate team! I was curious if there is anything that you don't like about using it as part of your workflow? Like I can see your colleagues prefer a specifically different type of workflow - why did your team adopt it?
That's awesome! Can I ask what sort of feedback you were getting that lead to CodeApprove. I agree that sitting with the incumbents shouldn't be our default setting, curious about which parts you are trying to improve?
I was actually in charge of a large open-source effort at Google (75 repositories, dozens of internal devs, hundreds of contributors) so I had a very unique position of being able to watch Googlers attempt to use Google engineering practices on GitHub.
For the most part they loved the open-source work (a lot more flexibility than internal systems) but they all complained about the code review! It just didn't give them the same rapid drive to consensus they got with Google's internal tools. And I think they were right.
So after I left Google I was very inspired to work on a better code review system for developers on GitHub. And that's how CodeApprove was born!
Hey, thanks so much for the kudos. This is a solid point. I'm going to talk with the team about prioritising an export function.
Each CodeNote is essentially a node of links to that code (and conversations about that code) in other places: VCS Hosts, editors, Slack etc. The generated VCS Host and Slack permalinks are not dependant on us. So we can, at least, create a dump of those in short order.
We use websockets to locate the code in editors, but could easily downgrade these to protocol links (e.g. `vscode:`) that are independent of us also.
What format would be most useful for the dump to be in? JSON, CSV, markdown ...? I'm thinking JSON just from a data organisation perspective?
