With permissive licenses, someone can take the code and make proprietary modifications to it and sell it to other people without releasing the modifications. We want people to publish their improvements, right?

With copyleft, we can force people to publish their improvements to copyleft code. Businesses will want to use our code because creating it was so much work in the first place. We need copyleft if we want more contributors, more open source, more code re-use, more freedom.

Right?

Wrong.

In this post, I break down all the ways copyleft licenses fail to achieve their stated goals, and explain why permissive licenses succeed where copyleft fails.

Background

(Skip this if you already know the difference between permissive and copyleft licenses.)

Open source licenses were created for important reasons: To protect the author, to protect the contributors, and to protect the consumers. This is achieved through codifying rights regarding redistribution, derived works, discrimination, and disclaimer of liability/warranty. Perhaps most importantly, an open source license is designed around allowing us to “fork” a project while retaining all the rights in the license.¹

When picking an open source license, there’s two camps: Permissive licenses (like BSD, MIT, Apache-2.0) and copyleft licenses (like MPL, GPL, AGPL).

Permissive licenses give the author the same rights as the contributors and consumers. Everyone can do anything as long as the license is not removed from where it is. If you want to use permissively-licensed code in a proprietary program, go wild.

Copyleft licenses are different–they were created as an exploit of our intellectual property and copyright system, a kind of “virus” to combat our proprietary rights-reserved-by-default legal system. With copyleft licenses, derivative work is required to perpetuate the same license. The boundary of derivation varies between licenses. For example: MPL constrains at the “file” level, GPL is at the binary distribution level which can be bypassed with dynamic linking, AGPL is at the “network” level specifically to target SaaS usage.

There are many downstream repercussions of these details that I’ll discuss below.

Copyleft is asymmetric

(Please bear with me as I take a brief detour to explain this not-very-intuitive point that comes up again and again. It turns out the asymmetry of copyleft is a critical flaw relevant in many scenarios.)

In the construct of our society’s intellectual property law², the author retains copyright by default. If I write some code and don’t explicitly release my rights to it, then it is considered proprietary and owned by me by default. I don’t even need to write “all rights reserved”!

Having copyright over my code gives me the right to license it however I want. I can keep it proprietary, or I can make a custom contract to sell to a customer or another publisher, or I can release it under a common license template like an open source license.

When I commit code to a code repository with some open source license, I am consenting to include my code under the project license (which usually lives in the root of the repository and applies to the whole thing unless said otherwise). But because I still own the copyright to my work, I can also release the same code under a different license in a different repository.

This means as an author of some copyleft code, I have special rights that my users don’t have: I am allowed to use my code for proprietary purposes, but my users are not.³

Permissive licenses don’t have this asymmetry by virtue of giving everyone the right to use the code for proprietary purposes.

Okay, why is this important?

Custom-licensed copyleft code is a liability

Some projects choose copyleft licenses as a way to convince businesses to pay for a custom license.

On paper, this sounds rational: The code is available to review and even prototype against, but deploying to customers may cross the viral copyleft boundary and a business would choose to pay for a custom license from the maintainer to avoid relicensing their entire product.

For every dependency that a business pays for a custom license, it adopts a liability and creates another point of failure. Each dependency has the power to rug the business: They can choose not to renew the license next year, or they can choose to pivot the project in an incompatible direction, or they can refactor in a way that increases the copyleft boundary.

Most importantly, the business has no recourse!⁴

Recall that with permissive licenses, we all have the same rights: If a maintainer does something that doesn’t work for me, I can simply fork and continue using the code as I was before. I don’t lose any rights even if I was depending on a custom license before.

It is safer for a business to do a contract deal with a permissively licensed project!

With copyleft and a custom license, I don’t have the protection of retaining my rights if something goes awry. If my business model or infrastructure architecture is incompatible with the copyleft nature of the dependency, then my entire business is at risk.

Now imagine how much worse this could be at scale: Naively, it seems like a great idea “if all dependencies were copyleft and we automated licensing them” then these liabilities would compound exponentially.

Code is not a whole

There is a common assumption from copyleft-licensed projects that the consumer will use the project as a whole. This is incorrect on two fronts:

1. It’s very common for programmers to get stuck on a problem, see how another project solves it, and adopt their solution if the license permits. In many cases, this can be as small as a 20 line function that has a clever optimization. This is how much progress is made in software, rather than always reinventing the wheel poorly.
2. When a consumer uses a project wholesale, they’re not depending on 100% of the code in the repository. For example, I may only be using 20% of the features a project implements, and I may never run the unit tests, or validate the formal verification, or access the modding interfaces, etc. This is important because it represents the “replacement value” of a project to the consumer, which we’ll discuss next.

Relicense or rewrite?

The stated goal of copyleft is to create more copyleft source code, but in practice it does the opposite: Copyleft creates more proprietary code.

When a business finds a dependency that they’d like to use, but notice that it’s copyleft-licensed, the business has three choices:

1. Open source and relicense all internal code that would be impacted by integrating this dependency.⁵
2. Rewrite the dependency inhouse. (Or find another permissively licensed substitute, if such exists.)
3. Request a custom license from the copyright holders, see: Custom-licensed copyleft code is a liability. (This is also logistically difficult if the project has many contributors without a consolidated copyright holder, as each contributor would need to consent.)

I’ve been working as an open source maintainer and contributor 20+ years and not a single time in my life have I seen a business willingly⁶ make public and relicense their internal code to comply with a dependency they were considering using. Not once!

On the other hand, I’ve personally witnessed many cases where a business would do a clean room rewrite of copyleft-encumbered code to avoid touching it. In fact, I’ve done work like this myself on several occasions and have been lucky to convince my employers to allow me to do it under a permissive MIT license. By default, rewrites stay locked up in an internal repository that no one else gets to benefit from.⁷

Why rewrite the code? Because it’s wildly easier to rewrite code after the design boundaries have been established.

If you have a mature codebase that your team spent a person-year building, ask them: “Given everything we’ve learned, how long would it take for us to rewrite this in a different language?” The answer to this is often around 10× faster. Much of the time spent building the first version is finding and avoiding all of the “wrong decisions”, iterating with user feedback, reframing features to make more holistic sense, testing them, polishing them, arguing over button colours, etc.⁸

Second, consider the “replacement value” of the project (from the previous section). If we only need 20% of the functionality, we don’t need to rewrite 100% of the code.

If you spent 52 weeks building 100% of the functionality and supporting infrastructure, and I just need 20% of it that I can rewrite 10× faster… that’s just a couple weeks of work!⁹

Why would a business pay for an existential liability that when they could just have a half-decent programmer do an in-house rewrite of the relevant component in two weeks?

Permissive licenses create more open source

While copyleft claims (but fails) to create more open source code, permissive code actually achieves this by default.

When a business uses permissively licensed code and runs into a bug or needs to patch an improvement, they have two choices:

1. Maintain an internal downstream fork with modifications, dealing with rebase conflicts with every update.
2. Send a pull request upstream with the modifications, and have the community maintain it for free.

No one wants to maintain and rebase an internal fork, it’s frustrating and grueling work with negligible benefits unless this one modification is the very core differentiator of your business–and this is extremely rare, especially considering most software businesses have hundreds or thousands of dependencies.

By default, businesses tend to contribute more to permissive open source code in their own self-interest.

Copyleft reduces the contributor pool

Most software businesses outright ban their employees from touching strong copyleft licenses like AGPL. For example, Google’s document on allowable licenses for third party dependencies.¹⁰

Some proponents of copyleft claim that this is a feature, not a bug: Why should we benefit businesses at all, when we could only benefit individuals?

Unfortunately, this exclusion is counterproductive because nearly every programmer in our capitalist society is employed by such a business. At minimum, these projects miss out from people who would upstream fixes and improvements during work hours, but also many employment agreements have much influence over what people do in their personal time (if not practically then at least emotionally).

And it’s not just businesses!

I am an independent open source developer who is passionate about permissively licensed code (could you have guessed?) and I create a lot of it. I will not even read AGPL code because I don’t want to risk possibly contaminating some of my many other projects.

Copyleft nuances and complexity

I can write Python that has a copyleft GPL dependency without relicensing my project to match, but I can’t write Go that has a GPL dependency without relicensing. Why?

Python is interpreted and the code is linked dynamically, whereas Go produces a statically linked binary so the copyleft “infects” the rest of the code.

Unless, of course, if I want to ship my Python program as a py2exe bundle with a GPL dependency, then that changes everything.

Does anyone actually understand these implications and how they vary across languages? Of course not!

But wait, what if I split out the GPL dependency into a shared library that is dynamically linked? Oh, that’s fine. Unless you ask the FSF, who disagrees with almost everyone else.

What about other copyleft licenses like LGPL? MPL? AGPL?

What if I wrap an AGPL dependency in a network-isolated container which batch-processes input from a proprietary component in my system? That’s fine.

Did we really improve anything or are we just asking people to create complex infrastructure and deployment workarounds?

I liked this quote from David Chisnall on lobste.rs (the rest is worth reading too):

[…] And this is reason #3742648 why I don’t contribute to AGPL things: They place a compliance burden on good-faith actors that are trivial to bypass for bad-faith actors.

Permissive licenses create public goods

While copyleft licenses have several exclusionary clauses (e.g. can’t use this code if you’re statically linking against other code that has a different license), permissive licenses do not. Copyleft licenses give special rights to the author, permissive licenses do not. Strong copyleft licenses are practically banned from large subsets of consumers and contributors (we’ll debate if this is justifiable), permissive licenses are not.

Permissively licensed code is a better fit under the “both non-excludable and non-rivalrous” definition of public goods.

Copyleft fails to prevent corporate capture

A common complaint is that Amazon AWS exploits open source by profiting from it without sufficiently contributing back, and that the only solution is strong copyleft like AGPL.

Until 2018, MongoDB was copyleft AGPL licensed, and Amazon AWS happily provided a hosted service for MongoDB. MongoDB didn’t like that Amazon was profiting from their work, so on October 2018, MongoDB changed their license to a commercial source-available license called SSPL–specifically to exclude Amazon being able to use it this way. By January 2019, just 2.5 months later, Amazon built and released a proprietary API-compatible version called DocumentDB.

MongoDB was being developed since 2009, for 9 years. Did it take Amazon 9 years to rewrite the “replacement value” of their service? No, it took 2.5 months.

Did AGPL save MongoDB? No.

Did copyleft AGPL create more open source code? No, Amazon did a proprietary internal full rewrite and never published the code as open source.

Did relicensing to an even more restrictive license force Amazon to give MongoDB more money? No.

This has happened again and again. Elasticsearch relicensed from permissive Apache-2.0 to commercial SSPL in 2021, which resulted in the previous Apache-2.0 version being forked and maintained as OpenSearch. Amazon contributed code to the permissively licensed version, but Elasticsearch did not succeed at extracting more money from Amazon by using a more restrictive license. In 2024, Elasticsearch changed their mind and relicensed to copyleft AGPL, but AWS continues to use and contribute to OpenSearch.

Did permissive Apache-2.0 create more open source code? YES! Unlike the copyleft AGPL example, Amazon forked the permissively-licensed project and continued to maintain it in public, allowing everyone else to benefit too.

In 2024, Redis (permissively licensed under BSD) relicensed to a Source Available license, same story: Redis failed to extract more money from customers, instead a permissive community fork continued under Valkey. In 2025, Redis changed their mind and relicensed to copyleft AGPL! What happened? It’s still early, but so far Valkey (BSD) continues to thrive, Redis continues to stagnate.

How do we make businesses contribute to open source?

I get this question a lot, and my general answer is: They already do, just not exactly in the way we might want.

When we imagine businesses contributing to open source, we imagine them sending money to maintainers of dependencies they use. While this does happen, it’s very rare.

What’s less rare is businesses increasingly choose to release parts of their code as open source code, and contribute improvements to other projects. While this doesn’t help overburdened maintainers, it is otherwise a good thing!

I believe the lowest hanging fruit is to encourage businesses to get more involved with creating and maintaining open source code by empowering their employees to do so.

The best way for maintainers to grow funding from businesses who use their software is to establish relationship with their “customers” and find services that are valuable for these customers. For example, funding to work on features that are important for the customers, or funding for an annual support retainer.

What license should I use?

If you’re optimizing for adoption and impact, I suggest the most permissive license that is popular in your community. Usually that’s MIT or Apache-2.0.

If you’re trying to create a self-sustaining silo of code that doesn’t get reused outside of a comparatively small ecosystem, then copyleft licenses achieve this.

If you’re trying to exclude groups from using your code, like for-profit businesses or the military industrial complex or people with disagreeable political alignments, then open source is probably not for you because that would violate the Open Source Definition.

Conclusion

In the past couple of decades, permissive licenses (like BSD, MIT, Apache-2.0) have succeeded at creating more open source code, more collaboration and mutual participation from businesses, more code-reuse, and more public goods.

This wasn’t always true: In the 90s, copyleft was king. Businesses were very skeptical of open source and security through obscurity was a popular mentality. In many ways, businesses considered themselves at war with open source. Recall this 2001 interview quote from Steve Ballmer (Microsoft CEO at the time):

Q: Do you view Linux and the open-source movement as a threat to Microsoft?

A: Yeah. It’s good competition. It will force us to be innovative. It will force us to justify the prices and value that we deliver. And that’s only healthy. The only thing we have a problem with is when the government funds open-source work. Government funding should be for work that is available to everybody. Open source is not available to commercial companies. The way the license is written, if you use any open-source software, you have to make the rest of your software open source. If the government wants to put something in the public domain, it should. Linux is not in the public domain. Linux is a cancer that attaches itself in an intellectual property sense to everything it touches. That’s the way that the license works.

Of course this was a misinformed and naive view, but the seed of the concern was real as discussed in the Custom-licensed copyleft code is a liability section.

In 2025, the landscape is very different. Businesses have found a mutually-aligned interest with permissive open source, and the ecosystem has exploded thanks to that.

Is this the best we can do? I hope not!

Let’s continue to find more Schelling points of collaboration and aligned interests, so that the public can benefit from a larger portion of private effort.

This post was featured on opensource.org/maintainers/shazow

My first big open source project was urllib3. Today it’s used by almost every Python user and receives about a billion downloads each month, but it started in 2007 out of necessity.

I was working at TinEye (formerly known as Idée Inc.) as my first “real” job out of university, and we needed to upload billions of images to Amazon S3. I wrote a script to get processing and estimated how long it would take to finish… two months! Turns out in 2007, HTTP libraries weren’t reusing sockets or connection pooling, weren’t thread-safe, didn’t fully support multipart encoding, didn’t know about resuming or retries or redirecting, and much more that we take for granted today.

It took me about a week to write the first version of what ultimately became urllib3, along with workerpool for managing concurrent jobs in Python, and roughly one more week to do the entire S3 upload using these new tools. A month and a half ahead of schedule, and we became one of Amazon’s biggest S3 customers at the time.

I was pleased with my work. I was just months into my role at TinEye and I already had a material impact. Reflecting on this time almost two decades later, I realized that doing a good job at work was not what created the real impact. There are many people out there who are smarter and work harder who move the needle further at their jobs than I ever did.

The real impact of my work was realized when I asked my boss and co-founder of TinEye, Paul Bloore, if I could open source urllib3 under my own name with a permissive MIT license, and Paul said yes. I did not realize at the time how generous and rare this was, but I learned later after having worked with many companies who fought tooth and nail to retain and control every morsel of intellectual property they could get their hands on.

It’s one thing to write high impact code that helps ourselves or our employer, but it’s another thing to unlock it so that it can help millions of other people and organizations too.

Choosing a permissive open source license like MIT made Paul’s decision easy: There was no liability or threat to the company. TinEye had all the same rights to the code as I did or any other contributor did. In fact, Paul allowed me to continue improving it while I worked there because it benefited TinEye as much as it benefited everyone else.

Releasing urllib3 under my own name allowed me to continue maintaining and improving the project even after leaving, because it was not locked under my employer’s namespace and I felt more ownership over the project.

Hundreds of contributors started streaming in, too. Nobody loves maintaining a fork if they don’t have to, so it’s rational to report bugs upstream and supply improvements if we have them.

The growth of urllib3 since the first release in 2008 has been a complicated journey. Today, my role is more of a meta-maintainer where I support our active maintainers (thank you Seth M. Larson, Quentin Pradet, Illia Volochii!) while allowing people to transition into alumni maintainers over time as life circumstances change. It’s important to remember that while funding open source is very important and impactful (please consider supporting urllib3), it’s not always about money. People don’t want to work on one thing their whole life, so we have to allow for transition and succession.

I learned many lessons from my first big open source project, and I continue to apply them to all of my projects since then with great success. I hope you’ll join along!

“Any sufficiently advanced incompetence is indistinguishable from malice.”

tl;dr: Earliest online record of this quote is by Vernon Schryver on May 1, 2002.

Grey’s Law, 1996?

Wikipedia, LLMs, and various random blog posts cite it as “Grey’s Law” which I haven’t been able to corroborate.

Wikipedia references a book from 2015 which refers to the quote as “Grey’s Law” but attributes it to “unknown author”. I couldn’t find an actual source for someone named Grey, and closest “Grey” reference I’ve found mentioned is a Youtuber named CGP Grey from 2010+.

Meanwhile, Rationalwiki’s Talk section on Grey’s Law has an anecdotal story from someone who claims to have made that quote in the 90’s under a handle related to Grey:

[…] I have a distinct memory that some point in the very late 90’s or early 00’s was the first time (for me) that I posited the maxim “any sufficiently advanced incompetence is indistinguishable from malice,” with explicit crediting of Clarke and Hanlon. […]

Unfortunately, I haven’t been able to find actual archives of posts with this quote from the 90s.

Vernon Schryver, 2002

Earliest online record of this quote is by Vernon Schryver on May 1, 2002 on in the news.admin.net-abuse.email usenet newsgroup, which has sadly been purged by Google Groups but luckily archive.org still has a snapshot: https://web.archive.org/web/20070221155843/http://groups.google.com/group/news.admin.net-abuse.email/msg/f9f67dca7591a860

Napoleon-Clarke Law, 2004

It was later dubbed the “Napoleon-Clarke Law” by Paul Ciszek on October 11, 2004 in the rec.arts.sf.fandom usenet group. Paul explains later in the same thread:

Well, Napoleon said something about not attributing to malice that which is adequately explained by incomptence, and Clarke said that any sufficiently advanced technology is indistinguishable from magic. So far as I know I am the first one to put them together and call it the Napoleon-Clarke law.

After finding some of the pieces pointing to Vernon Schryver and Paul Ciszek, I stumbled on this excellent overview thread by Kevin J. Maroney in Sept 25, 2005 on the rec.arts.sf.fandom newsgroup that is worth a read: https://groups.google.com/g/rec.arts.sf.fandom/c/1JaqxckrAOc/m/xO5jzyejK1UJ

Hanlon-Clarke Corrolary

We later reattributed Napoleon’s quote to Hanlon’s Razor.

Coming back full circle with Grey’s anecdote who correctly attributed the mashup to Hanlon and Clarke, I’m going to take this opportunity to further rebrand Vernon’s quote as the Hanlon-Clarke Corollary.

Until we can find better corroboration of Grey’s anecdote (please reach out if you have a lead!), I say we attribute this quote mashup to Vernon Schryver.

Hanlon-Clarke Corollary: “Any sufficiently advanced incompetence is indistinguishable from malice.” ~ Vernon Schryver, 2002

• ActivityPub/Mastodon
• ATProto/Bluesky
• Farcaster/Warpcast

Some scenarios I’d like to consider:

1. Can my identity be taken away?
2. Can my audience be taken away?
3. Can my ability to extend it and build on the protocol be taken away?

Some specific failure modes I’m concerned about:

4. What happens when the most popular app or instance becomes malicious?
5. Is there something the maintainer can do that would prompt me to abandon the service/protocol altogether?

Let’s begin:

ActivityPub/Mastodon

There are two scenarios to consider here: One is for self-hosting and second is accounts that are hosted on a shared instance.

While ActivityPub has many uses outside of social networks and the social network aspects like Mastodon are capable of self-hosting, they are practically designed for shared hosting¹: It is practically impossible for everyone to self-host an instance today. Even if I had a magic wand and made every Mastodon account self-hosted, the service as designed today would be unusable.

With that in mind, I will primarily focus on the shared-hosted Mastodon-compatible social network instance case specifically:

1. Can my identity be taken away?

   💀 Yes.

   The owner of the instance has full control over instance accounts and can do with them what they please.

2. Can my audience be taken away?

   💀 Yes.

   In fact, this happened to me personally. I was on an instance with a few hundred followers, then the admin burned out and abruptly shut down the server and now both the identity and audience are forever gone, impossible for me to recover.

