Creating a Pretty, Inviting Repo
I made a silly mistake recently which created a messy git repo. I thought this would be fine because other people / myself would continually update the more active documents, but looking back this was fairly short-sighted/aggressively long-sighted because there probably won't be many changes for some time.1 Let me explain.
Bulk Git Commits
It's common3 for contributors to collate diverse changes into a single commit for the sake of simplicity, ease of writing less, etc. Take your motivations as you will. I've personally found that it's the easiest way to obfuscate otherwise material information / nuanced details.
But the other week, I accidentally did this in an update to the YP. I like using the handshake emoji for the LICENSE file since it rarely changes unless you want to keep the copyright year current. But when I added this to the repo, I also made a number of minor updates to all the non-image files in the repo.
Accordingly, the view here now looks relatively trashy:
Rebase and Merge 🙏
However, more relevant to adequate public disclosures, the logic behind the changes to each item is not properly documented. Namely, I filled in a gap on the third page that's existed for at least a year. This change, alongside the explicit reference to the Stellar dev docs, should have been documented in the commit name or details regarding main.tex specifically—and they weren't.
In a perfect world, each category of change would have its own commit detailing the inspiration, motivation, and significance of the change. Not only does this create a prettier repo (below)4, but it lets anyone easily see what's happening with their favorite projects without diving into the complexities of source code. And I beg you: this is web3 we're talking about; could we please keep things mildly interesting with an emoji?
Emojis let you add valuable context that would otherwise necessitate a bland tag. Consider a 🐛 instead of bug:, 🔨 instead of fix:, etc. It's a quick keyboard shortcut and search that really only takes a second even though it adds so much appeal.
-
Namely, I doubt any new sources will be added as references imminently. ↩︎
-
Four descriptive words after an emoji, with additional context in the description. See, e.g. conversation not documented publicly which can now be referenced in compliance update. These backhooks have material implications in streamlining, facilitating, and provoking permissionless innovation. ↩︎
-
I won't bother sourcing major offenders as that is not particularly respectful; most people are really trying their best. Moreover, a lot of changes come in through a PR whereby the admin opts for using the PR name rather than rebasing with individual commits. ↩︎
-
The hasty
Update resources.htmlwas a quick fix after updating the page's redirect URL. By not following my own convention,2 I drastically limited the valuable public disclosure, auditability, and transmission. ↩︎