On my first day at Trello, my peer mentor showed me two things. One of them ended up being the topic of my talk on Reactive Programming. The second thing he told me was, on our team, PR’s should tell a story.

Then we pair constructed a PR. To be clear, he was already in a local branch, and the code was already written and committed.

He showed me how he used git reset and git rebase to rewrite the commits. He explained that he was rebuilding the commits to make the PR easy to review. He constructed each commit to be atomic—to do a single coherent thing.

This was the PR style for our team for the whole time I worked there. The goal of a PR was to make it easy to review, and we expected reviewers to open each commit in a tab and review them one-by-one. We considered it acceptable to decline a PR if it was too big or hard to review (in practice, this happened very infrequently).

Other practices:

1. PR’s were mostly less than five commits. If they were more, it was because each commit was tiny.
2. Commits were tiny because we wanted them to be atomic—only one idea. For example, if I saw a spelling error in a comment, it would be its own commit. If I renamed a function, the rename refactor would be its own commit.
3. Most PRs were merged within hours of being opened. Many even sooner.
4. This is true even though we required 2 reviewers per PR.
5. It only took 10-20 minutes to review a PR
6. If PRs were big, we’d do a “Live review” over zoom to go back and forth quickly
7. Single Jira tickets that required a lot of code were PR’d in parts.
8. Almost every review comment was pointing out a blocking defect (or possible ones), not nitpicks.
9. If the code changed the UI, we’d attach before and after screenshots.

These practices helped us, but the important part is our team mindset that PRs were constructed to be easy to review.

The Liskov Substitution Principle is an Object-Oriented class design guideline that says that a sub-class should be substitutable for a super-class and that clients to the super-class should not be impacted.

You achieve this by specifying a contract for each public method of a class.

First, you specify a pre-condition/requirement.

If the caller meets the requirements, then the method makes a promise of a post-condition and result.

A sub-class is substitutable if it makes the same promises under the same requirements. It is also substitutable if it can make the same promise with fewer requirements. And, finally, it’s still substitutable if it makes more promises.

So, sub-classes can require less and promise more than the specification of their super-classes. But, they can neither require more nor promise less.

Some OO languages, like Eiffel, have ways of encoding the contract, but in Swift and many other languages, this is something usually stated in documentation.

But, substitution is not just an OO principle, or at least, I don’t only apply it to super/sub class relationships. I think it should be applied to versioning of any public library of any kind of code (OO, functional, whatever). To do this, think of vNext as a subclass of vCurrent.

So, vNext can require less and promise more. It can’t:

1. Add new required parameters to a method
2. Add exceptions to methods that didn’t have them before
3. Change the name of a method
4. Change the return type unless the new type is substitutable
5. Change parameter types unless the old type is substitutable
6. Add new required methods to a prototype

Unfortunately, many languages would think of some acceptable changes as a compile-time breaking change. For example, in Swift if a method returned T? and you changed it to return T, then callers that used guards would not compile. Strictly speaking, T is always substitutable for T?, but you should not do this change.

This is not how many library authors think, Instead, I think we’ve been corrupted by semantic versioning and the idea of acceptable breaking changes. Under substitutable versioning, there is no such thing as a breaking change.

Under semantic versioning (major.minor.patch), most library providers only think of patch version increases as being substitutable and for sure major version increases are not. I would say in practice, minor version increases are sometimes breaking.

In a fully substitutable versioning system, this would never be the case. vNext would always be substitutable for vCurrent. This means that:

1. Old classes and methods could be marked as deprecated, but are never removed.
2. Things that would be changed in major versions are done in new namespaces or with new class names.
3. To plan for this, perhaps the original namespace would use a versioning scheme.
4. Any client that compiled and worked with an old version would compile and work with a new version.

To be clear, if clients write to implementations and not specifications, they might break with future versions, so documentation needs to clearly explain what is required and promised. The actual behavior should not be confused with the contract.

A common example of this is relying on buggy behavior. If I call a method and it has some bug, I might write code to work-around that bug. If a future version fixes the bug and my software breaks because of my work-around, that’s still considered a substitutable change as the bug was not a promised behavior.

In a talk on clojure specs, Rich Hickey called this concept accretion and railed against breaking change. I know that semantic versioning is too entrenched right now to change, but something like what Rich is describing would do a lot to relieve dependency hell.

I started a podcast about a week ago and the first episode was an exercise that helped me overcome writer’s block. In the episode I said that I don’t get “coder’s block”.

This is more or less true, but I want to elaborate. I don’t mean that I can instantly solve any bug or program anything I want at will. I mean that I can make progress and do something.

When I have a problem I need to solve and literally have no idea what to do next, here are a few things that help.

1. Write down everything you know about the problem
   1. Assumptions
   2. Goals
   3. Constraints
2. Share this document with colleagues or talk to them about it.
   1. Are the assumptions and goals correct?
   2. Can a constraint can be loosened?
3. Do experiments to learn more and update your document
   1. Automated tests and scripts that help reproduce the issue
   2. User tests or analytics
   3. Diagnostic logging
4. Think bigger: Is there a fundamental problem that, if solved, makes this problem go away
5. Think smaller: Can you solve a subset of the problem

And, sometimes it’s right to put a hard problem on the back burner and come back to it later.