3. Can my ability to extend it and build on the protocol be taken away?

   💚 No.

   ActivityPub is an open and generously permissive protocol built around implicit trust, almost to a fault with some security implications here such as private accounts’ posts getting leaked across federated boundaries².

4. What happens when the most popular app or instance becomes malicious?

   🚨 Worst case scenario is if the largest instance disappears (or gets purchased by a malicious billionaire) then all of those identities are gone, all that audience is gone, the content is gone (some may be recoverable through caches on federated instances, but not robustly attributable). But other instances survive and are largely unaffected except for the reduction in audience, and this is an improvement over something like Twitter.

5. Is there something the maintainer can do that would prompt me to abandon the service/protocol altogether? 💚 I don’t think so.

   There is a huge ecosystem with diverse implementations by varieties of people. There are already apps built on ActivityPub/Mastodon that span every conceivable ideology, including TruthSocial that is owned by the president of the United States and Threads owned by Meta. I don’t think any of them can say or do much which would severely change my perspective on ActivityPub or Mastodon as a technology.

   I found at least 80 independent Mastodon instances with over 10,000 users and 10 with over 100,000 users. Protocol challenges aside, this level of instance diversity is very impressive.

ATProto/Bluesky

Bluesky (and the ATProto protocol it’s built on) has many optional provisions for improving the sovereignty of users, such as managing signing keys with the Public Ledger of Credentials (PLC)³ and running my own Personal Data Server (PDS)⁴ that can serve as a source of truth for my data. While this is not the default, and it’s unrealistic for everyone to self-host a PDS, the protocol is designed for a world where everyone has ownership over their signing key and it does support alternate identity schemes in the future (potentially even fully sovereign and programmable onchain signatures).

1. Can my identity be taken away?

   💚 No-ish.

   The default onboarding with a *.bsky.social identity is controlled by Bluesky and can be taken away, but the protocol facilitates using my own domain for my identity, so I can be shazow.net instead of shazow.bsky.social and that can’t be taken away by Bluesky BUT it can be taken away by ICANN and my registrar.

   Note that this namespace is mostly cosmetic, the actual protocol interactions are mapped to a long-lived public key (a DID, managed by the PLC) and the “human readable” identity is simply an alias to it which can be changed without losing the interaction integrity. This mapping is currently stored in a verifiable but centralized database (PLC Directory) which can misbehave by preventing updates, limiting access to the ledger logs, and removing/reordering the history of operations.⁵

   Overall, if my handle is taken away, then someone else will show up as me on Bluesky and I will need to register another handle, but I will not lose any of my social graph. If the PLC Directory disappears, I could lose my ability to write to my account.

2. Can my audience be taken away?

   🟠 Sort of.

   ATProto messages are designed to be robustly replicated with cryptographic signatures, so there can be arbitrary paths to getting messages to my audience. Unlike ActivityPub, if one replica loses all of my posts then another replica can robustly re-introduce them to the network without risk of forgery.

   On the other hand, a core part of Bluesky is their approach to composable and comprehensive moderation tooling that is available at many layers (the client via labels, the AppView, the relay, etc). On multiple occasions, Bluesky chose to deplatform users who effectively lost all access to their audience.

   It would help if Bluesky leaned more heavily on their excellent community moderation tools and eventually remove global moderation altogether. Additional popular clients and AppViews with their own policies would help, too.

3. Can my ability to extend it and build on the protocol be taken away?

   💚 No.

   I can extend ATProto with my own “lexicons” and create whole parallel functionality within the same infrastructure.

   In fact, there are already many interesting use cases being used, like: WhiteWind for blogging, Smoke Signal for coordinating events, Flashes App for photo sharing, and many other experiments. That said, I suspect some of this will change in the future as more griefing and other attacks on the protocol are explored.

4. What happens when the most popular app or instance becomes malicious?

   🚨 What happens if Bluesky Social, PBC (the company behind Bluesky) disappears tomorrow? Let’s say bsky.app and associated infrastructure they run is gone (bsky.social PDS, AppView, relays, etc), now what?

   The good: The Bluesky App and infrastructure tools are all permissively-licensed open source, and someone else can fork them and release alternate versions. There are some minor players already trying this. The historic state can be replayed from any archives people have (there are some services who maintain snapshots).

   The bad: It’s extremely expensive to operate for the current userbase (33M users today), it was estimated to cost over $500,000/mo in hardware costs when Bluesky was half this size. Assuming double that after bandwidth, human, and other costs, it’s prohibitively expensive for a random individual to take on that cost and it’s too much to quickly coordinate a grassroots cooperative effort. Frankly, both the protocol (relays feeding an AppView monolith) and culture (“signups should be free”) are not designed for a collectively owned/operated ecosystem at scale.

5. Is there something the maintainer can do that would prompt me to abandon the service/protocol altogether?

   🚨 This is a tricky one.

   If the Bluesky team said tomorrow “you know what? we’re tired, this isn’t working out, we’re going to stop working on it” then I’m not confident that someone else would pick up the baton. That could very well spell the end of the social network as it is today. It’s not like there’s a bunch of companies making good money from it that they’d be compelled to take over to retain their business. If there were more independent and institutionally motivated companies hosting their own instances of the whole stack so that users can trivially switch endpoints on the app, I’d feel more confident.

Farcaster/Warpcast

Warpcast (and the Farcaster protocol) takes a similar portable cryptographically-signed approach as ATProto, except with several important differences: Full identity sovereignty, native payments, and a culture around building an active self-reinforcing economy within the protocol ecosystem. Both third-party services and unique features like mini-apps that take advantage of payments being a native mechanism on Farcaster. Keep this in mind for the final point.

1. Can my identity be taken away?

   💚 No.

   While the default onboarding flow uses a custodied identity similar to Bluesky (Farcaster ID), anyone can set an ENS identity which is fully self-custodied and can’t be taken away even, not even by ICANN. So instead of shazow.farcaster I am shazow.eth. This also allows for arbitrary programmable collectively owned namespaces, since the ENS can be owned and managed by any smart contract.

   Additionally, Farcaster’s key management is onchain in a smart contract by default, so every user has full control over their permissions in a censorship-resistant way⁶. There are several supported signing formats, including passkeys. There is also optional social recovery available, by default it allows Warpcast to help recover my account if I lose access to all my signers (passkey, mobile app, etc) but I can change that.

2. Can my audience be taken away?

   💚 Not entirely, but there is still only one main app (Warpcast) that is used by the vast majority of people.

   The dominant app can effectively moderate people out of the timeline, indistinguishable from being categorized as spam. This will change very soon as large companies like Coinbase are integrating Farcaster into their apps which would compete in scale with the active audience on the network today. A few more large participants with a variety of timeline/moderation approaches will make audience ownership relatively safe.

3. Can my ability to extend it and build on the protocol be taken away?

   💚 No.

   While the apps do a great job hiding the implementation details, the key management is non-custodial in a smart contract, so I can fully control who gets write access to my namespace and that can’t be taken away from me. The Farcaster Hub protocol is similarly cryptographically signed so my messages can be routed in arbitrary ways even with one node censoring.

   While lot of development today is happening around Mini-Apps (formerly known as Frames) which run within the timeline with native access to payment and social functions, there is also a healthy community building on the Farcaster protocol itself.

4. What happens when the most popular app or instance becomes malicious?

   🚨 What happens if Merkle Manufactory (company behind Farcaster) disappears tomorrow, along with the app and all the infrastructure they run?

   While the protocol and hubs to run it are permissively licensed open source, the main app is closed source and much of the auxiliary infrastructure required to operate the app is also closed source (algorithmic timeline service, spam moderation, etc). There are some alternate implementations, but it’s still early.

   On the other hand: It’s not wildly expensive to operate the necessary infrastructure ($X00/mo operate a hub), largely in part because the Farcaster network is still fairly small (3% of Bluesky right now, at 870K users and 45K daily actives), so it’s quite plausible that individuals, small groups, or another company could take on this burden. Plus there is a thriving culture of economic activity on Farcaster. Coinbase is integrating a client, Neynar provides paid API services for developers, a bunch of people are almost making a living through various mini-app activities.

   This scenario would be painful, but the proportion of Farcaster’s size to the economic activity on the protocol is still promising. This may change as Farcaster grows.

5. Is there something the maintainer can do that would prompt me to abandon the service/protocol altogether?

   🚨 This one is also tricky. I suspect there is not yet enough momentum if the founders decided to wind down. I ask myself if I would care if a megacorp acquired the team along with the most popular app but committed to maintaining the same design properties… I’m not sure! More independent/open source, and economically motivated apps platforming large audiences would make me feel more confident that moderation won’t get abused.

Takeaway

Economic balance matters

If it’s far too costly to bootstrap infrastructure in a black swan event (censorship, evil billionaire, physical infrastructure failure, whatever) then the efficacy of a robust protocol is lost.

For a given player, the balance is between the cost of correcting a failure and value that is gained from recovering. If a network has a thriving economy and it is comparatively inexpensive to operate it, then we can be more assured that it will persevere.

Scale matters

Some protocols have desirable properties when the network is small, but lose them at scale:

A few blogs federating ActivityPub remain perfectly robust from capture, but a million user Mastodon instance is a juicy point of failure. Even smaller instances are brittle and risky: perhaps the sysadmin gets burned out and wants to do something else or a security update isn’t installed quickly enough.

Similarly, Farcaster seems almost sustainable at today’s scale, but will it be off-balance like Bluesky if it grows to tens of millions of users?

Interdependence matters

We can’t expect a single dominant player to resist exercising powers like threats of censorship, even if the underlying protocol is resistant. If one player is platforming 99% of the network, there is nothing stopping them from abandoning the underlying protocol altogether and just replacing it with a private database instead. We must have a multi-polar plurality of interdependent players to protect us from the effects of capture.

What’s next?

I’d like to see each protocol describe what their ideal evolution and adoption looks like a year from today. If everything about the current roadmap goes right and all the relevant partners enthusiastically join forces, what does the world look like for this protocol in 2026?

Thanks to Boris, Boscolo, and Leeward for reviewing early drafts of this post. Also big thanks to everyone who asked great questions after this was published.

Are the trillions of us spanning many solar systems?

What if there are only millions, or even thousands of us?

It’s tempting to take our history of swarming through continents on Earth, consuming all available resources to scale and grow, and extrapolate it into space. Many planets across many solar systems, each with many billions of people. A lot of science fiction paints this version of the future, but what would it take for us to imagine a different future?

What if we defeated death and could choose to live forever? What if we become cybernetic, melding with the machines we build? What if we tame our minds and upload replicas into digital storage, onto digital simulations, and back into artificial physical sleeves?

What if we transcend life, creating artificial beings beyond imagination? What if we finally achieve alchemy: transmute matter into energy and back again, transporting at the speed of light and reconstructing into whatever physical bodies we want whenever we want?

Imagine a distant species, once human but now anything, which can exist and scale to any shape or quantity on a whim. A species that is confident of its mastery over reality, unneeding of redundancy and excess.

Would there be thousands of us one day, travelling in groups as we wish? Materializing peers and family on another day into billions, only to pack up later into few again.

Would some choose to join their minds into a collective consciousnesses, blurring the line of enumeration?

Will there be one?

For a long time, we have been in an Age of Growth as a society. Growth has been our main metric for success that we optimized obsessively, sometimes to toxic extremes.

Can we imagine what it would take for us to transcend into a post-growth society?

Thank you to John for sending this related audio short story after reading this: Outlasting the Universe

After breaking my foot, I’ve been working on conditioning all of the tiny ligaments to properly support movements and impacts I haven’t practiced in months. I can’t just say “hey foot, you’re not broken anymore, go back to normal.” I have to slowly and incrementally reinforce each change.

Similar to learning a musical instrument by training our fingers to move a specific way, over and over – we’re telling all of the related “muscle memory” that this is an important motion we need to be good at. Like lifting weights, we’re telling the muscle “you’re going to continually exceed your capacity, so get bigger and stronger.”

It’s not just a one-and-done: Conditioning takes time and repetition, because the channel is low-bandwidth and lossy, and the micro-changes required are many and sequential.

When we train our dog to not be reactive about visitors (or to salivate when the bell rings), we can use positive reinforcement to rewire the brain with the help of oxytocin signals. Treats, “good dog”, or even hugs can all be forms of communicating that the precursor to some stressor is actually okay. Just like humans working with a therapist, we try to condition the sources of our anxieties to take on different frames (or acclimate to our fears).

Similar to positive reinforcement with oxytocin, there is cortisol and dopamine and other hormones/neurotransmitters which communicate desirable/undesirable conditioning between different aspects of our minds and bodies.

I really like the model that we’re not monoliths, but rather a bunch of disparate components who are stuck together. Our brain can’t simply tell our body to shed fat and build muscle, our tic disorder to chill out, our ligaments to support wider range of motion… but our brain can slowly and methodically facilitate these changes by communicating them through conditioning!

What does this mean for society?

If we break out of the monolith mindset of our bodies, we can also think of communities, corporations, nations, species as “mega organisms” who suffer from inefficient/indirect communication.

We may condition our societies towards democratic practices or into accepting authoritarian rule. To justice or inequity. It can happen slowly through reinforcement, or it can snap like a bone breaking from ever-increasing pressure. Those suffering may ache like a festering infection, but we can acclimate (or amputate).

What’s the difference between Jeff Bezos and a rando who woke up with a hundred billion dollars?

Bezos has preconditioned infrastructure to achieve his endeavours. He can take on logistics, media, space exploration, investment, and who knows what else. What can rando do without spending months/years “conditioning” their assets to support their endeavours? Just think of how long it would take to even hire a sizeable team of good people! This is conditioning.

In many ways, the peripersonal space of powerful individuals expands far beyond their wealth. It extends to that which they have conditioned to advance their pursuits.

I want us to condition ourselves out of thinking like monoliths. How do we do that?

We should condition ourselves to think in terms of conditioning, rather than quick drastic swings that bring injury after injury. (“We need to be good at lifting heavy weights, so we should lift the heavy weights immediately.”)

We can set ambitious goals that are beyond the ability of a single component, or even a single person or nation, and we need to figure out how to communicate them properly to all participants–repeatedly, consistently! All participants need to practice them, repeatedly and consistently!

Let’s not ignore our pains, but take time to listen and understand where the pain is really coming from and why, and how to address it.

But most importantly: Recognize when we’re being conditioned into something we don’t want to be.

It can be just a couple of sentences of how they positively impacted your life, or a brief story of a positive shared experience, or what you admire about them.

Let’s break down “collectively owned programmable substrate”:

Collectively Owned

The Ethereum consensus is a communal mechanism which enforces certain rights for anyone who chooses to use it.

Primarily, it is designed to enforce the right to deploy code that is guaranteed to be executed correctly without relying on an empowered intermediary (someone who can choose to break the rules we’ve established). These rights are extended to everyone equally: regardless of which country or jurisdiction you live in, and whether you’re a person or corporation or even a program.

Anyone can read the state of the Ethereum blockchain, but writing to the blockchain requires paying for the cost of the execution².

Programmable Substrate

Building on top of a programmable substrate inverts many of our traditional assumptions:

• We can create programs that are immutable (permanent and unchangeable) yet flexible.
• We can create programs that give up all owner control, giving all of the power to the consumers.
• We can build composeable components that can be reused safely (because they’re immutable).

Programmable Security

Traditionally, services we use have concrete security flows: Choose an email and password; Add a phone number for a second factor; Upload a photo of our driver’s license to verify it’s us. If our bank doesn’t support Authy for a second factor, there’s nothing we can do but complain. If our email provider doesn’t support team logins, there’s nothing we can do but share the password with the team.

The blockchain ecosystem flips this dynamic: The application does not need to care how the consumer secures their accounts. Every account can provide a cryptographic signature, and that’s enough.

With smart contract wallets like Safe{Wallet}, we can customize every aspect of our own security. We can add multiple devices, we can add spending limits, we can add various recovery schemes like Social Recovery. This allows us to dramatically innovate on our security practices as an independent industry.

Programmable Identity

Traditionally, we have identity cards issued by our local government, or domains managed by ICANN, or a profile managed by LinkedIn. These are all empowered intermediaries: They can choose to deny changes, or outright ban us from their systems.

Ethereum Name Service (ENS) is an example of a collectively owned identity resolving system that is also fully programmable. We can set it up a name like foo.eth that routes one way on weekdays, and other ways on weekends. There is no centrally managed “API” that can be sunset and prevent us from using it like before. By using programmable security, we can abstract the ownership of our ENS to be managed by an individual, or a team, or a democratic collective, or anything else that can be expressed as a program.

Programmable Banking

Traditionally, banks require us to pay bills from a Checking Account, but encourage us to hold money in a Savings Account through modest interest rates. Autopay Bills can only be paid out of Checking Accounts. If the Checking Account drops below zero, we get charged an Overdraft Fee (even if money is available in the Savings Account), and we’ll also get hit by a Late Fee from the bill provider. Not to mention many things being limited to business hours, out of network ATM fees, excessive foreign exchange fees hidden in the price spread, over a billion people blocked out of the banking system at large. Why do we tolerate these anti-consumer constraints?

Banking in a collectively owned programmable substrate is quite different: There are no limits to how accounts must behave, we can automatically split incoming payments among our collaborators (e.g. splits.org); we can setup a cascading system that pays for our services however we want–even complex vesting or payroll payments streamed down to the second (e.g. superfluid.finance, sablier); we can completely abstract multitudes of currencies and assets (e.g. cowswap), allowing us to pay with whatever we prefer while being confident that we’re receiving the most competitive rate that anyone else would too.

Programmable Everything?

If you’re a web developer, how many times have you built the same signup/login flow?

What would we build if we didn’t have to re-implement standardized “smart” components that are collectively owned? What if our consumers could bring their own…

• Login security and recovery
• Identity details
• Payment processing
• Social network audiences
• Cosmetic assets (picture profiles, avatars, item skins, colour schemes and themes)
• Privacy-preserving attested facts (whether they’re over some age, or have some amount of income, or a citizen of some jurisdiction, or a unique human)
• Governance processes for how communities make decisions
• … What else?

What if all of those components kept getting better and better, while our application could stay the same?

The question is not “why can’t we build this without a blockchain?”

The question is: Why would we want to build things without a collectively owned programmable substrate?

“There are no such thing as zero trust assumptions.”

Trustless is a confusing word: We don’t use it in common speech; it means “not trust worthy” in the dictionary; decentralized technologies sometimes use it as “not needing to trust”; and the uninitiated might interpret it to mean that it’s advocating for less trust?

Despite the confusion, there is a very useful insight behind the concept of “trustless” (in the decentralization sense). To understand it, let’s suspend our immediate reaction and break down two interesting properties behind this concept: Explicit trust and immutable trust.

Our goal is not to reduce the amount of trust in the world, but rather to create more and better trust that we can use to create more powerful and interesting systems.

Consider a typical intimate relationship: We can create more and better trust through communication–setting expectations and being clear about our boundaries, allowing us to thrive even in more complicated and non-traditional arrangements.

Let’s try to build a framework for doing this when designing other kinds of systems.

Immutable and Mutable

To trust something mutable is to understand that it can change. To trust something immutable is to understand that it cannot change. We’ll explore how we can plan for and benefit from both scenarios.

When the CEO of a company makes a promise, we need to remember that it’s not the individual making a lifelong commitment. The Chief Executive Officer is a role within a company. One day it can be Dick, next day it can be Parag, then Jack, then suddenly Elon.

A leadership role within a company is mutable, which means that the direction of a company can change. When we put our trust in a verbal commitment of a company, perhaps drafted by a PR firm, we must remember that the role which drives that promise can be changed–and inevitably will be, as we don’t live forever.

Individuals are mutable, too. People age, change careers, lose interest, get sick, and ultimately die. It’s okay to be mutable.

Even when we commit to a contractual obligation, the meaning of the contract can still vary within the interpretation of the law. Legal experts can sometimes help us to better understand all of the possible outcomes and how likely they are.

When we add a trust assumption in a specific protocol or a theorem, we can be confident that the nature of that trust is not going to change. Our understanding of it might change–perhaps we discover an undesirable property that was encoded within it. No worries, we can stop using the old undesirable protocol and switch to a new one.

Imagine a terrible law that was written before we knew any better, that is ultimately challenged and abandoned. The old immutable law still says what it said before, but our legal system decides to stop using it. Being immutable is okay, too.

Explicit and Implicit

To trust something explicitly is to fully consent to how it can behave and how it can change. To trust a complex system with many components of varying mutability as a single opaque agent is to accept its complexity implicitly.

When a couple starts dating, they start out trusting that their relationship is operating within the default expectations of our society or their social group. Sometimes that’s as far as relationships get, they rely entirely on these implicit assumptions. Other relationships will slowly and explicitly map out important assumptions and boundaries: Are we exclusive? Have we been tested for STI’s recently? What’s our safe word? Are we always putting the toilet seat down?

Relationships start being based on implicit trust, but can become increasingly anchored by explicit trust.

When the CEO of a company makes a promise, they’re making a commitment on behalf of all of the participants of the organization: The employees, the board, the suppliers and contractors, sometimes even the shareholders. How many times has a company promised us that our data is safe, only to leak their data a few months later because an employee was careless?

When we choose to trust a company to behave in some way, we are implicitly consenting to the behaviour of all of the components within that system.

Some trust assumptions are simple and explicit (“I trust you to always put the toilet seat down”) and we can have clear expectations of what happens if that trust is violated (toilet seat stays up). Other trust assumptions are just the tip of a complex iceberg of assumptions (“I trust Apple to care about my privacy”) and it can be extremely hard to enumerate all of the possible failure modes and fully consent, so we can choose to trust them implicitly.

Let’s say that implicit trust assumptions are ones that contain an arrangement of additional trust assumptions behind it, with varying mutability and implicitness.

Trust Chains

The challenge with mutable and implicit trust points is that it’s impossible to chain them while maintaining strong confidence. The complexity of assumptions spirals astronomically with each additional chain. Sometimes the legal system can help us mitigate this by enforcing assumptions from the outside: If we have a contractual agreement with all participating parties, then anyone deviating from the expectations can be later sued and perhaps damages can be recovered (but even that is merely a mitigation, the original desired state cannot be guaranteed).

What if we had a bunch of mechanisms that had explicit and immutable trust properties? We could chain them to arbitrary arrangements, while still having full confidence of the outcome’s variability.

We can take several mathematical axioms, and use them to build complex mathematical theorems that maintain the same hard trust expectations we established from the axioms.

Deep & Complex Relationships

In a world with more explicit and immutable trust mechanisms, we can create more interesting and complicated trusted relationships within our society.

Trustless does not mean we must trust each other less, but rather it means that we can trust each other more!

Even in our intimate relationships, ample communication and setting explicit boundaries allows us to create stronger and more complex intimate relationships. Relationships that are entirely bootstrapped from the implicit assumptions of our society’s defaults are the ones that are limited within that same framework–to the point that we’ve had to build an institution of marriage to enforce it with the help of our legal system.

With more explicit and immutable trust mechanisms, we can create more complicated cooperative collectives, we can create more interesting governance structures, we can create a larger solution space for our future.

Let’s create a world with more better trust.

If we have two systems where one is more trustless and the second is more permissionless, can we say that one is decentralized but the other is not? Can we even say that one is more decentralized than the other? Or does each simply have different points of centralization across different dimensions?

Perhaps we need a clearer vocabulary to use when we discuss decentralization. Peer-to-peer, trustless, permissionless, non-custodial, credibly-neutral… What do we mean by these words?

Vocabulary

Let’s break down some of the properties that are found in some of our fantasy decentralized systems, and imagine that each of these properties exists on a scale of 0 to 10:

• Peer-to-peer: We can participate in the system by connecting directly with another peer, without going through a designated intermediary.
• Trustless: We can independently verify that all of the components of the system are behaving correctly.
• Permissionless: We can be equal participants in the system without requesting access from another entity that can act as a gatekeeper. This is also related to preventing censorship.
• Non-custodial: We can participate in the system without giving up or delegating any control (or power of outcome) to a provider.
• Credibly-neutral: The system is not systemically biased towards a specific sub-class of participants.
• Legitimate: The system is behaving in accordance to the rules that we collectively decided are desirable.
• Open Source: Anyone can read the source code of a system, and fork the development of the software if there is disagreement with its development.

This is not a comprehensive list, but it helps to discuss concrete properties that fall under this umbrella.

We must be mindful that changing the scale of one of these properties does not make a system entirely centralized or decentralized! By changing the design of our system, we can add or remove points of centralization across specific dimensions.

Why are these properties important?

We can acknowledge the obvious reasons: When we give disproportional power to specific individuals, it can lead to abuse of that power.

But there is a more interesting property:

It’s easy to build centralized systems on top of decentralized systems, but it’s hard to build decentralized systems on top of centralized systems.

This asymmetry means that there is a larger possible solution space in decentralized systems than in centralized systems. One is a superset of the other.

Let’s explore each component within this context:

• Peer-to-peer: We can build a client/server relationship on top of peer-to-peer systems, but we can’t directly connect to a peer if we’re only allowed to connect through a designated server.
• Trustless: We can write a verifiable smart contract that lets an opaque box unilaterally control it. We can’t build a verifiable smart contract on top of a opaque box.
• Permissionless: We can deploy a smart contract on a permissionless system that controls who can interact with it.
• Non-custodial: We can always delegate our secret private key to a custodian, like a spouse or a bank.
• Credibly-neutral: We can create a smart contract on a neutral system that gives preferential treatment to public keys that are on a special list.
• Legitimate: We can create a smart contract on a legitimate system which advertises one desirable behaviour, such as “price always goes up”, but ultimately exhibits an undesirable behaviour, such as “creator stole all the money.”
• Open Source: We can deploy a closed-source service that uses open source underneath. In fact, almost all closed-source software today relies on open source. Not hard to imagine.

This is similar to how we can easily build an insecure system within a secure system, but it’s extremely hard to build a secure system within an insecure system. Secure systems have a larger and more interesting solution space within them.

It’s clear that we can take something completely decentralized in every respect, and easily build on top of it something that defeats every desirable property. Many “scams” take this shape: They exploit the intuition that a system with desirable properties would only be a host to other things with desirable properties.

Turtles all the way down

Our lives are composed of a mishmash of systems that are centralized or decentralized in different ways.

It can be convenient to point at one piece like TCP/IP exclaim “the internet is decentralized!” Or we can point at ICANN (or Amazon AWS or Facebook) and exclaim “the internet is centralized!”

When we realize how it’s easy to build centralized systems on top of decentralized systems, it’s unsurprising that we can find so many conflicting examples.

In many ways, our political systems fall on these axes, too: We value legitimate democracies, and eschew corrupted authoritarianism. We fear that people in positions of power will abuse them without “transparency” and “checks and balances”. We want to have private and personal relationships with people. We like the idea of living in a society that allows us to do creative things without asking for permission, and we would prefer a future where a small class of people doesn’t have disproportional power and wealth over everyone else.

Other interesting examples to contemplate within this framework: In what properties and scales is our legal system decentralized? What about realestate ownership? Modern medicine?

What does decentralization solve?

Ask not what decentralization can do for you, but what you can do for decentralization.

Decentralization can remove the surface area for problems that are created by centralization, such as those caused by added intermediaries and custodians.

Let’s setup a fantasy strawman scenario to illustrate this:

Imagine Twitter starts requiring a new kind of intermediary for posting on their service: Moving forward, everyone has to tweet through another Twitter employee. That person will get your username and password, and you’ll need to phone them up and dictate your tweet for them to post on your behalf. What are some things that can go wrong here?

For one, we’re going to have all kinds of communication issues–literally a game of broken telephone! Tweets are going to get miswritten due to bad phone reception, or misunderstanding of accents, or the intermediary having a bad day, or maybe they’re working with a political figure that they despise. We’ll need to hire thousands or maybe millions of intermediaries to do this job, and this also opens up an opportunity for the intermediary to leak our password, or outright hijack our account and post unauthorized tweets. Perhaps we can discourage it with a licensing scheme and harsh penalties.

Admittedly Twitter was not very decentralized to begin with, but let’s work through our framework:

• Peer-to-peer? We now have another designated intermediary that we’re required to use in the chain, so this got worse.
• Trustless? Another intermediary in the trust chain that we can’t audit, this got worse.
• Permissionless? Even if we made it through Twitter’s original gatekeeping, the new intermediary can decide to block us.
• Non-custodial? This new intermediary has our username and password, and they can do what they want with it. We’ve given up all control over our Twitter accounts to this custodian.
• Credibly-neutral? Perhaps the licensing scheme and penalties could keep most of these intermediaries in line, but ultimately that’s one more point where bias can be exercised to dis-empower classes of people. Even politics aside, imagine using this phone system with a speech impediment. If Twitter was 6/10 on this property before, it’s more like 4/10 now.
• Legitimate? This one is more interesting here. If we as a society decide that these intermediaries are ultimately doing a great service to us by exercising their judgement and reducing content that we don’t want anyway… it’s possible that this fantasy could end up more legitimate than original Twitter?
• Open source? Since this is already a closed system, this reduces to the Trustless property. One more opaque step that we can’t audit.

Now imagine we remove this added intermediary, and suddenly all of these new problems disappear from that particular point. Other points of centralization still exist as they did before, and perhaps we can work towards removing them too someday.

Clearly this is not a serious example, but it illustrates important points:

1. We can always add more intermediaries, it’s very easy! This changes the decentralization properties of our system.
2. We can remove intermediaries, but it’s harder as they become integrated into our institutions. Imagine if it’s wildly profitable to be a Twitter Intermediary due to bribes, or the contrary: the thousands of underpaid and overworked employees form a union that becomes too difficult to bargain against. How can we conscionably take away jobs from so many people?
3. Since they’re so easy to add, intermediaries exist everywhere. How do we evaluate which ones are worth doing the hard work of removing? Can we even anticipate what the outcomes will be?

This is again similar to security: Removing components that don’t have the necessary guarantees is the best way to improve security, but it can be hard to remove components without sacrificing their features that we’ve become dependent on. On the other hand, how many times have we found fragile dependencies in our systems that we don’t need anymore?

Decentralization is not a panacea

We have many challenges in modern society that are orthogonal to whether they’re expressed by a centralized system or decentralized system.

For example, consider ownership: We can have a centralized physical ledger on our Mayor’s desk, with entries of who owns what. Or we can have a decentralized digital ledger, with the very same entries. In either case, it does not change what policy on ownership we enact as a society. It does not change what taxes we choose to collect, or what kind of construction zoning we allow, or if we decide to disregard that ledger and start anew.

Some other social challenges worth noting: Decentralization does not solve wealth inequality, it does not solve local law enforcement, it does not solve the ability for people to create centralized systems within it (and all of the problems that are created from them).

When is centralization useful?

Most properties of centralization are about concentrating control or power in a specific component, this can make it very easy to make quick unilateral changes in policy. To decentralize is to give up power or control.

When we imagined the fantasy Twitter scenario, the added intermediaries acquired a powerful position: They gained control of what tweets were being posted. To remove them, they would need to give up that power.

We can imagine scenarios where having ultimate power and control can be vital, such as a military chain of command. When facing dire threat and every moment is a life-or-death decision, having competent leadership with full control over their domain is crucial.

Centralized properties can be very convenient and powerful, and some of their harm can be mitigated by placing them within structured decentralized process–like giving a representative partial control over an organization, while still being able to vote them out. More harmful parts of centralization are amplified when they approach permanent capture, when we become too dependent on them and we’re no longer able to exercise any mitigations for misbehaviour.

It is up to us to choose whether we allow more and more parts of our lives to become captured in centralization, or if we want to pursue the dream of decentralizing things that were not possible to decentralize before and see where that takes us.

Appendix with additional notes and links.

Thanks for feedback on early drafts to Benjamin, Ezzeri, Harper, Jenny, Max, Phill.

There are many things about it that are outright fascinating: Algorithmic stablecoins, automated market makers, flash loans, flash mints! Every month there is a wild new invention that changes the landscape, often increasingly difficult to understand which is both frustrating and intimidating.

I want to talk about one thin slice of this technology that I’m seeing a lot of people have trouble grasping: Where does the yield come from?

A big part of the DeFi movement is easy access to pools of high-yielding assets. The highest-yielding assets are leveraged derivatives of other liquidity pools, but at the foundation we have access to an investment vehicle that has impressive returns with zero economic risk. How is this possible?

Traditionally, returns on investments come from inflation, inefficiency, speculation/risk, or violation of trust.

We have government bonds that push the interest rate floor that private institutions offer. We have arbitrage opportunities which increase liquidity between markets. We have investors making claims that something is going to be worth more or less in the future, arguably contributing to price discovery. We have institutions giving out debt in hopes that they’ll get it back with some interest. We have ponzi schemes where unscrupulous fund custodians provide some clients returns taken directly from the reserves of other clients until it all falls apart.

How is DeFi different?

Sure, all the same old tricks exist. There’s no shortage of scams, there’s volatility between markets, there’s speculation, there’s inflation and disinflation. None of this is new—no one is claiming it is.

Here is what’s new:

1. Non-custodial contracts (reducing the reliance on trusting intermediaries)
2. Algorithmic contracts (further reducing trust, introducing determinism, reducing inefficiency)
3. Atomic contracts: The ability to write a series of instructions with the guarantee that either all of it or none of it executes. This is key, and the consequences are most profound.

Contract Atomicity

If you’ve ever typed BEGIN; and COMMIT; then you’re familiar with atomic transactions in databases.

ACID-compliant database transactions have been a thing since the 70s, but it’s something that has never made it to the global financial system. A single institution might promise that a list of instructions sent to them would be executed as a single unit, but the reality is that anything that spans institutions will have multi-day settlement periods and often involve humans signing off on parts of it. Even within a single institution, operations are often batched and batches are executed periodically. Very little is actually real time in traditional finance.

Let’s say we see two marketplaces which value apples differently. We can buy a bunch of apples from one, haul them over to the other market, sell them for a profit. That sounds great in theory, but by the time we arrange the purchase from one market, load them onto our cart, and haul them over to the other market, a few thousand high-frequency trading bots from Wall Street have moved the price of apples a million times and we’re probably not going to make minimum wage on our effort.

To make it worth our while, the difference has to be substantial and our capital has to be huge to really take advantage of it. This is why arbitrage hedge funds are typically managing upwards of hundreds of millions of dollars in assets, and a single avid WSB reader wouldn’t dare compete… Usually.

Imagine we could pull out cash from our bank, buy apples, move apples, sell apples, and get cash back into our back account in a single atomic transaction. Either the whole thing succeeds, or none of it happens. It’s zero risk arbitrage (though there are fixed fees for the privilege).

That’s great! We can complete with high frequency traders now, but we still can’t compete with their capital.

But wait, what else can we do with atomic transactions?

Imagine we could take out a loan for a million dollars, buy a lot of apples, sell the apples, pay back the loan plus a fee, and keep the difference in a single atomic transaction. Either the whole thing succeeds, or none of it happens. It’s zero risk loans for zero time (except we pay a fee to the liquidity pools who lock their capital that we loan from). This is called flash loans.

Now we can compete with wealthy hedge funds, as long as we can afford the modest flash loan fees (these vary, but roughly 0.0X% in fees) and transaction gas fees.

There are other even wilder possibilities with atomic transactions, like flash mints (instead of loan money, create money for zero time), but let’s talk about zero time.

Zero Time

The longer a debt is held, the more unknowns are added to the probability that the debt will be paid out. A mortgage holder could lose their job, a bank could buy debt that represents a bunch of people who lost their jobs, a global pandemic could ravage our local economy. If my friend wants twenty bucks for a second, I’m not too worried about not getting it back unless they’re an illusionist. If my friend wants to borrow twenty bucks for ten years, I doubt I’ll see it again. So much can change with time, I’ll probably forget about it.

A flash loan does not exist outside of the scope of the transaction. In effect, a flash loan is debt that exists for precisely zero time. Aside from the real-but-tractable likelihood that there is a software bug in the system, there is no risk of an atomic zero-time loan not being paid back.

The idea is sound, even if there have been times when a particular implementation was not. It seems that only people who have trouble grokking zero-time loans are expecting software to be perfect in zero-time. 🙃

In fact, DeFi exploits are some of the most fascinating users of flash loans, since they’re able to amplify market imbalances in unexpected ways with incredible effect. These are not fundamental flaws, and they’ve all been mitigated in modern DeFi contracts, but I’m sure there will be more before things become completely safe and stable.

That’s the big difference with traditional finance: Even after eons of custodial trust violations, from the very first primate to borrow a tool and not return it as promised, we are still struggling with the same fundamental shortcomings. Meanwhile, DeFi on Ethereum has only been alive for a couple of years, and there is a very achievable end point of stability and safety.

FAQs

Is this investment advice? 😳🫴🦋

No.

Could we implement this on traditional finance infrastructure?

It’s possible. Meanwhile, we’re still seeing banks sweating to maintain billions of lines of COBOL running in production that was written 50+ years ago. Ask again in a hundred years?

Even if we could wave a magic wand and retrofit all of the world’s banking today, the custodial nature of traditional banking is what introduces a lot of the risk. Can a loan across multi-national banking institutions truly be risk-free if each institution has to trust the other side to keep up its end of the deal? Once we move to a trustless non-custodial system that has Turing-complete atomic instructions, we end up where we are today with Ethereum’s DeFi ecosystem.

No risk is never truly no risk!

Of course. Software bugs happen, human error happens, black swan events happen. The goal of these mechanisms is to dramatically reduce the number of intermediaries and cut down on the surface area for risk, in ways we haven’t been able to do before.

Huh, free money with no risk? Wouldn’t everyone put their money in this and the returns go to 0?

That’s not impossible! But keep in mind, flash loans is just one of a multitude of yield-earning mechanisms, and one with the lowest returns already. There are plenty of other mechanisms that pay far more but involve more hands-on babysitting (like adjusting collateral ratios as prices change) or have more risk (less mature smart contracts that could be exploitable) or are more speculative. Furthermore, as more money enters the ecosystem, more opportunity becomes available for flash-loan trading bots to do their thing.

How much yield could I get right now? Asking for a friend…

Depends on your risk tolerance and how hands-on you want to be. Many of these rates vary wildly from week to wee.

What are flash loan bots actually doing?

Here’s a well-documented smart contract bot that takes out a loan from Aave and performs arbitrage between two markets on ETH-DAI: https://github.com/fifikobayashi/Flash-Arb-Trader

More sophisticated bots in production today traverse much more complex paths across many lenders, exchanges, and trading pairs before completing a profitable cycle. All atomically, of course.

• Special thanks to Tracy, Charlie, Phill, and others for feedback.

This is specific to the wireless embedded mode, not tethered Quest Link mode. I tested it with the Elite Strap, which ought to be included by default.

Tracking

Tracking is “surprisingly good” as everyone says, especially superficially. It’s hard to visually detect glitches when the system is operating smoothly.

On the other hand, I did feel mild nausea after some casual use. Normally I can use my Index (or old Vive) for hours without nausea. It’s hard to tell if this is due to some more subtle tracking issues, or because of the limited lens controls, or purely from processing glitches.

It’s not hard to make the embedded computing system overload and jitter. Using it while apps are installing causes tracking failures, or using insufficiently “optimized” apps like VR Chat. The tracking will freeze occasionally or swing aggressively.

It’s not very common under more “Made for Quest” experiences.

I was particularly concerned about the Quest inside-out controller tracking but again I was surprised at how well they worked. Not perfect (there were positions where they jittered or disappeared), but better than expected. Under good operating conditions, it was more than tolerable.

Display

Text clarity is very very good, but the graphics fidelity on everything else is noticeably sad.

Granted it’s an underpowered platform, compared to an expensive gaming computer, but this comes with consequences.

Obviously “optimized” scenes are very low-polygon, but that can still work under the right context. The thing that is more noticeable is the textures are very low quality too. The end result feels kind of like playing a game on Low Quality settings in 800x600 resolution but on a 6K high-DPI display. The vector-rendered elements are very crisp, but everything else is from a different lo-fi universe.

The field of view is noticeably tighter than the Valve Index, but I am also personally less bothered by this than most.

No complaints with any screen door effect or godrays.

Wireless

It is very pleasant to be wireless. Wired headsets never bothered me as much as it bothers some people, but I do wish the Valve Index came out with a wireless module already. At minimum, it makes the “grab and play” experience a bit better.

On the other hand, I suspect the Quest 2 is a much better device when tethered to a gaming box via Quest Link. I haven’t tried it in this mode, since it’s hard to imagine it being better than the Index in any metric so why bother… But if it’s a question of budget, then it seems like a viable option.

Audio

While wearing the Quest 2, the built-in audio is fine. Not nearly as good as the Index, which is better than a lot of dedicated headphones!

On the other hand, the sound is more audible outside of the headset than inside. Anyone else in the room gets to experience everything you experience at x1.25 the volume.

One of the cool parts of audio inside of a head-tracked VR environment is that it’s easy to simulate 3D audio very well, this is great for the wearer but terrible for everyone else. I could feel a bit of nausea just sitting in the same room as someone playing the Oculus Quest 2, just from all of the simulated audio positioning shifting.

Thankfully there is an AUX port on the headset so it’s easy to put on your own headphones.

Comfort

There are only two IDP presets, luckily one was pretty close to my head shape. My eyelashes hit the lens a bit, and luckily I do not need to wear glasses.

With the Elite Strap, the device is a good weight and comfortable to wear for extended periods, no complaints. Not quite as comfortable and adjustable as the Valve Index, but a fair bit lighter. If the Valve Index is a Herman Miller Aeron Chair, the Oculus Quest 2 with Elite Strap is a budget look-alike from Staples that gets you most of the way there.

Certainly more than good enough to sit back and enjoy a full-feature 3D film, or dance around for a couple hours.

Controllers

No complaints but they do have a “budget” feel to them coming from the Index Knuckles, or even the Vive Wands. They’re small, but reasonably comfortable. Not certain they would win in a fight against a TV, or certainly not against some drywall (which my old Vive wands have more than enjoyed taking on).

Oculus Store

Compared to Steam, the Oculus Store is a sad experience. It was difficult to find a hierarchical listing of games or experiences. The search worked well, but you need to know what to search for. Overall it did not feel like the people who designed it live on the same planet as I do.

Facebook

The device and all of your purchases are locked to your Facebook account. Fuck Facebook. This is a deal breaker for me and should be for everyone, I would never spend my own money on anything that profits Facebook. My only hope is that they’re selling the Quest 2 below cost and that it’s thoroughly jailbroken soon.

Overall

I really wish there was another competitor in the “embedded wireless with optional tethered” tier that I could recommend as an alternative, but there isn’t. For people who can’t commit to a gaming box yet, there’s simply no other option. I can’t fault Facebook for cannibalizing and betraying the Rift team with the Quest line, it’s clearly the best move in our current VR ecosystem, especially at the price point they’re selling.

Overall it feels like a $500-600 device being sold for $370 USD (with the Elite Strap), with clear intent and inevitable success of dominating the entry-level tier of VR. I’m sure Facebook will more than make up any losses through the walled-garden they’ve assembled.

The drafts keep accumulating, how do I trick myself into publishing more? Perhaps by reducing the effort required for the next step? Let’s do it!

Architecture

My blog is statically generated using Hugo, the code is hosted on Github, then when a pull request comes in it is built, previewed, and published on merge by Netlify.

The blog post drafts are posted as Github issues, so there is a clear gap: How do we convert issues into pull requests for Netlify? Enter Github Actions!

Github Action: Issue to Pull Request

My full workflow lives here if we want to jump ahead, but let’s break down the broad strokes.

I decided to trigger the publishing process once an issue is labelled with ‘publish’, so let’s start with that:

name: Publish post from issue

on:
  issues:
    types: ['labeled']

jobs:
  build:
    if: ${{ github.event.label.name == 'publish' }}
    runs-on: ubuntu-latest
    steps:
      ...

Next up we want to specify the steps, first thing is to check out the repository into the action’s environment:

      - uses: actions/checkout@v2

Once the source code is available, we want to generate the blog post from the issue metadata. Here is a very basic version of this, though I ended up doing more tweaking in the end:

      - name: Generate Post
        env:
          POST_TITLE: ${{ github.event.issue.title }}
          POST_BODY: ${{ github.event.issue.body }}
        run: |
          cat > "content/posts/${POST_TITLE}.md" << EOF
          ${POST_BODY}
          EOF          

This shoves the body of the issue, which is already markdown, into a markdown file named based on the title of the issue. This is a good place to add frontmatter, or slugify the title, or whatever else your blog setup requires.

Running the payload through environment variables helps with not needing to escape various characters like `.

And finally, we make the pull request using Peter Evan’s create-pull-request action which makes this super easy:

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v3

This is the minimum of what we need, but we can specify all kinds of additional options here: like auto-deleting the branch, setting a custom title, body, and whatever else. Here’s an example of what I’m doing:

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v3
        with:
          delete-branch: true
          title: "publish: ${{ github.event.issue.title}}"
          body: |
            Automagically sprouted for publishing.
            Merging will publish to: https://shazow.net/posts/${{ github.event.issue.title }}
            Closes #${{ github.event.issue.number }}            
          reviewers: ${{ github.repository_owner }}
          commit-message: "post: ${{ github.event.issue.title }}"

Result

When my blog post draft is ready, I add the tag and the Github action takes it away, creating a pull request:

The pull request automatically pings me as a reviewer, and includes a “Closes #X” line which will close the draft issue once the PR is merged. Very convenient!

Once the pull request is ready, Netlify takes it away, builds everything and generates a handy preview:

I can make sure everything looks right, and even apply edits directly inside the pull request. This is another great step to send a long blog post for feedback, using all of the wonderful Pull Request Review features!

When all is said and done, merging the pull request triggers Netlify to publish my changes to my domain, and merging closes the original issue, and I’m done!

Bonus

Drag n’ drop images work in Github Issues, so it’s super easy to write a quick post with a bunch of screenshots or what have you.

It’s important to me that I’m not too tightly coupled to third-party services, so the pull request and code merge flow makes sure that all of the published state continues to live inside of my Git repository.

I can still make blog posts the way I used to: Pull the latest repo, write some markdown, and push to publish.

I added a little frontmatterify script to process the incoming markdown and convert the remote Github Issue uploaded images into local images that are included in the pull request. The script also generates frontmatter that I use for Hugo. It’s a bit clunky but works for now.

Alright, let’s do this.

Sourdough recipes are more involved than regular bread recipes, that’s for sure. There are many steps, and bakers can’t seem to agree on many of them. That’s no accident, a great sourdough bake needs to be adjusted to our kitchen and our starter.

What to expect when you’re expecting Sourdough

This article is not a sourdough recipe or guide. It’s more of a guide for reading sourdough recipes. It’s everything I wish I knew after reading my first sourdough recipe. When we get that faithful link from our baker friend with the only caption saying “just do what it says,” read through it, take it in, then come back here for some added context. (For some decent recipes, check the links at the end of the article.)

Let’s break down a standard sourdough bread recipe, look at what varies between them, and how to adjust the recipe fit our kitchen.

A typical sourdough recipe comes down to four things:

1. Component ratio: How to adjust recipe measurements to fit the size loaf we want.
2. Component ingredients: What are we using to make our sourdough? What kind of flour?
3. Time, Temperature, and Yeast: This is what varies from baker to baker, and what we need to know to compensate in our steps.
4. Steps: The bulk of the recipe, from crucial technique to flourishes and rituals.

Component Ratio

Whether our recipe measures in grams or ounces or cups, the thing that really matters is the ratio between ingredients: Starter to Water to Flour.

For example, 50 grams of starter, 50 grams of water, and 100 grams of flour is 1:1:2 in ratio short-hand.

It can also be expressed as a Baker’s Percentage: 100% flour, 50% starter, 50% water. When using Baker’s Percentages, everything is relative to the weight of the flour, so flour is always 100%.

Once we have the ratio, we can scale the recipe to whatever total quantity we’d like, whether it’s a small 300g bun or a big ol’ 1.5kg absolute unit.

The ratio also tells us the hydration of the bread (baker percentage of total water content). Higher hydration can make the bread’s crumb more open and fluffy, but it can also make the dough stickier and more difficult to work with. This is one of the common things that vary in recipes, whether explicitly or indirectly.

We can use a Bread Calculator to figure all of this out ahead of time, and tweak the components to meet our goal.

• https://breadcalc.com/
• http://brdclc.com/

Tried at 60% hydration loaf last time but want to bring it up to 75% this time? Plug in our measurements and tweak the water or flour components until our hydration ratio where we want it.

Other components are usually expressed in baker’s percentages too, like 2% salt is standard.

Component Ingredients

Okay, so we have our ratio of flour and water, but what kind of flour?

Most beginner sourdough recipes recommend using Bread Flour. It has more protein than All Purpose Flour which gives the starter yeast more nutrition to work with.

There are many other kinds of flours out there, like Whole Wheat Flour and Rye Flour, which have even more protein. If all you have is All Purpose Flour and Whole Wheat or Rye, then considering mixing them to give your starter yeast more to work with. Too much Whole Wheat or Rye can be difficult to work with, so start with majority of your base flour (Bread Flour ideally, All Purpose otherwise). Maybe something like 5:1 base flour to other flour, and tweak from there.

Avoid flours designed to be low on protein, like pastry flour.

Once we’re ready to experiment more, we can toss in some herbs, cheese, seeds, the possibilities are endless!

Time, Temperature, and Yeast

Any sourdough bread recipe will have a bunch of steps with specific timelines they recommend. Half hour to rest, a few hours to bulk ferment, another period to proof. The problem with most recipes is that they’re written for the author’s specific kitchen and starter.

We’ll stumble on professional baker in one end of the world heatedly debating another baker on the other side, both with thousands of loafs under their belt but they just can’t agree on The Correct Way To Make Sourdough! “I’ve always proofed mine for no more than 3 hours and it comes out perfect every time,” one will insist. “No way, you need to proof for minimum 5 hours, until a flock of pigeons fly by the window,” the other will protest.

While I’m just someone who read too many recipes and discussion boards on the topic, here are some of my notes on what I discovered truly matters:

Ambient Temperature

A cold kitchen will take a lot longer for a dough to rise than a warm kitchen. It can be the difference between a 3 hour bulk fermentation and an 8 hour. Or 10% sourdough starter and 30% sourdough starter. If we have a really warm kitchen, we can scale down the amount of starter we use to slow down the fermentation. A longer fermentation can yield a richer sour flavour, so we want that.

It will also take a lot longer for a new sourdough starter to mature in a cold kitchen, one week can become two weeks. It can help to create a warm space for the dough to rise more efficiently: An oven with the oven light on, or a warming mat typically used for seedlings. Be careful to not go too warm, the yeast starts to die at around 100F. 80–85F is the recommended range for a good efficient rise. Periodically checking the dough’s core temperature is a good way to control this variable better.

Starter and Yeast Activity

A less mature starter is less active, possibly not even ready to make bread with. If we used a low-protein flour for our starter, it can take longer to ramp up. When a starter is matured, it regularly doubles or triples in volume after a feeding. With consistent feedings, it gets a kind of metabolism where you can rely on it reaching peak activity at a specific time during the day. It can help to use the starter as it approaches its peak activity, especially if we’re working with a cold kitchen.

Watch out for the infamous starter false start: Around day 3 or 4, the starter will spike with massive growth and beginners will rejoice about how ready their starter is but it is for for nought: This happens because an adjacent bacteria took hold of the starter and consumed all of the nutrients until it burned itself out. With consistent feedings, the desired yeast sourced from our flour grains will ultimately prevail and develop a healthy cadence.

Time

Aside from changing the temperature, and the quantity and activity of our starter, we’ll need to adjust the timing of our steps. If the kitchen is cold, ferment and proof longer. If the yeast is not too active, extend our timeline even further. It can help a lot to learn what the quality of the dough should be at each step, to know whether to proceed to the next step or wait longer. There are various tests we can do, such as the floating test to see if the starter is ready to be used; the windowpane test to see if we have sufficient gluten development; the poke test to see if the dough is sufficiently proofed for baking. We’ll go more into it in the Steps section.Our dough can be underproofed or overproofed, and we might not even realize it until we pull it out of the oven, wait the prerequisite hour, cut into it, share our joy on instagram and then receive a DM from a professional baker that just says “it’s underproofed.”

An underproofed bread won’t have enough structure to fully rise during the bake, all of the gasses from the yeast will accumulate into few large bubbles, parts of it will be very dense and maybe even raw tasting. It’s much easier to underproof as a beginner, especially with an immature starter and a cold kitchen.

An overproofed bread won’t have an ideal crumb, such as very small holes, or it could collapse under its own rise because the gluten relaxed too much. If we discover the dough is overproofed before baking, we can fold it a few more times to reactivate the gluten and give it another short proof before baking. I’ve found it hard to find consensus on what qualities an overproofed loaf has, so it’s safer to err on the side of overproofing than underproofing if we must.

For other kinds of baking, when we just mix some ingredients and toss them into a temperature-controlled oven, it’s appropriate to follow the recipe to the letter. For sourdough bread baking, we need to be ready to adjust the recipe to fit our environment and our needs.

Steps

Many recipes have a lot of steps in common. Some of them are necessary, others can be substituted or adjusted, others are purely ritual. It’s useful to know which is which, and what we can do with them.

Maybe we started our bread too late in the day and can’t stay up until 2AM to do 6 additional folds, or maybe we don’t have time to bake in the morning and would prefer to avoid refrigerating overnight.

1. Levain: This is a process for taking some of your existing starter and making a separate sister starter that we can use for making our loaf while keeping our original starter.

   🤔 If we have a large enough discard from our original starter, we can use that instead.

2. Autolyse: Typically done while the levain is prepared, it’s for mixing the bulk of the recipe’s flour and water separate from the starter and letting it rest until the levain is ready to be mixed.

   🤔 If we’re skipping the levain step, skipping the autolyse step is not catastrophic for beginners. We can mix our discard all together, or I prefer to mix most of the water with the discard first and then add the bulk of the flour.

3. Mixing Techniques: As a beginner, do whatever it takes to get everything combined into a shaggy doughy mess. Minimize how much flour spills over the counter and makes a mess, and try to scrape what we can from our hands, but it’s not a big deal. We can slap, we can fold, we can slam, we can even yell profanities at it while we pinch it a bunch.

4. Rest and Add Salt: Many recipes are very serious about leaving the salt and a bit of water until after mixing the bulk of the dough and water. The theory is that salt leeches moisture from the flour so it won’t be absorbed as evenly if we do it all at once. Once we mix in the salt, the feel of the dough instantly changes into something much less shaggy and less sticky, it’s delightful.

   🤔 Foodgeek did an A/B test on this, and it doesn’t seem to matter if we mix in the salt with the Autolyse step. Seems it’s more ritual than anything, so no need to panic if we mixed in salt prematurely. It is convenient to save a bit of our water reserve for mixing the salt, though.

5. Stretch and Fold: During the “bulk fermentation” step, we’re usually instructed to perform a number of folds to help develop the gluten in the dough so that the webby network of the bread will have enough structure to support itself around all of the lovely bubbles produced by the yeast as it rises and bakes. Different recipes have different techniques here, with different timing. Some recipes suggest using oiled hands for working with dough at this point, but water-wet hands are even better and less messy and doesn’t introduce oil to the dough which can affect the recipe composition.

   🤔 Another Foodgeek contribution on the topic, it certainly seems worth doing at least a couple of good dough perturbations over a few hours. With a sufficiently mature yeast, even doing nothing produces decent sourdough but not quite as good and we’re taking a gamble on the activity of our yeast to compensate. If we’re busy, do at least two nice gentle lift and coil sets spaced out by 30–60 min, and let it rest until it rises 50–100%.

   🤔 Do the window pane test if we’re unsure if it needs to rest more. Colder environments or less mature yeast could require more time than prescribed here.

6. Fold, Roll, and Stitch: By shaping our dough at this point, we create a tense form that will present the rough shape of the final loaf. With a good tight roll and stitch, the loaf will have a better chance to rise vertically rather than sprawl into a blob.

   🤔 I’ve unintentionally totally for science skipped this step once and ended up with a very flat loaf that sprawled the circumference of the dutch oven. As far as technique goes, this is one of the harder steps but it pays off to get better at it.

7. Banneton, Seam Side Up: The shape of the banneton helps reinforce the final form of the loaf as we give it additional time to rise. If we don’t have a banneton, we can use any form that is not too much bigger than the desired loaf size. I use a colander lined with a linen towel.

   🤔 This is the companion step to the Fold, Roll, and Stitch. It’s similarly important, but the seam side up is not a huge deal if we messed up. The loaf won’t have that perfect smooth top to work with on the surface, but it will be just as good inside. Remember to dust the lining with flour so it won’t stick, or some corn meal if we’re feeling fancy.

8. Overnight in the Fridge: Proofing in the fridge is a recurring step from all bakers who love to bake first thing in the morning. What about the hungry night owls? What about all the sourdough bakers who have been making this lovely bread for far long than refrigerators have existed in our society?

   🤔 We can replace the fridge proofing with a 3–5 hour proof at room temperature, on the longer end if the temperature is low or the starter is less active. Do the poke test if we’re unsure if it’s ready: The recess in the dough from the poke shouldn’t spring back immediately when it’s ready. Cover in plastic or wrap in a bag to prevent the dough from drying out while it’s proofing, especially if we’re refrigerating overnight.

9. Pre-heat and Bake From Cold: Pre-heat the oven to maximum heat, typically 500F, then quickly take out the dough from the fridge, flip onto parchment (since we did seam-side up), dust with some flour, spread the flour, score with a lame (a fancy razor holder), and commit it to the flames.

   🤔 If we don’t have a dutch oven, or a covered cast iron pot, we can use a baking steel or even a baking sheet. We’ll need another pan placed at a lower rack full of boiling water, to add the moisture to the oven necessary for a nice crispy crust. The lidded dutch oven captures and retains the moisture from the dough, so it’s a bit simpler.

   🤔 What if the dough is looking a little sad after an overnight in the fridge? This can happen if the yeast isn’t as active as it could be. Take it out from the fridge and give it one more room-temperature proof for 2–4 hours, bonus points if we can proof it somewhere a bit warmer (80–85F), like a seedling warming mat.

   🤔 No lame? No problem. If we use a safety razor, carefully use a clean razor by hand. Worst case, just grab a nice sharp knife and use that to score. End to end, leaning 45 degrees, half-inch deep cut. Not a huge deal if the scoring step is botched or skipped, the bread will still form just fine but it won’t expand along a specific gorgeous seam of your making.

10. Wait For The Hardest Hour Of Your Life: When we pull the loaf out of the oven, it’s not quite done baking. A rookie mistake is to huddle around the glorious steaming orb-treasure and tear into it like a pack of post-apocalyptic savages. A true intellectual will place an ear near the crust as it cools and hear the crackling transformation within.

    🤔 If we don’t wait, it will still be edible but: The inside will be extra stretchy or gummy, it might have an “undercooked” vibe to it, some of the final notes of flavour won’t quite develop. Seriously, just wait at least an hour, or until it fully reaches room temperature. If it’s steamy when we cut into it, we didn’t wait long enough.

You Can Sourdo-ugh It

Let’s be real, we’re all in this for the sourdough puns.

Here’s a list of ideas we can try if it’s just not working out:

• Suspect the starter is just not ready? Use extra starter, like 30%. If you desperately want vaguely sourdough-y bread and can’t wait, sprinkle a bit of instant yeast when you mix in the starter (half teaspoon should do).
• Other kinds of breads to make while the starter is maturing? No-Knead recipes are great, or Almost No Knead. I like ones with a lager beer. I’m a fan of sourdough-hybrid chimera breads. To improvise a recipe, substitute some of the hydration with sourdough starter (remember it’s 100% hydration dough, or 1:1), and substitute some of the water with beer.
• Keep making that discard when you feed, sometimes I’ll keep the feeding ratio but skip a discard to have an extra-big discard the next day. Lots of things we can use that discard for, or even just toss some globs on a frying pan and make crumpets.
• Starter not starting? Try a different flour. The bulk of the yeast in the starter comes from the grains that the flour is made of, and sometimes cheaper flours aren’t the best source of a good healthy yeast — especially avoid bleached flour. Buy the fanciest bread flour available, just to be sure. Try mixing in 5–20% whole wheat or rye in there for extra protein. Some restaurants or bakeries will give away (or sell for super cheap) their starter, if we’re desperate to bootstrap from a known quantity.

Even if mistakes are made along the way, there’s a good chance we’ll end up with a decent tasting bread product in the end. We must eat our shame as we will our inevitable victory.

Additional Resources

• The Perfect Loaf: Simple Weekday Sourdough Bread: Good comprehensive recipe with a handy timeline visualization, good for beginners.
• Video: The Ultimate Homemade Sourdough Bread: Charismatic long-haired fella with a large Youtube audience making sourdough, good instruction for beginners.
• Video: Tartine Country Loaf by knormie: Nice simple quick video showing the process and techniques.
• Video: Brad and Claire Make Sourdough: Hilarious but some advanced techniques without much context for beginners. Honestly this is what got me started, which did not yield the best first result. Feel free to skip until later.
• Foodgeek Blog and Foodgeek Videos: Big fan of this, much of what I learned for this post was based on Sune’s work of methodically testing out variations of every variable in a sourdough recipe.
• /r/Sourdough: Obligatory topical subreddit. Can’t go wrong. More resources in the sidebar.
• Bread Hydration and Conversion Calculator: Anytime I start a loaf, I plug in my intended components here, make some tweaks to reach the desired hydration, and dive in.

🍞

Proud to be part of the team who built this chonk of vital internet infrastructure. ❤️

Big sincere thank you to our maintainers: @theavalkyrie @sethmlarson @haikuginger @Lukasaoz @sigmavirus24, and to all the other contributors for this very important work. https://t.co/ea3iFClKD5

Since urllib3 was created in 2008, we have gained several amazing maintainers and hundreds of contributors. Any time you do anything that touches HTTP in Python, you’re probably using urllib3 behind the scenes. It is the 2nd most downloaded third-party Python package, after pip.

Tens of thousands of engineering hours were donated by people working on their own time, unpaid. The whole world benefited from these important donations.

Generous companies have helped the urllib3 contributors and maintainers financially over the years. In the spirit of transparency, I’m going to take a moment to talk about some of our recent funding and how that money was spent.

Supportive Employers

Above all, I want to applaud employers who are actively encouraging their team to contribute back to open source as part of their job. You’re already part of our README, but once more for the active supporters:

• Thank you Google Cloud Patform for supporting Thea, our lead maintainer.
• Thank you Abbott for supporting Seth, who has been doing the bulk of the work for a long time now.

And thank you to all of the employers who have contributed your company’s resources to our project in the past: Akamai, Hewlett Packard Enterprise, and others. If your work on urllib3 is actively being funded by your employer, please send a pull request to be added to the README.

Grants and Sponsorships

We have received a variety of support in various shapes and sizes over the years. Most recently:

• Thank you Computer Emergency Response Team of the Government of the Grand Duchy of Luxembourg for funding 8 weeks of Seth’s time towards improving urllib3’s security and robustness.
• Thank you Gitcoin for allocating over $6,000.00 in funds over 3 months that will go towards Seth’s time on urllib3.

Additionally, urllib3 joined Tidelift Subscription to provide better support guarantees for their paying customers. Our current revenue from the subscription is $417.00 per month ($10,000 over 2 years). This funding is going to Seth for handling support requests and releases. Previously, I was taking $208.50 per month for work as backup maintainer. Thank you Tidelift!

Does your company benefit from Python?

With over 50 million installs per month, urllib3 is a core part of the world’s infrastructure. There is a never ending stream of improvements and fixes that need to be done, especially as HTTP continues to evolve as a technology.

If you can convince your management to allocate a budget to support the improvement of urllib3, please get in touch with me or Thea. We will find the right urllib3 project and contributor to make good use of the funding, and the whole world will benefit from it.

Thank you.

I spent fifty hours setting up my new computer, and I feel a mixture of shame and pride about it.

We spend a lot of our lives in our computers. Working, socializing, relaxing. On the work laptop, at the home desktop, on the phone in bed.

We live in our computers, and we do little things to make ourselves feel more at home in them — a little more cozy. We change the wallpaper, install some new apps, buy a pretty case and some stickers for the back. We find ways to make our devices different from other peoples’. We personalize what we can. What we’re permitted.In 2008, I bought my first iPhone. Shortly after, I bought my first Macbook Pro. Coming from Linux, the Apple ecosystem felt clean and fresh. It felt like checking into a hotel. Everything I will need was laid out on the counter, and anything else could be arranged by the concierge (perhaps for a fee). I made myself at home.

Over the years, I started to feel disassociated from my devices. They were mine, but they didn’t feel mine. The immersion of ownership would frequently break as a corporate policy kicked my favorite app out of their store, or a feature I wanted was forbidden by the exposed API, or the pressure to buy newer hardware grew each year with forced software upgrades.

Imagine living in a hotel. You check in, put your backpack down on the luggage rack, and kick off your shoes. It’s a little different from your last hotel, but also the same. A television that you avoid, not because there is work to do but because the remote looks kind of gross. A lamp that is using up the only power outlet next to the bed, which you need for charging your phone overnight. There is a desk, but the padded office chair doesn’t lift enough to use it comfortably.

You’ll be in the hotel for a while, so you can make yourself comfortable and add a bit of yourself to it. You request a fish bowl from the concierge, and you name the fish Chee (short for Cheeto). You bring some chocolates from the Quik Mart a few streets away. You play some music on the complementary bluetooth speaker.

Ultimately, the hotel is an organism that operates outside of you. The unfinished chocolates disappear after a cleaning. The speaker keeps disconnecting sporadically. They take Chee away.

I switched to Android a few years back (after Lollipop came out, the first good Android). This week, I am giving up my fourth Macbook Pro — my final Apple device. Apple makes beautiful devices that were unrivaled for a long time, but convenience and uniformity comes at a price. I have come to crave fragmentation.The shame is obvious: I didn’t spend those fifty hours doing things like building better insulin control software for diabetic people or campaigning for affordable housing.

I spent those hours building my perfect computer home. Like a fresh cabin in the wilderness, there were some false starts. Some kernel modules were missing, or the full-disk encryption was misconfigured. At one point, about twenty hours in, I knocked it all down and started from the foundation again.

I learned very much — about binary firmware embedding in the kernel and LUKS disk encryption and systemd quirks.

More than anything, I made it feel mine. I will keep tweaking everything throughout the lifetime of this laptop and I’m sure much of the configuration will survive to the next. Lay out some area rugs, new cutlery, softer lighting, art for the walls. Hopefully not fifty hours in one week, but a few hours here and there. With each improvement, I will feel more at home, and there is no limit to what I can do.

I am proud of my new computer home.

I feel like there is more to learn from failure stories than success stories, so let’s start with those.

What not to do

I’ve handed over several projects before, and some didn’t go as well as I’d hoped. Here are some mistakes I’ve made:

1. Don’t transfer the project to the new maintainer’s namespace.

Once upon a time, I had given up developing s3funnel, a multi-threaded S3 client. I just wasn’t using S3 anymore, and I had no desire or need to support new features. I announced that I’m looking for new maintainers, and a contributor volunteered. Great! I transferred the project to his ownership, Github kindly permanently redirected, and the project moved along without me.> Couple years later, the new maintainer also gave up on s3funnel and largely disappeared. I don’t blame him. It wasn’t even his project—it wasn’t his baby. A bunch of pull requests piled up, unanswered. I wanted to put in a few hours to merge them, but I couldn’t. This was my mistake.

Don’t expect the new maintainer to stick around longer than you did. If the maintainer leaves without finding a replacement, you need to be able to take back the project. You can add new maintainers as collaborators on your repository or move the repository to an organization namespace which can have teams added and removed over time.

2. Don’t micromanage the new maintainer.

I don’t have an anecdote here, but really: The entire point of handing over a project is to release yourself from its burden. Let go, for your own sake.

Similarly, as a new maintainer of someone else’s project: Maybe they’re doing it because they want the responsibility and experience of managing other people—being the boss. They’re certainly not doing it to gain yet another boss. Let go, for your maintainer’s sake.

This doesn’t mean that you need to disassociate yourself entirely, but it does mean you need to defer to the new maintainer’s authority. You are just another contributor now, not the lead. Respect the new leader and empower them. I promise that a maintainer who feels respected and empowered will do better and stick around longer.

3. Don’t expect more from the new maintainer than they’re giving.

Unless you’re paying and employing the new maintainer to take over as part of their job description, they don’t owe you anything.

The new maintainer has no obligation to stick around forever. It’s not ideal, but it’s important to respect that the new maintainer is well within their rights to disappear.

Check in once in a while and make sure things are still going okay and their lifestyle permits them to continue as the maintainer. Maintaining open source is hard work, support them if they need to give back the torch/albatross.

How to do it right

So far, urllib3 has enjoyed two successful maintainer transitions. Here’s what worked well:

Finding a new lead maintainer

It can be tempting to put out a public call for new maintainers, but that’s best left as a last resort. The goal is to find someone who is already familiar with the codebase and has shown some commitment to working on it over time. We want to avoid choosing a maintainer who didn’t know what they were getting into and have them abandon the project a week later, forcing us to go through the whole process again.

I’ve found good results in reaching out to specific people who would be good candidates. In both cases for urllib3, the new lead maintainers were long time contributors to the project. Even better if they’re already co-maintainers. Even double-better if their employer allows them to maintain the project as part of their job. It doesn’t hurt to ask, and it helps a lot.

Foster a team of co-maintainers

Additional maintainers are there to help the lead maintainer. They’re the go-to for handling trivial issues, doing code reviews, or taking random tasks when time permits. When it’s time to choose a new lead maintainer, the co-maintainers are a great place to start from. The co-maintainers are there to help with the transition, too. It’s less scary when you’re not alone.

Make an explicit announcement for the transition

Putting everything in a project issue labelled Announcement and linking to it everywhere for discussion and transparency has been great.

Have a checklist for what that needs to be done

I like keeping this checklist public, alongside the announcement, because it helps raise awareness that this person is now getting access to all these things for the project.

• Announcement post
• Update README and documentation
• Repository collaborator/admin access (e.g. Github)
• Release publishing access (e.g. PyPi)
• Docs management access (e.g. ReadTheDocs)
• Continuous Integration admin access (e.g. TravisCI)
• Signing key access, or publish the new signing key (e.g. for GPG signed releases)
• Confirm that the release process is documented and achievable by the new maintainer
• Subscribe the new maintainer to the relevant StackOverflow tags

Switching to a new maintainer hands over a lot of trust to this person. That’s the nature of the gig. More transparency about the powers that this role comes with helps the users plan their security models accordingly.

But for now…

I feel like we all hope that our work will outlive us, in one way or another. Handing over the reins of a project is a natural part of a successful project, and something that will become more common as the open source community continues to mature.

When the time comes, let’s do it right.

@hyfen pong

— Andrey 🦃 Petrov (@shazow) April 20, 2007

My first tweet.

I haven’t tweeted in over two months.

This is very unusual for me. I’ve been an avid tweeter since 2007. Writing tweets has become a part of my identity to the point where most my bios mention that I’m a tweet ghostwriter—composing and editing tweets for friends is one of my favourite things to do.

Sometimes I worry the NSA might be spying on me through my desktop's webcam. Then I remember it's Linux and even I can't get it to work.

— Andrey 🦃 Petrov (@shazow) February 23, 2014

My most popular tweet.

I stopped reading and posting to Twitter for my mental health, but it’s not just about Twitter.

Mental health

Modern life is a minefield of addiction. I’m not talking about substance addiction, but behavioural addiction. News with clickbait titles, discussions filled with polarizing trolls, mobile games with clever viral loops, social media with a never-ending stream of dopamine hits.

Do you ever spend an hour just reading news? New tabs sprouting faster than we can close them. Just when we get close, we’re back to where we started—checking Twitter again, or Reddit, or Hacker News, or Slack. A few moments passed, so there is plenty of fodder for some fresh tabs to work through.

Do you ever feel justified being inside the feedback cycle? It feels like learning, but do we ever learn anything? It feels like engaging, or is it fluff? Are we even paying attention? Or are we coasting on autopilot with a machete through a never-ending forest of tightly-packed tidbits because that’s what we’ve trained ourselves?

Doing something about it

I started meditating daily exactly one year ago. I’ve been using Headspace, but my year subscription is about to run out and I’ll probably move onto something else.

Eventually, I noticed something: Meditation calmed my mind. Duh. But I noticed something else: Reading social media and news would make my mind more turbulent. After catching up on my Twitter feed, I would be become distractible and unmotivated. I noticed that my willpower would diminish and I would get depressed, falling further into the cycle of feeding on news because it’s the only thing that felt easy enough to do.

For a while, I used meditation as a counterbalance to binging on the hail of micro dopamine hits. It helped, but it was not enough.

Removing triggers

For the past year, I looked for things in my life that trigger me into negative behaviour. Things that make me less than the kind of person I aspire to be. Removing them has been difficult, and I’ve found that the best way for me has been to pick one thing at a time and quit it cold turkey. Once my lifestyle adapted to its absence, I could move on to the next thing.

Most recently, I’ve been focusing on quitting reading discussions which draw me into petty arguments and quitting news sources that are infinitely abundant. This means quitting some Slacks, not reading the Reddit front page, and not reading Twitter.

It has been two months. I’ve been more productive and my mood has been more stable, but I still feel the temptation to fall back into that cycle. I need to be careful.

Moving forward

Since I eliminated Twitter, I started writing more long-form content again. I want to encourage myself to do more of that and I want to share my posts with my followers, so I’m going to try a new set of rules for myself:

• I’m not going to read my Twitter feed.
• I’m going to avoid replying on Twitter (or on social media in general) and instead try to have more private conversations instead. Please DM me when possible.
• I am only going to post on my Twitter to share long-form content.

For people I’m following, I’m trying to subscribe to your blogs and newsletters whenever possible.

If you’d like to catch up, share something cool with me, or just miss my tweets: Send me a message and we can chat!

A case study between Python and Go.

In Go, a common complaint from newly-minted gophers who come from another language is the error handling pattern:

result, err := DoSomething()
if err != nil {
    return nil, err
}

another, err := SomethingElse(result)
if err != nil {
    return nil, err
}

// We can be a bit more terse if we don't need to save any
// variables outside of the if-scope:
if err := MoreWork(another); err != nil {
    return nil, err
}
...

Any time we write similar-looking code over and over, that’s considered boilerplate.

A key principle of programming that we all learn is Don’t Repeat Yourself (DRY). In a way, that’s the entire point of programming: To automate a task that we keep repeating manually. Who wants to keep artisanally sorting text files each morning when we could have a program do it for us faster and more reliably? Similarly, why should we keep writing some code pattern over and over when we should be able to abstract it away into some terser syntax?

Proportional work

After writing Python code for over a decade and becoming quite proficient at it, I’d take any opportunity to write terse code. It feels good to be clever and more code means more bugs, right?

One thing I didn’t notice until I switched to writing Go as my primary language: The proportionality of work done in Python code is hugely variable.

What do I mean by proportionality? Consider these two lines:

a = some_variable + 42
b = sum((j if j % 2 else 0) for (j, k) in results if k)

The second line does a lot more work than the first line. The first line is a simple integer addition, while the second line has a loop and a variable split and two conditional branches and an accumulator on a generator.

In Python (and many other languages), it’s very easy to unintentionally hide tons of work in a single line of built-in syntax. Some lines do almost no work, other lines do a moderate amount of work, other lines do what I’d describe is tens of lines worth of work—a lot of work. It varies a lot, even in beginner code.

In Go, I’ve found that this variability is much more diminished. A loop is always a loop, an error check is always an error check (rather than implicit exception propagation), a logic branch is always a branch.

This is the most reasonably-terse way I could write the above in Go:

b := 0
for _, r := range results {
    j, k := r[0], r[1]
    if !k || j % 2 == 0 {
        continue
    }
    b += j
}

Is this good? I believe it is. I believe this code is more proportional to the complexity of the work that it’s doing. It’s also possible to write Python in a similar level of proportionality, why don’t I?

When reading proportional code, it’s easier to notice where the interesting bits are. It’s easier to notice where the bulk of the work is being done, and focus our review on that. Maybe this is subjective but I posit that the code’s shape looks more like what it is.

We can continue to argue that it’s easier to understand what the work is actually doing, but that’s not a point I want to make. Instead, I want to make a different point: It’s easier to tweak what the code is doing.

Opportunity for correction

After writing a lot of code in Python, and writing a moderate amount of code in Go, I noticed an interesting phenomenon: I tweak code very differently in Go.

Programming is a very iterative process. As we implement our solution, our mental model of the problem evolves. We often go back and change some assumptions, tweak our data structures, remove obsolete crutches and stubs, make error handling more robust, and so on.

I noticed that when I wrote Python code, I would often go out of my way to avoid messing up a beautiful terse set of lines by moving logic to places other than where it might naturally belong. I would unconsciously move complexity from where it belongs to a tangential place that made the tweak more complex than it should have been.

For example: Rather than refactoring a try/except block into separate appropriately-layered method calls or multiple try/except phases, I’d introduce a variable to maintain error state that gets handled in a finally block. (An example of this pattern in urllib3.)

When I write Go, I noticed that my tweaks almost always go exactly where they naturally belong. My boilerplate doesn’t stay untouched!

For example: I’ll usually write lots of Go boilerplate in my first iteration, but by the time I look at my code closer to release I notice that it’s no longer looking like boilerplate. By the time I’m done—adding more recovery scenarios, better logging, augmenting errors with more context, handle more edge cases—most of my boilerplate gets a lot more interesting. I did not realize that good boilerplate could be fertile ground for iteration.

When a friend was reading through the source code for ssh-chat, he was surprised that I implemented my own Set type. I explained that while Go doesn’t have a built-in Set, it’s just a few lines of boilerplate to make your own on top of a map. In fact, I noticed that my version of Set evolved to be fairly specific to how it was being used. In retrospect, I’m glad that I was tweaking my own implementation iteratively rather than spending time working around whichever limitations a generic library might have had.

I realize now that disproportional code makes me unintentionally dance around it like tiny black holes of complexity. Having proportional boilerplate helps balance out the ease of modifying it with the amount of work that code is actually doing—whether it’s error handling or looping or whatever else.

Proportional code creates less complexity

I am not claiming that more lines of proportional code is less buggy than fewer lines of disproportional code.

I am not claiming that all boilerplate is good: boilerplate can be disproportional in the other direction, too—where it’s doing far less work than we’d expect.

My claim is: For non-trivial projects, proportional code is not cumulatively more lines than disproportional code.

When we write disproportional code (or code that varies a lot in proportionality), we shift natural complexity into unnatural places which is an unexpected sacrifice. Our beautiful one-liners are short indeed, but the rest of the project suffers in other places to pay off that purchase.

By the time we’re done iterating and fleshing out our project, we might not be winning as much as we’re losing from getting rid of boilerplate indiscriminately. Proportional boilerplate can help us iterate in a less constrained way.

Popular password managers work by maintaining an encrypted database of many secrets, protected by a combination of the master password and access to the encrypted database file that is synchronized across your devices. Picking a strong master password is crucial in case one of your devices is stolen or the cloud storage that is hosting your password file is compromised.

1. High-entropy memorable pass phrases

I recommend this generator: https://github.com/redacted/XKCD-password-generator

It’s written in Python, it has good defaults, and a sensible built-in word dictionary (65,355 words). You can install it using

pip install xkcdpass

You can tweak the length and formula with various command-line flags. I recommend getting a whole bunch of passwords and visually picking one from the list.

$ xkcdpass --count=100
jewelweed cruzeiro scrawny preempt edgeways ceramist
vendor sacker someone elevator jeweled croaky
ammonia American bunk bed rhymer velleity drenched
linger largesse plain thoraces withered big deal
Rolland wheelie empanada repossess colic hosteler
....

Make sure to pick from the list rather than making up your own, because humans are much worse at being random than we might intuitively think we are.

2. Write it down

Yes, you should write it down — but make sure it’s written on something that can be reliably destroyed and won’t be discovered before it’s destroyed. A piece of paper that you can mangle or burn will do the trick. Make sure to keep it safe until you’re ready to destroy it.

Totally optional: If you’re feeling ambitious, this is the time to augment it a bit by adding a few random symbols and numbers. Avoid common letter substitutions like l33t speak because every password cracking tool automatically tries these out of the box. Pick a couple of random numbers and symbols and litter them in the middle of some of your words.

It’s okay to add randomness to your already-random password, but avoid removing randomness by replacing your random words with ones that you chose on a whim or by simplifying the phrase in general.

If you’re not sure what to do, then just keep the passphrase as it came out from xkcdpass. It’s fine as it is and you don’t want to make it too hard to remember.

3. Memorize and practice

Make a text file with a short message and encrypt it using your new password. I like to use scrypt which is available in popular package managers:

$ brew install scrypt  # or apt-get install scrypt
$ echo "I remembered my password" > pwtest.txt
$ scrypt enc pwtest.txt > pwtest.enc
Please enter passphrase:
...
$ rm pwtest.txt  # Don't need this anymore

Now that we have our encrypted test file, we can practice unlocking it until we memorize the password:

$ scrypt dec pwtest.enc
Please enter passphrase:
...
I remembered my password
$ scrypt dec pwtest.enc
Please enter passphrase:
...
I remembered my password
$ scrypt dec pwtest.enc
Please enter passphrase:
...
I remembered my password

If you prefer to use GPG instead of scrypt:

$ echo "I remembered my password" > pwtest.txt
$ gpg -c pwtest.txt
Enter passphrase:
...
$ gpg pwtest.txt.gpg
Enter passphrase:
...
I remembered my password

4. Adopt the new master password

After a few days of practicing your new password, it’s time to adopt it: Destroy the paper you wrote it onto, change your password manager’s master password, and remember: Never use your master password anywhere else.

The master password is there to keep your other passwords safe. It should never be used as a password for another account, even if it’s your bank or iCloud or whatever. The master password is for your password manager, and you must use your password manager to generate and save passwords for the rest of your accounts.

If you’re not using a password manager yet, I recommend Bitwarden. It’s free, open source, has a great paid plan for families and teams, and works on all platforms.

If you insist on something closed source and more expensive but with 5% more polish, 1Password is also a good option.

Good security hygiene

• Use a strong randomly-generated passphrase as your master password.

  Done, good work.

• Use a password manager.

  Hopefully already done?

• Enable encryption for all of your devices and services.

  Especially portable devices that you can lose, like phones and laptops.

• Choose to use applications that come with good security defaults out of the box.

  Not all security or encryption is made equal: an application with bad security is like an account with a bad password. Sometimes bad security can be worse than no security if it manages to lull you into false expectations.

You won’t regret good security hygiene, especially as the cyber continues to intensify.

Go does not have classes and objects, but it does have types that we can make many instances of. Further, we can attach methods to these types and they kind-of start looking like the classes we’re used to. When we attach a method to a type, the receiver is the instance of the type for which it was called.

Choosing the name of a receiver is not always a trivial task. Should we be lazy and name them all the same (like this or self)? Or treat them not unlike local variables by abbreviating the type (like srv to a Server type )? Or maybe something even more nuanced?

And what are the consequences? How will our code suffer if we choose one approach over the other? Let’s explore.

Quick refresher on Go structs

type Server struct {
    ...
}

func (srv *Server) Close() error {
    ...
}

func (srv Server) Name() string {
    ...
}

Every time I start writing somekind of server, it starts out looking like this. It’s a type that holds information about our server, like a net.Listener socket, and it has a Close() method that shuts down the server. Easy enough.

The receiver of the Close() method is the (srv *Server) part. This says that inside of the Close() method declaration, the scope will have a srv variable that is a reference to the instance of the Server that it’s being called on. That is:

myServer := &Server{}
myServer.Close()

In this case, the srv that is referenced inside of the myServer.Close() is effectively the same variable as myServer. They’re both references to the same Server instance.

Facts about Go methods and receivers

While we can call a method on a type instance and get the receiver implicitly, it can also be called explicitly:

myServer := &Server{}
Server.Name(myServer) // same as myServer.Name()
(*Server).Close(&myServer) // same as myServer.Close()

These functions can be passed around as references just like any other function, with the implicit receiver or without:

withReceiver := myServer.Name
without := Server.Name

Receivers can be passed by reference or passed by value.

func (byValue Server) Hello() { ... }
func (byReference *Server) Bye() { ... }

This is to illustrate that struct methods in Go are merely thin sugar over traditional C-style struct helper declarations. An equivalent C method might look like this:

void server_close(server *srv) { ... }

Go helps by namespacing the methods and implicitly passing the receiver when called on an instance, but otherwise there is very little magic going on.

In other languages where this and self is a thing (Python, Ruby, JavaScript, and so on) it’s a much more complicated situation. These are not vanilla local variables wearing fancy pants. The thing we might expect this to represent inside of a method could actually represent something very different once inheritance or metaclasses had their way. In effect, it might not make any sense to give contextual names like srv rather than self in Python, but it definitely makes sense in Go.

Naming the receiver

As we write idiomatic Go code, it’s common to use the first letter or a short abbreviation as the name of the receiver. If the name of the struct is Server, we’ll usually see s or srv or even server. All of these are fine—short is convenient, but it’s more about uniquely identifying the variable in a consistent way.

Why not self or this? Coming from languages like Python, or Ruby, or JavaScript, it’s tempting to do something like:

func (this *Server) Close() error {
    ...
}

That’s one less decision to make every time we declare a struct. All of our methods could use the same receiver. Any time we see this in the code, we’ll know that we’re talking about the receiver, not some random local variable. It will be GREAT!.. or will it?

What if we refactor the code and this is no longer referring to the same thing as before? And are we giving up valuable semantic meaning?

Reshaping our code

Eventually we’ll need to refactor some of our code: Take a chunk of code that is already functional and put it in another context where it allows for more flexibility towards a higher-level goal.

For example, consider moving pieces of code between levels abstractions or from higher levels of abstraction into a lower level. Imagine taking this snippet from a higher-level container like Room which holds groups of users in a server, and moving it up or down one level:

func (this *Room) Announce() {
    srv := this.Server()
    for _, c := range srv.Clients() {
        // Send announcement to all clients about a new room
        c.Send(srv.RenderAnnouncement(this))
    }
}

// Moved between...

func (this *Server) AddRoom(room *Room) {
    for _, c := range this.Clients() {
        // Send announcement to all clients about a new room
        c.Send(this.RenderAnnouncement(room))
    }
}

When using this, there is confusion about whether we’re referring to the server or the room as we’re moving the code between.

-       c.Send(this.RenderAnnouncement(room))
+       c.Send(srv.RenderAnnouncement(this))

Refactoring this kind of code produce some bugs that the compiler will hopefully catch (or maybe not, if the interfaces happen to be compatible). Even bugs aside, having to edit all the little innards does make moving code around more tedious.

Moving across levels of abstraction is a great example of when consistently well-named receivers make a huge difference:

func (room *Room) Announce() {
    srv := room.Server()
    for _, c := range srv.Clients() {
        // Send announcement to all clients about a new room
        c.Send(srv.RenderAnnouncement(room))
    }
}

// Moved between...

func (srv *Server) AddRoom(room *Room) {
    for _, c := range srv.Clients() {
        // Send announcement to all clients about a new room
        c.Send(srv.RenderAnnouncement(room))
    }
}

This is a great little pattern to keep everything working despite moving between layers of abstraction. Note how the inner code stays identical and all we’re doing is sometimes adding a little extra context outside of it.

As projects mature, this kind of refactoring happens surprisingly often. We’re talking about just one line in this example, but the same applies for larger chunks too.

The suggested strategy for naming Go receivers is the same strategy for naming normal local variables. If they’re named similarly, then these code blocks can be moved wholesale between layers of abstraction with minimal hassle and helps us avoid careless bugs.

By naming receivers as this or self, we’re actually making receivers special in a way that is counter-productive. Imagine naming every local variable with the same name, all the time, regardless of what it represents? A scary thought.

Advanced naming technique

If we agree that contextually named receivers are meaningful, then maybe we can utilize this opportunity for an even greater advantage.

What if we named our receivers based on the interface that they’re implementing (if any)? Let’s say we add io.Writer and io.Reader interfaces to our Server:

func (w *Server) Write(p []byte) (n int, err error) {
    // Send p to all clients
}

func (r *Server) Read(p []byte) (n int, err error) {
    // Receive data from all clients
}

Maybe we also want to add the http.Handler interface to provide a dashboard for our server.

func (handler *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    // Render dashboard
}

There are a few benefits to doing it this way:

• The receivers enhance the self-documenting nature of our code. It becomes clearer which interface each method is attempting to implement.

• If we were implementing these wrappers outside of the Server struct, we would likely be using similarly named variabls for intermediate code. By naming the receiver in a corresponding way, it makes it easier to move the code inline without changing much.

• As we add interface-specific functionality, it’s likely that we’ll need to add more fields to our struct to manage various related state. The code can look more meaningful when a read buffer is being accessed from a r receiver to imply that its purpose is specifically for this functionality rather than it being a more general buffer for the server as a whole.

Name of the Receiver

Carefully naming our receivers can have lots of tangible benefits, especially as our project grows and code gets moved around. It can make our inner method code much more readable without needing to be aware of which struct it’s embedded into. It can even add an opportunity to indicate higher-level layout of our struct’s interface implementation.

Picking a fixed name for all receivers like self can have negative effects like mixing up context when code gets moved around. It removes a decision during writing, but the cost creeps up when we go back to read the code or refactor it.

Go forth and give your receivers the names they deserve.

I present three stories that use VR technology to push our crafts beyond what was possible. Each story is focused around an amazing short video that is very much worth watching.

“This is not why I became an actor.”

On the set of The Hobbit, Sir Ian McKellen broke down in tears after hours of delivering his lines as Gandalf to a handful of photographs floating amidst a sea of green.

In an interview with Contact Music, he recalled:

In order to shoot the dwarves and a large Gandalf, we couldn’t be in the same set. All I had for company was 13 photographs of the dwarves on top of stands with little lights — whoever’s talking flashes up.> Pretending you’re with 13 other people when you’re on your own, it stretches your technical ability to the absolute limits.> I cried, actually. I cried. Then I said out loud, ‘This is not why I became an actor’. Unfortunately the microphone was on and the whole studio heard.

Today, we’re entering a different world. One where actors can be immersed in the virtual world they’re depicting as they’re depicting it.

Cloudhead Games is working with actor Adrian Hough to record the motion captured acting end-to-end for the first episode of The Gallery, right inside the world itself as it’s being acted out:

As Valve’s Lighthouse Tracking system becomes available later this year, trackable peripherals and body attachments will bring a world of consumer motion capture. Someday, it might even be the default for most VR experiences. You’ll raise your hand, wiggle your fingers, and take that precious swing to feel haptics sharply vibrate in your palm as you slap your friend across the continent. The future is here.

“What is this amazing new world?”

Glen Keane is an animator who worked at Disney for 38 years, he helped create many of the characters we all take for granted from our childhood.

In collaboration with the Future of StoryTelling Summit, Keane put on an HTC Vive headset and picked up the wireless controllers. He entered a new world:

When I draw in virtual reality, I draw all the characters in real life size. They are that size in my imagination.

This world is called Tilt Brush, a VR painting application created by Google.

For years we’ve been fed images of architects and surgeons using virtual or augmented reality to feel what it’s like to be inside their building or patient. But what about us? What about our inner child unleashed inside a life-sized world of our own design, not just staring at it from the distant abstraction of a flat display.

“Your crappy PC is the biggest barrier to [VR] adoption.”

Palmer Luckey, founder of now-Facebook’s Oculus RV, hosted a marathon of an IAMA on /r/pcmasterrace last week. One recurring topic was the recommended hardware requirements for running the Oculus Rift, specifically the “NVIDIA GTX 970 / AMD 290 equivalent or greater” — a $350 investment just for the video card, or more if you’re shooting for above the bare minimum.

In modern gaming, 1080p resolution is considered passable. At 1920x1080, these 2,073,600 pixels are what you’d expect on a PS4 or XBox 360 rendered about 30 times each second. On a PC, it’s common to see higher resolutions pushing 60fps. What happens if some big explosions break out and the frame-rate drops to 45? Not much. If it drops below 20fps, you might notice and grumble a bit until things calm down again.

The first iteration of VR is going to be a more expensive beast: Two camera positions need to be rendered for every frame—one for each eye—90 times per second. Not to mention that the display panels are higher resolution, probably around 1512x1680 per eye or 5,080,320 pixels total. And what happens if you swing your head and the frame-rate drops to 40 fps for a few moments? Nausea. You’re done.

Today, we’re talking about 62 million pixels/sec rendered on latest-generation consoles compared to at least 378 million pixels/sec rendered for nausea-free VR.

Sounds gloomy, but don’t fret—the forecast is sunny: If we can track where our eyes are looking at inside of the headset, we can reduce the full-quality rendering to less than a quarter of the resolution. This is called Foveated Rendering, and a German startup already has a working prototype:

What does this mean?

Once Foveated Rendering reaches consumers, we might actually see higher graphics quality and lower hardware requirements from VR than traditional flat-display technology.

I can’t wait.

Let’s keep it simple and direct.

{
    "status": "ok",
    "code": 200,
    "messages": [],
    "result": {
        "user": {
            "id": 123,
            "name": "shazow"
        }
    }
}

result

The hard-coded name of “result” could be anything—like payload or response or whatever sounds sensible—but the keys inside are important. Each key helps us double-check our expectations of what is inside:

data["result"]["user"] == (a user object)
data["result"]["users"] == (a list of user objects)
data["result"]["post"] == (a post object)

This distinction is a valuable tool for the consumer. If I’m skimming the docs and expecting some API endpoint to return a user object but instead it returns a member object which is similar but subtly different, then trying to access the user key will reveal the problem immediately.

Imagine an alternate scenario, where we return each type inlined in the result:

data["result"] == (a user object)
data["result"] == (a list of user objects)
data["result"] == (a post object)

My code might seem like it’s working but it might seem like it by accident. I might treat a post id as a user id and get all kinds of weird results without realizing why. Maybe the inline result includes a handy “type” field, but who knows if I’ll bother checking against it every single time.

Bonus feature: Having the result objects keyed by their types allows you to return multiple things in a single result. Maybe it’s most efficient for the consumer to return a post and a user in the same response? It’s nice to keep our options open.

status

As a consumer, when I get a response from this API, first thing I do is check the status value. Is it “ok”? Great, carry on as expected. Is it an “error”? I’ll need to handle it.

This key only has two possible values, so it’s nice and simple for the consumer’s code.

code

When I get an error, this is where I’ll go to differentiate it and maybe handle it programmatically. We can use HTTP-like codes, or just incremental codes, or whatever makes us happy as long as it’s well-documented. Errors should be obvious and/or well-documented with what each endpoint could return and how we should handle it.

Why not just use HTTP response codes instead of embedding a code value in our JSON? Three reasons:

1. Consumers don’t like checking response codes, it’s a lazy thing. All of my code is already dealing with JSON values so why not one more. Also some HTTP libraries make it somewhat difficult to get at the value.
2. HTTP response codes are unreliable. Some poorly-implemented proxy code could override the code, or your cache will kick in and serve that one buggy response which might be inconsistent with the values inside.
3. No reason to tightly couple with your transport protocol. By all means, mirror your codes in HTTP but if you include it in the encoded response then you can just as easily switch the API to straight-up TCP or even something crazy like an SSH RPC API!

We could skip the status field by saying “code 200 is a success” or similar, but I like the binary nature of status. The API is less intimidating if I don’t need to learn about what which codes mean until I’m diving into actually handling specific errors.

messages

This one is purely for debugging or informational purposes. If there’s an error, then we’ll get some messages here telling us what went wrong—along the lines of “user id does not exist: 4”

We could add some user-friendly success messages in there, too—like “post created: My JSON API response.” I’ll often use the same API for my frontend client-side handlers as I do for backend stuff, so I can flash these messages as they appear.

Some APIs call this field errors, but I like that it can be used for non-errors.

Extra stuff?

• It can be fun to include a stats object with performance information.
• A pretty request parameter should indent our JSON and sort the keys, very handy for being human-readable and for comparing test output in a deterministic way.
• Pagination can be done with something like data[“result”][“offset”] and the offset value passed back in with the next query. This can be an arbitrary token or a page number. Not all responses make sense to paginate, so I prefer to include it as part of the result when it makes sense rather than making it a root-level value that is often ignored.

Patterns Avoided

There are lots of complicated standards that have evolved, like jsonapi.org and HATEOAS (remember SOAP?). Some of those ideas can be safely avoided, especially if we’re not building ENTERPRISE SOFTWARE (TM).

api links

    ...
    "user": {
        "id": "1",
        "name": "shazow",
        "links": {
            "self": "https://example.com/api/v1/user/1.json",
            "posts": "https://example.com/api/v1/user/1/posts.json"
        }
    }

Some APIs include a pre-generated API request URLs, such as for pagination or querying sub-relationships. This never made any sense to me. To get to this response, my consumer code already needs to know how to compose the URL in the first place. Suddenly I’m supposed to switch from using my URL-building code to using pre-built URLs returned in the response? This leads to all kinds of bugs:

1. More branching in the code, toggling between my own URL-building logic and pre-built URL logic.
2. API response might be normalizing URLs in a way that is different than I intended. Or maybe I’m accessing an API through a proxy like Runscope? “Ugh why is my first request working but the rest fail, WHY??! 😡🐚♨️”

This also breaks if you’re trying to avoid coupling with HTTP as a transport, or if you need to multipart-encode a large request and url-encoded variables don’t get merged.

On the other hand, including URLs for downloading or frontends to navigate to is fine: Images, browser links, whatever. We’re talking strictly about API endpoints here.

generic data lists with types

{
    "data": [
        {
            "id": "1",
            "name": "shazow",
            "type": "user"
        }
    ]
}

It’s not any more expressive than our result layout above, and we’d be requiring our consumer to check the type field for every object they touch to make sure they’re not mistreating it. They won’t. Bugs will ensue.

Other cans of worms

I have feelings on other API-related topics like REST vs RPC, language-native SDK wrappers, versioning, transport protocols, XSS security strategies, and more.

Let me know what interests you at twitter.com/shazow.

SSH, how does it even?

A few weeks ago, I wrote ssh-chat.

ssh http://t.co/E7Ilc0B0BC pic.twitter.com/CqYBR1WYO4

— Andrey 🦃 Petrov (@shazow) December 13, 2014

The idea is simple: You open your terminal and type,

$ ssh chat.shazow.net

Unlike many others, you might stop yourself before typing “ls” and notice — that’s no shell, it’s a chat room!

While the little details sink in, it dawns on you that there is something extra-special going on in here.

SSH knows your username

When you ssh into a server, your client shares several environment variables as inputs to the server, among them is the $USER variable. You can overwrite this, of course, by specifying the user you’re connecting as such:

$ ssh neo@chat.shazow.net

Well look at that, you’re the one. So special. What else can we mess with? By default, the server gets your $TERM variable too.

$ TERM=inator ssh chat.shazow.net

If ssh-chat was smart, it would recognize that your custom terminal might not support colours and skip sending those extra formatting characters.

You can even push your own environment variables with a SendEnv option flag, but we won’t get into that.

SSH validates against your key pair

There are several supported authentication methods in SSH: none, password, keyboard-interactive, and publickey. They each have interesting properties, but the last one is especially handy.

When your SSH client connects to a server, it negotiates an acceptable authentication method that both support (typically the reverse order of the above). If you’ve specified the identity flag or have some keys lying around in your ~/.ssh/ directory, your client will offer up some public keys to authenticate against. If the server recognizes one of those keys, such as if they’re listed in authorized_keys, then a secure handshake will begin verifying that you hold the private key to that public key but without revealing what the private key is. In the process, the client and server securely agree on a temporary symmetric session key to encrypt the communication with.

What does this mean? It means that SSH has authentication built into the protocol. When you join ssh-chat, not only do I know who you claim to be, but I can also permanently and securely attach an identity to your connection without any user intervention on your part. No signup forms, no clicking on links in your email, no fancy mobile apps.

A future version of ssh-chat will allow you to create a permanent account which is validated against your key pair, and these permanent accounts might have all kinds of special features like username ownership, always-online presence, and push notifications over Pushover or email.

SSH connections are encrypted

The server uses the same kind of key pair as a client would. When you connect to a new SSH host, you get a message that presents a “key fingerprint” for you to validate. The fingerprint is the hex of a hash of the server’s public key.

What does it mean if you try to connect to chat.shazow.net and you see a different fingerprint hash? You’re being man-in-the-middle’d.

Your local neighbourhood clandestine security agency could make an SSH server that just acts as a proxy in front of another SSH server you frequent (using something like sshmitm) and log everything that is going on while passing it through. Fortunately, as long as the proxy doesn’t have the original server’s private key, then the key fingerprint will be different.

Once you accept a fingerprint, it will be added to your ~/.ssh/known_hosts where it will be pinned to that host. This means if the key for the host ever changes, you’ll be greeted with this appropriately-scary message:

A host you’ve connected to previously is advertising a different public key than it did before. If you can’t account for this change (maybe you launched a new VPS on the same IP address as before and it generated a fresh SSH key pair?) then it’s worth being worried. Try connecting to this host from another network, see if the problem persists — if not, then someone is hijacking your local connection rather than the server’s connection.

SSH supports multiplexing

When your client connects to a server, it opens a channel where it requests a specific feature. There are many fun things your client can request like pty-req (a pseudo-terminal), exec (run command), or even tcpip-forward (port forwarding). There are many others, and there is nothing stopping you from inventing your own type for a custom client/server implementation. Maybe we’ll see a chat channel someday?

The best part is that you can do all of these things concurrently: Start port forwarding while opening a shell while having some command run in the background.

Once your pipeline is opened, you can send more commands within it. When your client opens a pty-req, it sends event updates such as window-change whenever your terminal size changes.

SSH is ubiquitous

“Is it mobile-friendly?” you may joke, but it is! Every platform you can imagine, there is an SSH client available, including iOS, Android, even Windows! OSX and every Linux distro ships with a client. There are even browser extension SSH clients.

SSH is one of the most accessible secure protocols ever, second only to HTTPS of course.

SSH sounds awesome, and familiar…

Let’s see what we have so far: Binary protocol, mandatory encryption, key pinning, multiplexing, compression (yes, it does that too).

Aren’t these the key features for why we invented HTTP/2?

Admittedly, SSH is missing some pieces. It’s lacking a notion of virtual hosts, or being able to serve different endpoints on different hostnames from a single IP address.

On the other hand, SSH does have several cool features over HTTP/2 though, like built-in client authentication which removes the need for registration and remembering extra passwords.

More factlets to fill your stockings

• SSH server and client specification is fairly symmetric. Per the protocol, most of what the client can ask of a server, a server could ask of the client. This includes things like run commands, but mainstream clients don’t implement this (as is recommended against in the specification).
• Every keystroke is sent over the TCP connection. This is why you might notice lag in your typing.
• To see what your OpenSSH client is doing, use -v to enable verbose debugging output. Use another -v to see per-keystroke debugging, and another -v to further increase the silliness.
• There is a protocol called MOSH which uses SSH to bootstrap but uses client-side predictive rendering and a UDP state synchronization protocol to remove the effects of latency. I wish there were more third-party implementations of it.
• Since SSH supports port forwarding and a SOCKS proxy interface, you can build a VPN on top of it by using something like sshuttle.
• SSH can authenticate using a certificate authority scheme, similar to x.509 certificates used in TLS. Also, many clients can verify server fingerprints against an SSHFP DNS entry.

Some provocative SSH ideas

Chat over SSH was fun, but that’s just the tip of what we can come up with.

Multi User Dungeon (MUD)

Someday, you’ll be able to ssh into mud.shazow.net and you’ll get a little ASCII RPG world to explore. Not yet, but it just might happen.

Distributed Hash Table (DHT)

This gets technical but the possibilities are striking…

Imagine S/Kademlia DHT implemented atop SSH: pic.twitter.com/poY2Ibu30W

— Andrey 🦃 Petrov (@shazow) December 28, 2014

Programmatic Data Streams

Or better yet, ZeroMQ-style sockets with proper security and encryption? Check out Jeff Lindsay’s Duplex. Still a proof of concept, but lots of really cool demos.

RPC API

SSH’s built-in authentication and encryption makes it really convenient for things like APIs. No complicated OAuth2 handshakes or HMACs and signatures.

ssh api.example.com multiply a=4 b=5

Someday we’ll have good libraries which make connecting over SSH just as easy as HTTP. At that point, your code will look exactly like today’s run-of-the-mill REST API, but use SSH underneath.

Either way, the days of curl examples in API docs would be behind us.

File Server

If we have an RPC API, why not serve static files while we’re at it?

ssh static.example.com get /images/header.png

Remember, SSH supports persistent connections just as well, so your browser could sit there connected to an SSH channel named get for the host and send concurrent get requests for assets. We could even implement ETAGs, and whatever else.

And finally, HTTP

At this point, there’s no reason we couldn’t build a version of HTTP/1 or HTTP/2 on top of SSH. Let’s add a header channel to specify things like Host for virtual host support, throw in some Cookie headers too. Want to add some method verbs? Why not, let’s make a bunch of channels like post or maybe http-post if we want to be polite.

Why aren’t we using SSH for everything?

Great question.

Six years ago, I built a better Python http library. It had then-novel things like connection pooling, thread-safety, multipart encoding, and more. Today, every Python user depends on it.

Maintaining something for six years on my own time is not easy, even with a slew of coping strategies. A few hours here and there, every week, and slowly it chugs along—largely thanks to contributors undertaking the bigger tasks that I can’t knock off in a quick afternoon.

Last week completes my two week grant from Stripe to work on urllib3 full time, and I’d like to declare that these weeks were a huge success.

tl;dr:

• $3,750 for two weeks of full time work at Stripe.
• 51 files changed, 1809 insertions(+), 633 deletions(-).
• 10 merged pull requests, 26 closed issues, 6 new issues.
• One major release (v1.9).
• ~6 months worth of progress in two weeks.
• Tech companies: More like this, please.

Stripe Open-Source Retreat

In April, Stripe announced the intent to sponsor a few open source projects for 3 months of full-time work at the office.

I drafted an email proposing a 2 week arrangement for urllib3 instead. I wanted a shorter term because I didn’t want to fully relocate my life to The City, and I felt that urllib3's backlog would get the most impact out of a few weeks worth of work without hitting diminishing returns.

Greg Brockman responded enthusiastically and worked out the ideal structure for me. Fast forward a couple of months, and the grant was official. We cut the $7,500/mo in half and settled on $3,750 for 2 weeks.

The rest of the experience was a dream. I arrived at Stripe and was basically treated like a new employee. Kat Li happily toured me around the office, introduced me to everyone, and made sure I had people to grab lunch with the first few days. “Python bindings? Talk with Andrew! Into Bitcoins? Check in with Christian!” Really great welcome experience.

Everyone treated me as a fellow Stripe. With new hires starting each week, I may as well have been.

Progress on urllib3

First few days were all about catching up on low-hanging fruit. Pull requests that have been thoroughly reviewed, easy little bugs or feature requests. I was closing numerous issues per day, and it felt great. Having a full day allocated to just this was empowering, without the distraction of attention-starved pets at home or coffeeshop patrons eyeing my prime seat next to the outlet.

Next up I took on a big feature that has been in the works for more than 8 months by the ever-patient Kevin Burke: Granular retry configuration. Not only did we have to design a sensible interface that we wouldn’t regret maintaining for the next 6 years, but also draw a line among many ambiguous questions like “is it safe to retry a request that has only been partially sent to the server?” For a few days, I learned what Kevin must have felt for months—hitting walls at every step, “why are half the tests suddenly failing? How do we persist this across hosts? There is no way to tell how much of the request we sent so far?”

Ultimately some compromises had to be made, but the feature got merged and the truck kept trucking.

All in all, 10 meaty pull requests were merged and 26 issues closed.

The big win from working full time is that it allowed me to tackle medium-large issues that otherwise I’d have to delegate to contributors. It can be weeks or months between a code review and when the contributor has a chance to iterate on the pull request. Having a contiguous work chunks allowed me to plow through what previously felt like more than six months worth of stuff.

urllib3 commits since moving to Github

More like this

Publishing and contributing to open source is going to continue happening regardless whether I’m getting paid for it or not, but it will be slow and unfocused. Which is fine, it’s how open source work has always worked. But it doesn’t need to be this way.

Sure, there are things like Gittip but the gap between an amount that would “move the needle” for me and the $1 I’m tipped per week is just too big to grapple, and I’d rather focus in short concentrated bursts than a long meandering slog.

If you’re a tech company, please allocate a budget for open source grants and sponsorships. Distribute it on Gittip if you wish, or do what Stripe did and fund aggressive sprints towards some high-impact milestones.

Consider this a formal call for sponsorship: Please help fund urllib3 development.

If your company uses Python and benefits from urllib3 (which powers Requests, pip, and numerous other tools and libraries) and you’d like to help push the state of HTTP in Python forward, I urge you to sponsor urllib3.

Lots of high-value open issues that could be knocked out with a few more weeks of full-time work, like adding SOCKS proxy support.

If you’re looking for other projects to give a grant to, I would be happy to recommend some other great initiatives.

Thanks again

A huge cloud-scale heartfelt thanks to urllib3's many contributors and to Stripe for helping the future come a little sooner.

Hello, John Carmack.

(1/3) Everyone has had some time to digest the FB deal now. I think it is going to be positive, but clearly many disagree.

— John Carmack (@ID_AA_Carmack) March 28, 2014

(2/3) Much of the ranting has been emotional or tribal, but I am interested in reading coherent viewpoints about objective outcomes.

— John Carmack (@ID_AA_Carmack) March 28, 2014

(3/3) What are the hazards? What should be done to guard against them? What are the tests for failure? Blog and I'll read.

— John Carmack (@ID_AA_Carmack) March 28, 2014

Thank you for being open to public discourse.

I am a passionate believer in the importance and imminence of virtual reality’s effects on our society. I was devastated when I read the news about Facebook acquiring OculusVR, and this is why:

Ecosystem

The Oculus Rift was more than a timely piece of clever technology—it was a powerful rallying cry to which hundreds of developers and manufacturers answered the call.

Within two years since Oculus Rift’s Kickstarter, the roots of a new industry took hold. Dozens of VR-related peripherals were put in the market, from haptic gloves to static treadmills to body scanners. Hundreds of demos and “VR Experiences” were published and consumed, pioneering a novel medium of entertainment and immersion. The Oculus Rift was one of the best examples of a successful “grassroots movement” that so many others try to replicate.

With a single announcement, much of this was undone. Numerous game developers abandoned their Oculus projects, the community roared in anger and disappointment. The trust has been broken.

The ecosystem has been broken.

We all acknowledge that Oculus VR was a private company and had the right to do what its leaders feel is necessary, but it’s clear that the expectations of the community were betrayed. The Oculus leadership was even quoted saying that they expected the core community to react negatively, so this was a calculated sacrifice.

I worry that this sacrifice was too big and will set our society back until the community recovers. It’s true that, with Facebook’s funds, Oculus VR could launch the consumer devices earlier, cheaper, and with better parts, but I worry it will land in a much less vibrant and healthy ecosystem than it otherwise could have.

Acquisitions

Even with the best intentions from both sides, acquisitions never end quite the way the participants hope they will.

Consider this a concern from my personal experiences, as limited and biased as they may be. I’ve heard of many concrete stories from my entrepreneurial friends of how promises get corrupted with time and bureaucracy. I can’t say I honestly believed it until it happened to me. Sure, none of these anecdotes were massive two billion dollar deals, but various degrees of autonomy and independence were definitely at play.

Mark Zuckerberg may feel like he is making a benevolent investment in society by advancing the roadmap of the Oculus Rift today, but things change. What if Facebook’s stock plummets next year as advertising intent continues to elude the social network? What if a competing VR firm shows success in monetizing the product in less-than-user-friendly ways? What if the SVP who is allocated to oversee your division disagrees with your vision and the slow-yet-steady political pressure erodes your founding team’s ideals? What if Instagram gets merged into Facebook Photos, WhatsApp gets merged into Facebook Messages, and you’re next on the cutting block?

Moving forward

What are the hazards? What should be done to guard against them? What are the tests for failure?

I don’t know.

While I trust the intentions of the founding team, I feel that too much of the future is in the hands of the Facebook brand and leadership.

If trust is lost, how will you regain it?

If autonomy slowly slips through your fingers, how will you notice?

If you’ve failed to uphold your vision, what will you do?I admit it—I initially overreacted to the acquisition news. Many of us did.

I hope my immediate reaction was completely wrong. I want to believe.

What do I really want? I’ve been thinking about this for many years.

Do I want to build a venture capital funded startup? A sustainable humble life-style business? An innovative independent game studio? A wildly-profitable consulting enterprise? Perhaps follow in the foot-steps of 37Signals, Github, Twitter, or Google?

Or maybe I would be happy working for somebody else but I just haven’t found the right place?

There are no wrong answers here.

My fantasy is to build a company which has a very high profit-to-employee ratio sourcing from a large diversity of projects. Employees are very well compensated and operate autonomously with the benefit of the company’s retained resources.

The closest present manifestation of my fantasy is Valve Software due to their very liberal project-assignment policy. Just unlock the wheels on your mobile desk and move to whatever project you’re interested in working with or recruit your own team. Some projects like Half-Life 3 will linger unreleased for years to come, but this nimble freedom is the special sauce that makes every great product from Valve what it is—no matter how long it takes.

My fantasy is Valve, but smaller. A few dozen people, instead of a few hundred. I like to imagine us all being equal partners, remotely distributed, meeting sporadically to collaborate on larger projects, building and disbanding teams as needed.

It has taken me a long time to realize that this is the fantasy which appeals to me most, but even still I cannot quite articulate why.

I have a strong belief in the power of tiny teams with disjoint projects who work towards a common vision of the future. I believe the top percentile of performers in the tech industry are vastly under-compensated and mis-utilized while they grind away on implementing mocks handed down from a designer directed by a product manager approved by a director and budgeted by a vice president. I believe that people perform best when they’re working on the thing they’re passionate about at that moment, and that people can change.

My fantasy is to create a world where I can work with people who share these beliefs.

Now I feel like I have a goal I’m working towards.

Exploring our fantasy career and life is important because it allows us to introspect into what parts really matter and guide life towards some version of it. I believe this to be true even outside of the privileged bubble of tech.

What is your fantasy?

Lessons learned from five years of maintaining one of the most-used Python libraries.

I’ve published dozens of open source projects over the years, mostly in Python and JavaScript. Few are old and stable, others are new and immature, some are wildly popular with a constant stream of contributors, but most linger until one day a trickle of users suddenly discover them. This is a guide on how to traverse these waters and foster your project into something you can be proud of.

Instructions

Every open source project needs three things: A summary of the project’s goal and approach, contribution instructions, and a license. Preferably up-front in a README file.

I like to include a section I call Organization & Philosophy. This outlines how the project is structured, where everything lives, how the code is written, the kinds of tests required, and what level of performance vs simplicity to aim for. (See unstdlib.py for an example.)

Then, include a Contributing section which outlines how to get started with the project as a developer, and all the steps necessary to get code successfully merged into the project. Here is an example from urllib3, which has been adopted by several other projects too:

1. Check for open issues or open a fresh issue to start a discussion around a feature idea or a bug. There is a Contributor Friendly tag for issues that should be ideal for people who are not very familiar with the codebase yet.
2. Fork the urllib3 repository on Github to start making your changes.
3. Write a test which shows that the bug was fixed or that the feature works as expected.
4. Send a pull request and bug the maintainer until it gets merged and published. :) Make sure to add yourself to CONTRIBUTORS.txt.

Finally, every open source project needs to have a License. If there is no license, then that means it’s copyrighted by the author and other people need explicit permission to use it. I default to using MIT, but you can read Jeff Atwood’s Pick a License, Any License post for a decent summary.

Attitude

It’s incredibly important to have a good attitude towards your users and contributors.

Occasionally a user of your library will stumble into your issue tracker and demand something that is obviously silly or addressed in the documentation. What do you do?

1. You can berate the user for rudely wasting your time.
2. You can patiently explain what the user is misunderstanding, and once they understand the problem better, invite them to send a pull request to improve the documentation for other users in their position.

For some reason, many projects choose #1. Perhaps it’s because some of them are sick of their often-thankless job as a maintainer and could afford to lose some contributors. But let’s examine the effects.

When you berate a user, you will almost definitely lose that user, which means you also lose the possibility of that user becoming a contributor, which also means this effect could cascade to other users who witnessed the exchange, told their peers, or stumbled onto the issue years later by Googling their confusion which your documentation still fails to address adequately. Or worse off, you could be wrong (it does happen) and come out of it with egg dripping down your face.

When you’re patient, polite with a user, and encourage them to contribute to the project, they can become more invested. This also cascades to the audience. Every once in a while, you’ll facilitate a really great relationship with someone who makes a significant impact on the project and makes your life easier.

Maintaining the right attitude is possibly the hardest part of it—every maintainer has bad days—but civility, positivity, and progress is crucial. Not only to you and your project, but also to the community as a whole.

Marketing

You can write the most useful beautiful code in the world and be done with it, but your contribution to society can be disproportionally amplified by allowing people to reuse it and making people aware of it.

PyPI query for “http connection pooling”

Finding your project. Think of it like SEO. Pick a relevant name for it which ideally includes an important keyword. Requests is a great name for an HTTP library, and urllib3 is less so—people often confuse it with being a standard library, but it still fares decently well when people search for things related to urllib and urllib2, which they do often due to the disappointing state of those standard libraries.

Your project description and first paragraph of your README should be a simple summary of your project which hits all the important keywords that people search for.

urllib3 — Python HTTP library with thread-safe connection pooling, file post support, sanity friendly, and more.

Python, HTTP library, thread-safe, connection pooling, file post. This is exactly what people search for when they run into a wall using Python’s standard HTTP libraries (urllib, urllib2, httplib). You can go into greater detail in a subsequent Highlights paragraph.

Once you’ve polished up your README, make sure to generate some documentation. Publishing it on Read the Docs is a great option. Include some code examples and recipes for easier adoption.

Finally, maintain a thorough CHANGES log and merge that into your long description. Every time a feature gets added or an important bug gets fixed, add it to your log and people will stumble on it. Also a great place to link to when announcing a release.

Provide technical support for your audience. Set up some StackOverflow alert filters, and maybe even Google Alerts for the odd random forum post. If you’re pushing your own software, it helps to add a disclaimer that you’re the author.

Consider partnerships. Most code you write will not be completely standalone. Write a plugin for a framework that could use your tool and see if they’ll link to it in their README. Couple of years ago, after chatting with Kenneth Reitz on several occasions, we decided to join forces and have urllib3 become the core of the very popular Requests library. At this point, urllib3 was already decently well-known, but far behind the incumbent httplib2. When Kenneth and I joined forces, both of our projects flourished beyond our expectations. It was important to establish clear roles and boundaries in our partnership, and it helped that our interactions grew into a strong friendship and mutual respect. As a bonus, we have healthy cross-pollination of contributors between the two projects. Everybody won.

Give it time. My more popular projects took at least a year to become known. This is the lazy version of marketing, but if you’ve done everything else in this article correctly, then they will come. Or if you’re impatient, then start hustling, attending meetups, writing blog posts, buying ads, and bribing the quasi-celebrities in your community to rave about you.

Community

It’s very hard to do everything alone, especially as more people come to expect things from you.

Ask for pull requests at every opportunity. Sometimes one rogue pull request could evolve into dozens of collaborations in the future. Also, I try to ask the opinion of other members in the community whenever possible. Often they’ll know more about some RFC I never heard of, or at least have the time and initiative to research the topic further.

Don’t be afraid to ask for help. I try to dedicate a few hours per week on open source work, but sometimes my schedule slips or I forget about a pull request. I encourage people to get involved and ping me when I need to get involved more. In more complicated branches, it helps to ask for a volunteer sub-maintainter to handle the issue until it’s ready to be considered for merging.

Automate as much as you can. I don’t think I could have made it this far without unit tests. Last year, we instituted a 100% test coverage rule for urllib3 which made the project much easier to maintain. Any feature must be tested or else it can be removed without notice. This means every pull request must be completely tested before it is merged.

Continuous Integration on Github with Travis CI

What’s better than unit tests? Automated unit tests! We use Travis CI with Github linking so that every pull request automatically gets all tests run on every platform we support. This removes me from needing to manually pull and run the tests, just to reply with “please fix the tests.” This feature is free for open source projects, and I highly recommend it for any project that receives regular pull requests.

Maintain a list of contributors. Remind and invite contributors to add themselves to the list, even if they just did something small. A few more bytes in the repository doesn’t cost you anything, and the pride they get from being recognized is priceless.

Have fun

Truth be told, it has been years since I’ve done HTTP-related things which needed urllib3. But I continue to maintain it because I like the community and I feel a lot of pride in the project.

When you stop having fun, it may be a good time to hand the project off to somebody else. Find someone who truly depends on the project and cares about it more than you do. Add them as a full-privilege contributor or point to their fork as the official source. Sometimes it works out alright. Other times the new maintainer drops out like you did, and you might need to pick up the slack again.

Possibly most importantly, don’t be afraid. Do your best and take pride in your work. Some people will appreciate it, other people might not. If you try to do the things in this post, then at the very least I will appreciate you for positively and effectively contributing to the Open Source community.

Thank you for sharing your code.

… But worth it.

Bespectacled

My first vision correction was prescribed in the midst of my high school years. I could see well enough to get around but with great effort and strain. By the time I got home from school, I had to take a long nap just to make it through the rest of the day. My eyes were exhausted and glasses fixed all that.

More than a decade later, I was ready to do almost anything to stop obsessively wiping the lenses of my glasses. Every tiny speck or smudge was loudly obtruding my attention, despite my my light-yet-necessary correct. Thin contact lenses were more comfortable but didn’t correct for my astigmatism which left my eyes exhausted. Toric contacts were somewhat closer but the clarity would get disturbed by each blink which shifts the orientation of the lens.

While I grew to appreciate a fashionable frame of glasses, several thousand dollars seemed like a small price to pay to eliminate a constant source of stress in my life.

First day of my new life

December 6, 2012

My agenda for today:

• 9:45am Eyedrops
• 1:25pm Eyedrops
• 4:15pm Eyedrops
• 9:00pm Eyedrops
• 10:00pm Wipe my eyelids before bed

I recruit Tracy to be my ride and provider of moral support. After much research and preparation, it’s not hard to avoid thinking about the details of tomorrow.

December 7, 2012

1:15pm We pull in to Dr. Furlong’s facility in northern San Jose, CA. The friendly staff blaze through all the paperwork I’ve had a week to pre-read, and we begin the signing-athon.

“I understand that there is no guarantee of perfect vision” — check. “I understand that this is an elective surgery and there is no health reason to require this surgery” — check. “I am here for laser eye corrective surgery” — indeed.

I reveal my envelope holding a wad of $4,900 in cash that we agreed on earlier. “Would you like to take a mild sedative that will help you stay relaxed during the surgery and sleep after?” I accept the tiny sweet pill and hold it under my tongue while it slowly dissolves.

The receptionist leads Tracy and me over to the other waiting area, where we continue to wait for more minutes. The “No wifi or cellphones” sign draws attention to the thickened walls, probably leaded just in case. One of the technicians enters to take me in for “prep”.

I’m seated in yet another room as the technician turns on a little boom box dedicated to cheesy pop music. She prepares a eyedrops concoction of anti-biotics, numbing, and lubricants. After cleaning and disinfecting my eyes, we sit back and wait and listen to the cheerful music while the sedative starts to take effect. My thinking begins to fog, decisions become short-sighted, and my breathing is noticeably calmed. I make note of my changing internal state while anticipating the next room.

Finally, it’s time. We walk through the unassuming door into the operating room. Spacious, with numerous utensils and machinery on the periphery, surrounding the centerpiece that is the chair. The chair is hospital-green leather, installed to recline and swivel between two laser machines. One machine makes the flap followed by the other which performs the prescribed correction.

Suddenly imagery of my childhood rushes in. Watching X-Files, alien abductions, brainwashing. When I was a kid, I thought brainwashing was the process of severing your scalp and immersing your brain in a special fluid. I imagined it:

“Anesthetic is applied, followed by pressure on the tip of the head as it’s pulled into place with suction. You don’t feel much but you know the top of the head is being sliced open, scalp peeled back, revealing the brain. It’s floating peacefully in your head’s natural cerebrospinal fluid until brainwashing begins. The anonymous figures in your periphery prod with instruments. Adjusting and correcting the physical matter of your parietal lobe while drowning the organ over with supplemental fluids to keep it lubricated and responsive. Results are verified and the scalp is replaced.”

Creepy. During my experience I was amused at how familiar it all felt to my bizarre science fiction imagery, but instead applied to my eyes.

“Before we get started, another quick eye check and I’m going to place some marks on your eyes to help the tracker,” another technician leads me to another chin rest. As with every other eye instrument, I fit my chin and forehead into the frame and look straight ahead. The numbing eyedrops are well in effect by now so I felt nothing as the man gently poked my eye with some kind of marker, once on either side of the iris.

All ready, off to the chair. I slide onto it and positioned my head to be in range of the pivoting radius. My neck feels cradled and comfortable. More numbing eyedrops wash over my eyes and my left eye is taped shut. I lay here waiting for Dr. Furlong for a few minutes as he wraps up with his previous patient. I hear subtle chatter as I stare towards the ceiling with one eye.

A familiar voice walks through the door and re-introduces himself. Dr. Furlong confirm that I’m here to get laser eye surgery and which kind-as if I would remember the subtle differences between the various generations of laser technology, CustomVue, Visx, WaveFront, something something something—“I guess,” I respond after a pregnant pause. Smiles all around, we proceed. “We’re going to clamp your eyelids open. You have a very strong blink reflex, and while it’s easier said than done, try to give into it the clamp as much as you can or else your eyelids are going to be extra sore tomorrow from fighting it.” This is the first instance of discomfort. Once the clamps are in place, it’s easy to get distracted from them being there with everything else that goes on.

At every step, Dr. Furlong talks through what’s happening, what will happen next, and what to expect. None of the discomfort was a surprise—I appreciate this.

After the clamps comes the suction, but no sooner than another slew of eyedrops. They place a tube-feeling thing around the iris which creates suction until your vision blanks out. This was possibly the most uncomfortable part of the process because the suction creates a lot of pressure on the eye, briefly bordering on pain, but simultaneously distracted by the complete loss of vision. It didn’t feel so much as a fundamental loss of vision but more that my vision was obstructed, like when you close your eyes. With everything in place, I’m swivled under the flap-creating laser and told to try to stare at the subtle blinking orange light—the only thing I could see among my otherwise absence of vision.

The laser sounds like an old DOT MATRIX printer. Tra-dat-dat-dat-dat-dat-dat. Within just a few seconds, maybe fifteen, it’s done. I’m rotated slightly, the suction is removed and my watery vision returns. I’m sure more drops were applied as Dr. Furlong peeled back the flap of my cornea. You’d think this would be the worst part, but it’s bizarrely interesting. It takes maybe 30-45 seconds to get the flap fully open which immediately changes my vision to a complete blur. Painless and too fascinating to delve on how creepy this is.

Suction is reapplied and I’m swiveled a few inches over to the corrective laser, again told to track the light. Ready? Tra-dat-dat-dat-dat-dat-dat. This is when you start smelling your flesh burning a bit—not a huge deal if you’ve ever had a root canal, or partook autocannibalism I suppose. With each laser burst, the peripheral of my vision glows in an ethereal light blue, lighter each time. Not sure what causes this effect, but it’s like an unearthly aurora borealis inside my own eye. Within 25 seconds, it’s over. “You did great!”

The pressure on my eye is released and the flap carefully peeled back into the covering position, this takes another half minute and ample eyedrops.

“You can gently close your eye now,” I comply and my freshly lasered eye is taped shut. Time for the other eye. Unsurprisingly, process for the left eye was essentially identical. (Fast forward a few minutes.)

“You can sit up now.” My legs dangle off the chair as I’m offered a kids juice to help ward off dizziness, primarily from anxiety. I can already see, well enough to walk around and get a final examination, but things are foggy rather than blurry. Dr. Furlong admires his work as he looks at my eyes through his microscope. “Excellent flaps.” We shake hands, I thank him, and I’m taken to the previous room where I’m given additional drops and care instructions. Tracy had the option to watch the surgery but opted to rejoin me in the post-op room instead. This is where they taped the silly goggles onto my face and gave me sunglasses to go over them. I’m warned that there is bruising on my eye but it will heal, that I would be extra sensitive to light, and that there would be discomfort and scratchy pain once the numbing eyedrops wear off. This was an understatement.

Tracy and I nod, pack up the supplies, and head home.

I’m pretty chipper on the walk back to the car—I could basically see already, but my mood quickly changes as the sun starts blaring through the car window while we drive home. Like a creature of the night, I hiss and try to hide from the light, but the scratchy pain and burning keep growing with each beam of light revealed while Tracy navigates the car towards home. Unsure of whether it’s the light or just the numbing wearing off or both, I want to get home and hide in a very dark room as soon as possible.

The next hour or two suck the most, worse than the surgery itself. I take two tylenol, which I should have done earlier. Later, I apply the numbing eyedrops I was given, which I also should have done earlier too. Both of these things help. I apply the numbing drops just once more after another hour, but I should have applied them more frequently in retrospect.

Eventually I was able to fall asleep, and by the time three hours pass, I find myself pain-free. My eyes still feel swollen and achey, but it’s much more manageable.

After waking up, I’m greeted with boredom but I was instructed to keep my eyes mostly closed for the rest of the night. So here I am, sitting in the dark, writing the first draft of this post, with my eyes closed.

Four months later

“Was it worth it?” Absolutely.

Today my eye sight is almost 20/15 and I’m down to ~3 lubricating eyedrops per day. Halos are not an issue anymore, though I’m still a little sensitive to light, like sunny days or oncoming traffic at night. Nothing intolerable and wearing sunglasses is much more enjoyable than corrective glasses. Overall, it feels like a significant source of stress from my life has been removed.

The procedure itself was creepy, but not painful or even that scary. I admit I was quite phobic about the whole flap thing, but after having gone through it I feel it wasn’t anywhere as bad as I feared. And after the first couple of hours, the recovery was a breeze–just don’t stinge on the numbing drops like I did.

“Should I get LASIK?” If you mind wearing glasses or contacts, and you can afford the pricetag, I highly recommend it. Especially if your prescription is reasonably weak, then there is much lower risk of needing a second touchup.

• Adium
• Chrome Firefox
• Clyppan
• Colloquy
• Dropbox
• Growl
• Homebrew Fink MacPorts
• MacVim (via Homebrew!)
• Notifyapp Google Notifier
• Pandoraboy
• Quicksilver
• Skype
• iTerm2 TotalTerminal Visor
• Transmission
• VLC
• Virtualbox
• XCode

(Based on my older post, New Macbook Pro, list of things I installed. What am I missing?)

Every offer you get will include some details and omit others. To perform a proper comparison between multiple offers and reach a good decision, you’ll need all the details for all offers. After numerous back-and-forths with several companies, I composed a checklist ideal for anyone on the verge of deciding the next stage of their career.

• Benefits: Medical, dental, vision. Yes, you’re young and healthy, but root canals are much more painful when you’re paying for them out of your pocket.
• Bonuses: Sign-on bonus, moving bonus, refresher bonus, performance bonus, yearly bonus. Some companies have them, others don’t. This affects your “total compen sation” per year.
• Career opportunities: What positions are available in the event that you earn a promotion? What is the procedure for promotions and raises? Some companies require a strict number of years of experience or qualification before you can reach specific positions.
• Culture: Dress code? Beer nights? Offsite trips?
• Equity: Stock options and restricted stock units are two that I’ve encountered. Find out the vesting conditions (when the stock actually becomes yours), and more importantly find out its value. For publically traded companies you can look up the value of each share, but for private companies 100,000 shares means nothing if you don’t know how many shares there are in total and what class your shares are (which affects your dilution). Ultimately, you want to find out what portion of the company value you are getting in the event that there is a buyout. Large and VC-funded companies will usually have less stock floating around for new hires, while smaller privately-funded companies will usually offer more stock for a lower salary. It’s up to you to determine how much you think that company (and thus, your stock) is worth. I highly recommend reading Venture Hacks’ writeup on considering offers from startups if you find yourself in that boat.
• Growth support: Will they send you to relevant conferences? Book budget? Will they pay for tuition so you can get your Master’s degree and increase your value?
• Hours: What is the company culture regarding the number of hours they’re expecting you put in? Is it a +60hr/wk sweatshop, or do they not care how late you stumble in and how early you bust out as long as your work is getting done?
• Intellectual property: Can you continue working on your open source projects on weekends? Does the company aggressively claim ownership on anything you might invent outside of the office?
• Leaving: You never know when your life might change and you have to jump ship. Keep an eye out on leaving conditions and consequences, such as having to pay back your bonuses. You don’t want to find yourself in unexpected debt.
• Perks: Free lunches, gym access and trainers, public transit pass, housing assistance, commute shuttles, relocation assistance, company events, corporate discounts. Perks don’t pay your bills, but they don’t get taxed and hopefully make you a little bit happier.
• Team: Are you working with people you will learn from and admire or a bunch of outsourced consultants struggling to not sabotage your company at every step?
• Salary: This is heavily proportional to the location and its cost of living. Your salary is worth a lot less in California than it is in Seattle where the cost of living is half, and there is no state income tax.
• Starting date: Can you take a couple of months to travel Europe before tying the corporate knot?
• Telecommuting: What is the policy for working from home? What about working abroad during an extended trip?
• Title: You might not think it matters right now, but it matters to your career. That, and salaries are often proportional to your title. Find out what positions are available in your branch of specialty and figure out what bracket they’re offering you. Big tech companies often have things like Software Engineer Level 1 (new graduate), Level 2, etc.
• Vacation: How many days of vacation per year? Personal days? Sick days?

Know what is important to you and what you’re worth

Remember that everything is negotiable. If having a beer budget is super important to you and the company really wants you on the team, figure out what it would take to make your dreams come true. Worst case scenario is they’ll say “Sorry, we can’t do that because…” and you can decide whether you still want the job or not.

Big thanks to everyone who contributed their experience to this writeup: Adam White, Greg Wilson, Isaac Ezer, Laurie, and Vincent Shen.

(Based on my older post, Considering offers? A checklist in alphabetical order)

I’m currently using SuperGenPass, but considering writing my own version that uses customizeable multipass sha512, more symbol breadth in passwords, and some other improvements.

Update: I’m using Bitwarden now, and you should too.

Derived Password Algorithm

pwgen

@jondoda wrote his own simple algorithm for deriving a per-site password based from a master password. I’ve seen many variations of this, they’re all very simple: Given a service name and a master password, concatenate them and run a hash function on it a bunch of times, then base64-encode the result and truncate to the desired length. Jon even wrote an Android version.

SuperGenPass

Same idea as Jon’s pwgen, but in a JavaScript bookmarklet! This particular implementation uses multipass md5 which is pretty weak but the rest of the implementation is impressive. You go to the login page, enter your username and master password, then hit the bookmarklet and it converts the master password into a site-specific derived password in-place. No data leaves the comfort of your browser for this. There is also a mobile version.

Proprietary

1Password

1Password is the Lexus of password management tools. It costs $39.99 for an OSX and Windows desktop license and another $11.99 for a mobile app. It lives in one file encrypted by your master password, so it’s portable and many people use Dropbox to sync it across devices. No Linux support. (Via @wolever)

LastPass

LastPass has been sold to private equity and leaked their customer data on multiple occasions. Many of their users have reported evidence that their vaults have been decrypted by third parties. Do not use LastPass.

Open Source

Bitwarden

It’s just the best, hands down. Ignore the rest, use this. It has clients on every platform, with great features and usability rivaling the best proprietary competitors, and it’s open source with an active third-party community.

KeePass

Official client is Windows-based but has ports to all desktop platforms (Linux, OSX, mobile). Self-contained binary and database, portable. Actively developed, has a healthy plugin community with extensions for major browsers. (Via @corbett_inc)

Password Gorilla

Very barebones, self contained binary, actively developed. (Via @seanpiled)

pwsafe

Even more barebones, text-based, no browser integration. (Via @jpetazzo)

SFLvault

Somewhat unrelated but cool project, useful for sharing passwords between teams. (Via @jpetazzo)

The goal is not to build an effective schemaless database on top of a relational database, but rather to accomodate for rapidly-evolving relational schemas and reducing the difficult of migrating forward.

Hypothesis

In an evolving relational (SQL) database schema, we store two types of data: Data we will be querying against and data we will be displaying. There is often a subset of display data which will not be used for querying in the foreseeable future, and this is the data whose structure changes most often.

Solution

Store query data and display data separately such that display data is less strictly-structured and thus more easily evolved.

Imagine a standardized table structure where each table has the following columns: id, time_created, time_updated, _data, and additional “index columns”.

The _data column contains a dictionary of arbitrary data serialized into JSON (or could be zlib-compressed Pickle if it were Python-specific). Index columns are columns which you query against.

Example

A typical user table might have the following columns (using an SQLAlchemy declarative model):

class User(Model):

    id = Column(types.Integer, primary_key=True)
    time_created = Column(types.DateTime, default=datetime.now, nullable=False)
    time_updated = Column(types.DateTime, onupdate=datetime.now)

    is_admin = Column(types.Boolean, default=False, nullable=False)

    email = Column(types.String(255), nullable=False, index=True, unique=True)
    display_name = Column(types.String(64))

    password_hash = Column(types.String(40), nullable=False)
    password_salt = Column(types.String(8), nullable=False)

In our example, this table will have two types of queries:

-- Load the user object from the current session (where we store the user_id)
SELECT * FROM user WHERE id = :user_id;

-- Check the given password against the email address, for login
SELECT password_hash, password_salt FROM user WHERE email = :user_email;

In the schemaless model, the table would look like this:

class User(SchemalessModel):

    id = Column(types.Integer, primary_key=True)
    time_created = Column(types.DateTime, default=datetime.now, nullable=False)
    time_updated = Column(types.DateTime, onupdate=datetime.now)
    _data = Column(types.JSON)

    email = Column(types.String(255), nullable=False, index=True, unique=True)

Where the _data column would contain data like this:

{
    "display_name": "Andrey Petrov",
    "is_admin": 1,
    "password_hash": "cSKSsy315E4EroxeDQrsxjTb6ijBxxbK",
    "password_salt": "vS5Otm",
}

And perhaps we would build a framework on top of SQLAlchemy which would let us access columns as user.display_name or user.email regardless whether it’s an extracted indexed property or a buried _data element.

Process: Adding an index

1. Build a table with just a free-structure _data field.
2. Determine queries, extract relevant properties into indexed columns:
   1. ALTER TABLE to add the column
   2. Run full-scan query to populate new column with data
   3. Add relevant index onto said column
   4. Deprecate property from _data (optional, we could just assume that proper columns always supercede _data attributes)

Concerns

• Adding an index may affect database performance during the process, due to the data locality. With FriendFeed’s approach, the indices are stored in their own tables which could even be sharded across databases, so this removes any performance concerns during schema transitions. On the other hand, FriendFeed’s approach reduces data locality which increases the number of joins required to get desired data, and also reduces the semantic meaning of the tables thus making queries more complex.
• Performing unexpected demographic analysis on large datasets would be much slower if the fields are stored in _data (such as age, gender, etc) since it would require a full table scan instead of an in-database aggregate query.
• Parsing and storing the _data dictionary has some performance implications, too. cPickle is best for parsing performance, perhaps zlib-compressed cPickle is best for data size and parsing performance tradeoff, but no portability beyond Python. zlib-compressed JSON reduces data size and is portable across languages, but increases parsing time. Also, this could be done natively for PostgreSQL using HSTORE (via jek)
• Tracking mutability is important, potentially hard to do elegantly.

• Keep a grid, always align to the vertical columns, but also strive to align to the horizontal rows if possible. For web design, using a CSS framework will help with this. I like Blueprint but there are many others like 960 which is more to the point.
• Pay attention to rhythm: Bigger spacing interlaced with small spacing creates two rhythms instead of one. One rhythm is better than two unless there’s a good reason.
• Be consistent. This includes the chrome, grid, colors, button types (link vs form button vs div), etc.
• Err on the side of more spacing. Try more first, if it looks weird then try less.
• Err on the side of simplicity. Question the existence of specific elements, get rid of them if they’re not absolutely necessary. You’re better off having your users not know how to do one obscure task than to be overwhelmed and not do any of the simple common tasks.
• Blend colors (use ColorBlendy or Photoshop equivalent). Colors on top of each other (think foreground/background) look more organic if they have an element of each other within them. I typically pick a background color (e.g. light blue like #abc) and a monochromatic foreground color (e.g. dark grey, #333) and multiply. This gives me the foreground color I should use with the light blue (ie. dark blue with a light blue).
• Avoid too many lines like separators, boxes, containers. Having incoherent details adds complexity and “busy-ness” to the interface. Instead, use empty space and arrangement. This is similar to adding too much punctuation to your writing.
• Focus on one primary user flow you’re optimizing for at a time. You rather the user be able to do the most important thing really easily than to be able to do everything kind of difficultly.

It is possible to build a beautiful interface that is completely unusable, and it’s possible to build an utilitarian and maybe unbeautiful interface which is very usable. I would aim to do the latter until you’re ready to hire a designer. It’s likely that the designer will have to rethink a lot of it from scratch as that’s just part of the design process, but that’s about as much as you can hope for.

These design guidelines have helped me reduce the designed-by-a-programmer effect when building consumer applications.

Drawing without using reference is one of my favourite hobbies. Struggling to pull an image out of the depths of my mind, like a fierce fish fighting for freedom. Reeling and reeling, until the moment when the fish bursts out of the still surface of the water, when the splash from the water blankets me as a sign of impending success. The rod sways unbalanced from the weight of the catch. The line could snap now, so I’m careful as pull it in and release it onto the paper. I look at the art of my creation as something new, something I haven’t seen before… but the image feels familiar. I conjured this from my mind.

Getting something in your mind onto paper is a difficult process. You can’t really focus on parts of the image in your mind. It’s like imagining a line between two points, and then trying to focus on that line… but you can’t, because it’s not really there.

The frustration that you feel when you’re trying to imbue your imagination onto reality, but just can’t get it to look quite right. The relieving catharsis when you achieve a sense of familiarity with your creation. That is what stuttering is like.

Frequently Asked Questions

• Are there certain things that make you stutter? There are many factors, with a large grain of randomness. Getting too little or too much sleep makes it worse. Who I’m talking to makes a big difference — large groups or people who I spend a lot of time with will rarely hear me stutter. If I spend a lot of time talking, I will stutter less over time. If I spend a lot of time not talking, I will stutter more. Some words are more “high risk” than others, in particular hard sounds like the C in Computer Science.
• I know what you’re trying to say, but you can’t get it out… should I say it for you or does that offend you? By all means, speak up. Be my autocomplete. In fact, it’s easier for me to say a word after hearing someone else say it. Unless your guess is wrong, then it can get frustrating.
• What causes stuttering? There is no conclusive answer. There are also various types of stuttering, most of which people grow out of after some years, and some of which you can train yourself to circumvent. There is definitely a large psychological factor, since I can speak to myself completely fluently. But there could just as easily be hard-coded physiological or neurological factors.

More questions are welcome.