diff --git a/content/journal/dispatch-3-may-2023/Results - Tar Heel 10 Miler.pdf b/content/journal/dispatch-3-may-2023/10_miler_results.pdf similarity index 100% rename from content/journal/dispatch-3-may-2023/Results - Tar Heel 10 Miler.pdf rename to content/journal/dispatch-3-may-2023/10_miler_results.pdf diff --git a/content/journal/dispatch-3-may-2023/index.md b/content/journal/dispatch-3-may-2023/index.md index 0c50365..38f45cd 100644 --- a/content/journal/dispatch-3-may-2023/index.md +++ b/content/journal/dispatch-3-may-2023/index.md @@ -6,10 +6,22 @@ tags: - dispatch - ebikes references: +- title: "Some Favorite Reads From 2022 • by Kyle Aster" + url: https://warpspire.com/posts/some-favorite-reads-2022 + date: 2023-04-30T18:47:22Z + file: warpspire-com-bhv7lv.txt +- title: "Simple Commit Linting for Issue Number in GitHub Actions | Viget" + url: https://www.viget.com/articles/simple-commit-linting-for-issue-number-in-github-actions/ + date: 2023-04-30T18:47:23Z + file: www-viget-com-biybeb.txt - title: "What Do You Want to Make Real in the World? — Anna Havron" url: https://www.annahavron.com/blog/what-do-you-want-to-make-real-in-the-world date: 2023-04-30T03:38:36Z file: www-annahavron-com-34fw9w.txt +- title: "A Brief History & Ethos of the Digital Garden" + url: https://maggieappleton.com/garden-history + date: 2023-04-30T18:47:58Z + file: maggieappleton-com-n6xsqa.txt --- Last month: @@ -18,9 +30,11 @@ Last month: * Closet project * E-bike * [Aventon Pace 500][1] -* Tar Heel 10 Miler +* Tar Heel 10 Miler ([results][2], [certificate][3]) [1]: https://www.aventon.com/products/pace500-3-step-through-ebike +[2]: 10_miler_results.pdf +[3]: 10_miler_certificate.png @@ -32,24 +46,24 @@ This month: Reading: -* Fiction: [_Long Shadows_][2], David Baldacci -* Non-fiction: [_Building a Second Brain_][3], Tiago Forte - * _Looks like the author did a [podcast][4] I should check out_ +* Fiction: [_Long Shadows_][4], David Baldacci +* Non-fiction: [_Building a Second Brain_][5], Tiago Forte + * _Looks like the author did a [podcast][6] I should check out_ -[2]: https://bookshop.org/p/books/long-shadows-david-baldacci/18261851?ean=9781538719824 -[3]: https://bookshop.org/p/books/building-a-second-brain-a-proven-method-to-organize-your-digital-life-and-unlock-your-creative-potential-tiago-forte/18265370?ean=9781982167387 -[4]: https://www.artofmanliness.com/character/advice/podcast-816-building-a-second-brain/ +[4]: https://bookshop.org/p/books/long-shadows-david-baldacci/18261851?ean=9781538719824 +[5]: https://bookshop.org/p/books/building-a-second-brain-a-proven-method-to-organize-your-digital-life-and-unlock-your-creative-potential-tiago-forte/18265370?ean=9781982167387 +[6]: https://www.artofmanliness.com/character/advice/podcast-816-building-a-second-brain/ Links: -* [_This Is How You Lose The Time War_][5] - * [recommended here][6] -* [Simple Commit Linting for Issue Number in GitHub Actions | Viget][7] -- short post on my company blog about two topics dear to me: continuous integration and information retrieval -* [What Do You Want to Make Real in the World?][8] -* [A Brief History & Ethos of the Digital Garden][9] +* [_This Is How You Lose The Time War_][7] + * [recommended here][8] +* [Simple Commit Linting for Issue Number in GitHub Actions | Viget][9] -- short post on my company blog about two topics dear to me: continuous integration and information retrieval +* [What Do You Want to Make Real in the World?][10] +* [A Brief History & Ethos of the Digital Garden][11] -[5]: https://bookshop.org/p/books/this-is-how-you-lose-the-time-war-amal-el-mohtar/18270911 -[6]: https://warpspire.com/posts/some-favorite-reads-2022 -[7]: https://www.viget.com/articles/simple-commit-linting-for-issue-number-in-github-actions/ -[8]: https://www.annahavron.com/blog/what-do-you-want-to-make-real-in-the-world -[9]: https://maggieappleton.com/garden-history +[7]: https://bookshop.org/p/books/this-is-how-you-lose-the-time-war-amal-el-mohtar/18270911 +[8]: https://warpspire.com/posts/some-favorite-reads-2022 +[9]: https://www.viget.com/articles/simple-commit-linting-for-issue-number-in-github-actions/ +[10]: https://www.annahavron.com/blog/what-do-you-want-to-make-real-in-the-world +[11]: https://maggieappleton.com/garden-history diff --git a/content/journal/dispatch-3-may-2023/tar-heel-10-miler-2023-david-eisinger.png b/content/journal/dispatch-3-may-2023/tar-heel-10-miler-2023-david-eisinger.png deleted file mode 100644 index afdd320..0000000 Binary files a/content/journal/dispatch-3-may-2023/tar-heel-10-miler-2023-david-eisinger.png and /dev/null differ diff --git a/static/archive/maggieappleton-com-n6xsqa.txt b/static/archive/maggieappleton-com-n6xsqa.txt new file mode 100644 index 0000000..0c50a77 --- /dev/null +++ b/static/archive/maggieappleton-com-n6xsqa.txt @@ -0,0 +1,772 @@ + #[1]Main RSS Feed + + [2]Home + The Garden (BUTTON) + [3]Now + [4]About + (BUTTON) + + Essays + + evergreen + +A Brief History & Ethos of the Digital Garden + + A newly revived philosophy for publishing personal knowledge on the web + * [5]Digital Gardening + * [6]Personal Knowledge + * [7]The Web + + Planted almost 3 years agoLast tended almost 2 years ago + + (BUTTON) Back To Top + +Table of Contents + + [8]A Brief History of Digital Gardens[9]The Early Gardens of + Hypertext[10]Digital Puttering on Twitter[11]Gardens, Streams, and + Caufield's Metaphors[12]Carrying on Caufield[13]Digital Gardening's + Fertile Soil[14]Developer-led Gardening[15]The Six Patterns of + Gardening[16]1. Topography over Timelines[17]2. Continuous Growth[18]3. + Imperfection & Learning in Public[19]4. Playful, Personal, and + Experimental[20]5. Intercropping & Content Diversity[21]6. Independent + Ownership + +Table of Contents + + [22]A Brief History of Digital Gardens[23]The Early Gardens of + Hypertext[24]Digital Puttering on Twitter[25]Gardens, Streams, and + Caufield's Metaphors[26]Carrying on Caufield[27]Digital Gardening's + Fertile Soil[28]Developer-led Gardening[29]The Six Patterns of + Gardening[30]1. Topography over Timelines[31]2. Continuous Growth[32]3. + Imperfection & Learning in Public[33]4. Playful, Personal, and + Experimental[34]5. Intercropping & Content Diversity[35]6. Independent + Ownership + Loading... + + My highlighted a number of sites that are taking a new approach to the + way we publish personal knowledge on the web. + + They're not following the conventions of the "personal blog," as we've + come to know it. Rather than presenting a set of polished articles, + displayed in reverse chronological order, these sites act more like + free form, work-in-progress wikis. + + A garden is a collection of evolving ideas that aren't strictly + organised by their publication date. They're inherently exploratory – + notes are linked through contextual associations. They aren't refined + or complete - notes are published as half-finished thoughts that will + grow and evolve over time. They're less rigid, less performative, and + less perfect than the personal websites we're used to seeing. + + It harkens back to the early days of the web when people had fewer + notions of how websites "should be.” It's an ethos that is both + classically old and newly imagined. + __________________________________________________________________ + + [36] + +A Brief History of Digital Gardens + + Let's go on a short journey to the origin of this word. The notion of a + digital garden is not a 2020 invention. It's been floating around for + over two decades. However, it's passed through a couple of semantic + shifts in that time, meaning different things to different people + across the years. As words tend to do. + + Tracing back how + [37]Neologisms + are born helps us understand why anyone needed this word in the first + place. Language is always a response to the evolving world around us – + we expand it when our current vocabulary fails to capture what we're + observing, or have a particular desire for how we'd like the future to + unfold. Naming is a political act as much as a poetic one. + +The Early Gardens of Hypertext + + Mark Bernstein's 1998 essay appears to be the first recorded mention of + the term. Mark was part of the early hypertext crowd – the developers + figuring out how to arrange and present this new medium. + + While the essay is a beautiful ode to free-wheeling internet + exploration, it's less about building personal internet spaces, and + more of a manifesto on user experience flows and content organisation. + + Let's note that Mark's graphics are to die for + + To put this in its historical context, Mark's writing was part of a + larger conversation happening throughout the nineties around hypertext + and its metaphorical framing. + + The early web-adopters were caught up in the idea of The Web as a + labyrinth-esque community landscape tended by and These creators wanted + to enable pick-your-own-path experiences, while also providing enough + signposts that people didn't feel lost in their new, strange medium. + + The early web debates around this became known as – the issue of how to + give web users just enough guidance to freely explore the web, without + forcing them into pre-defined browsing experiences. The eternal + struggle to find the right balance of chaos and structure. + + "Unplanned hypertext sprawl is wilderness: complex and interesting, + but uninviting. Interesting things await us in the thickets, but we + may be reluctant to plough through the brush, subject to thorns and + mosquitoes" + + While Mark's essay was concerned with different problems to the ones we + face on the web today, its core ethos feels aligned with our emerging + understanding of digital gardening. It captures the desire for + exploratory experiences, a welcoming of digital weirdness, and a + healthy amount of resistance to top-down structures. + + After Mark's essay the term digital gardening goes quiet for nearly a + decade. + +Digital Puttering on Twitter + + In April of 2007 when Tweets first started ringing through the internet + airwaves, Rory Sutherland (oddly, the vice president of Ogilvy Group) + used the term "digital gardening", but defined it as "faffing about + syncing things, defragging - like pruning for young people" + Loading... + + The next dozen mentions on Twitter all followed this sentiment – people + were using the term as a way to describe digital maintenance - the act + of cleaning up one's digital space. The focus was on sorting, weeding, + pruning, and decluttering, rather than growing and cultivating. People + mentioned cleaning out private folders, codebases, and photo albums as + the focus of their gardening efforts. + + These people were digital puttering more than gardening. + Loading... + Loading... + Loading... + + Since none of these folks reference to the earlier nineties notion of + digital gardening, or mention issues of hypertext navigation, this use + of the word feels like a brief tangent. Given the tiny size of Twitter + in the early days, these people probably belonged to the same social + flocks and were riffing off one another. It's not necessarily part of + the mainstream narrative we're tracking, but shows there's not one + strict meaning to the term. + + That said, some degree of faffing about, sorting, and pruning are + certainly part of the practice of digital gardening. Though best + enjoyed in moderation. + +Gardens, Streams, and Caufield's Metaphors + + At the 2015 Digital Learning Research Network, Mike Caufield delivered + a keynote on . It later becomes that lays the foundations for our + current understanding of the term. If anyone should be considered the + original source of digital gardening, it's Caufield. They are the first + to lay out this whole idea in poetic, coherent words. + + Caufield makes clear digital gardening is not about specific tools – + it's not a Wordpress plugin, Gastby theme, or Jekyll template. It's a + different way of thinking about our online behaviour around information + - one that accumulates personal knowledge over time in an explorable + space. + + Caufield's main argument was that we have become swept away by streams + – the collapse of information into single-track timelines of events. + The conversational feed design of email inboxes, group chats, and + InstaTwitBook is fleeting – they're only concerned with self-assertive + immediate thoughts that rush by us in a few moments. + + This is not inherently bad. Streams have their time and place. Twitter + is a force-multiplier for exploratory thoughts and delightful + encounters once you fall in with the right crowd and learn to play the + game. + + But streams only surface the Zeitgeisty ideas of the last 24 hours. + They are not designed to accumulate knowledge, connect disparate + information, or mature over time. + + The garden is our counterbalance. Gardens present information in a + richly linked landscape that grows slowly over time. Everything is + arranged and connected in ways that allow you to explore. Think about + the way Wikipedia works when you're hopping from to to . It's + hyperlinking at it's best. You get to actively choose which curiosity + trail to follow, rather than defaulting to the algorithmically-filtered + ephemeral stream. The garden helps us move away from time-bound streams + and into contextual knowledge spaces. + + "The Garden is the web as topology. The web as space. It’s the + integrative web, the iterative web, the web as an arrangement and + rearrangement of things to one another." + +Carrying on Caufield + + Good ideas take time to germinate, and Caufield's vision of the + personal garden didn't reach critical mass right off the bat. It lay + dormant, waiting for the right time and the right people to find it. + + In late 2018 the corner of Twitter I hang out in began using the term + more regularly – folks began passing around Caufield's original article + and experimenting with ways to turn their chronological blogs into + exploratory, interlinked gardens. + + Tom Critchlow's 2018 article was one of the main kick-off points. Tom + read Caufield's essay and began speculating on alternative metaphors to + frame the way we consume and produce information. They suggested we add + campfires to the idea of streams and gardens – the private Slack + groups, casual blog rings, and + [38]Cozy Web + areas where people write in response to one another. While gardens + present the ideas of an individual, campfires are conversational spaces + to exchange ideas that aren't yet fully formed. + + Tom piece was shortly followed by Joel Hooks' in early 2019. Joel + focused on the process of digital gardening, emphasising the slow + growth of ideas through writing, rewriting, editing, and revising + thoughts in public. Instead of slapping Fully Formed Opinions up on the + web and never changing them. + + Joel also added Amy Hoy's post to the pile of influential ideas that + led to our current gardening infatuation. While not specifically about + gardening, Amy's piece gives us a lot of good historical context. In + it, she explores the history of blogs over the last three decades, and + pinpoints exactly when we all became fixated on publishing our thoughts + in reverse chronological order (spoiler: around 2001 with the launch of + ). + + Amy argues that Moveable Type didn't just launch us into the + "Chronological Sort Era". It also killed the wild, diverse, hodge-podge + personalisation of websites that characterised the early web. Instead + of hand-coding your own layout and deciding exactly how to arrange the + digital furniture, we began to enter the age of standardised layouts. + Plug n' play templates that you drop content into became the norm. It + became harder and more technically involved to edit the HTML & CSS + yourself. + + "Suddenly people weren’t creating homepages or even web pages... + they were writing web content in form fields and text areas inside a + web page." + + Many people have lamented the web's slow transition from unique + homepages to a bland ocean of generic Wordpress themes. Digital + gardening is part of the pushback against the limited range of vanilla + web formats and layouts we now for granted. + + Over the course 2019 and early 2020, more and more people began riffing + on the concept. Shaun Wang compiled the . Anne-Laure Le Cunff published + a popular guide to setting up . The IndieWeb community hosted a to + discuss the history of commonplace books, personal wikis, and memory + palaces. + + By late 2020 this whole concept had attracted enough attention for the + MIT Tech Review to write on it. Perhaps this is the watershed moment + when a Twitter buzzword has "made it." + +Digital Gardening's Fertile Soil + + What made our current historical moment the right time for digital + gardening to take off? + + The timing coincided with a few complimentary ideas and communities + rallying around personal knowledge systems, note-taking practices, and + reimagining tools for blogging. The scene was ripe for new ideas around + curating and sharing personal knowledge online. + + Many of the people who jumped on the early digital gardening bandwagon + were part of communities like... + * The collective – a group that has been championing independent web + spaces outside the walled gardens of Instatwitbook for nearly a + decade. + * Users of the note-taking app – Roam pioneered new ways of + interlinking content and strongly appeals to people trying to build + sprawling knowledge graphs. + * Followers of Tiago Forte's course which popularised the idea of + actively curating personal knowledge. + * People rallying around the ethos that encourages continuously + creating 'learning exhaust' in the form of notes and summaries. + +Developer-led Gardening + + Many of these early adopters were people who understood how to build + websites – either professional developers or enthusiastic hobbyists. + Any kind of novel experimentation with the web requires knowing a + non-trivial amount of HTML, CSS, and JS. Not to mention all the + surrounding infrastructure required actually to get a site live. + Developers took to the idea because they already had the technical + ability to jump in play around with what garden-esque websites might + look like. + + The current state of web development helped here too. While it feels + like we've been in a slow descent into a horrifyingly complex and + bloated web development process, a number of recent tools have made it + easier to get a fully customised website up and running. Services like + and have taken the pain out of deployment. Static site generators like + , , and make it easier to build sophisticated websites that + auto-generate pages, and take care of grunt work like optimising load + time, images, and SEO. These services are trying to find a happy middle + ground between tediously hand-coding solutions, and being trapped in + the restrictions of Wordpress or Squarespace. + + While developers were the first on the scene, plenty of writers, + researchers, and note-taking enthusiasts have been drawn to the idea of + digital gardening. To help folks without programming skills join in, + there's been a surge in templates and platforms that allow people to + build their own digital gardens without touching a ton of code. I've + written an entire guide to + [39]Digital Gardening for Non-Technical Folks + if you fall into that category. + + Tools like , , and are all great options. Many of them offer fancy + features like nested folders, + [40]Bi-Directional Links + , footnotes, and visual graphs. + + However, many of these no-code tools still feel like cookie-cutter + solutions. Rather than allowing people to design the and spatial + layouts of their gardens, they inevitably force people into pre-made + arrangements. This doesn't meant they don't "count,” as "real” gardens, + but simply that they limit their gardeners to some extent. You can't + design different types of links, novel features, experimental layouts, + or custom architecture. They're pre-fab houses instead of raw building + materials. + __________________________________________________________________ + + [41] + +The Six Patterns of Gardening + + In all the recent gardening flurry, we've run into the inevitable + confusion around how to define the term. + Loading... + + There are contested ideas about what qualifies as a garden, what the + core ethos should focus on, and whether it's worthy of a new label at + all. What exactly makes a website a digital garden as opposed to just + another blog? + + After reading all the existing takes on the term, observing a wide + variety of gardens, and collecting some of the , I've identified a few + key qualities they all share. + + There are a few guiding principles, design patterns and structures + people are rallying around. This amounts to a kind of digital gardening + [42]Pattern Language + . + +1. Topography over Timelines + + Gardens are organised around contextual relationships and associative + links; the concepts and themes within each note determine how it's + connected to others. + + This runs counter to the time-based structure of traditional blogs: + posts presented in reverse chronological order based on publication + date. + + Gardens don't consider publication dates the most important detail of a + piece of writing. Dates might be included on posts, but they aren't the + structural basis of how you navigate around the garden. Posts are + connected to other by posts through related themes, topics, and shared + context. + + One of the best ways to do this is through + [43]Bi-Directional Links + – links that make both the destination page and the source page visible + to the reader. This makes it easy to move between related content. + + Because garden notes are densely linked, a garden explorer can enter at + any location and follow any trail they link through the content, rather + than being dumped into a "most recent” feed. + + Dense links are essential, but gardeners often layer on other ways of + exploring their knowledge base. They might have , , tags and filtering + functionality, , , or listing notable and popular content. + + Many entry points but no prescribed pathways. + +2. Continuous Growth + + Gardens are never finished, they're constantly growing, evolving, and + changing. Just like a real soil, carrot, and cabbage garden. + + The isn't how we usually think about writing on the web. Over the last + decade, we've moved away from casual live journal entries and + formalised our writing into articles and essays. These are carefully + crafted, edited, revised, and published with a timestamp. When it's + done, it's done. We act like tiny magazines, sending our writing off to + the printer. + + This is odd considering editability is one of the main selling points + of the web. Gardens lean into this – there is no "final version” on a + garden. What you publish is always open to revision and expansion. + + Gardens are designed to evolve alongside your thoughts. When you first + have an idea, it's fuzzy and unrefined. You might notice a pattern in + your corner of the world, but need to collect evidence, consider + counter-arguments, spot similar trends, and research who else has thunk + such thoughts before you. In short, you need to do your homework and + critically think about it over time. + + In performance-blog-land you do that thinking and researching + privately, then shove it out at the final moment. A grand flourish that + hides the process. + + In garden-land, that process of researching and refining happens on the + open internet. You post ideas while they're still "seedlings,” and tend + them regularly until they're fully grown, respectable opinions. + + This has a number of benefits: + * You're freed from the pressure to get everything right immediately. + You can test ideas, get feedback, and revise your opinions like a + good internet citizen. + * It's low friction. Gardening your thoughts becomes a daily ritual + that only takes a small amount of effort. Over time, big things + grow. + * It gives readers an insight into your writing and thinking process. + They come to realise you are not a magical idea machine banging out + perfectly formed thoughts, but instead an equally mediocre human + doing The Work of trying to understand the world and make sense of + it alongside you. + + This all comes with an important caveat; gardens make their + imperfection known to readers. Which brings us to the next pattern... + +3. Imperfection & Learning in Public + + Gardens are imperfect by design. They don't hide their rough edges or + claim to be a permanent source of truth. + + Putting anything imperfect and half-written on an "official website” + may feel strange. We have all been trained to behave like tiny, + performative corporations when it comes to presenting ourselves in + digital space. Blogging evolved in the culture of Millenialism as a way + to Promote Your Personal Brand™ and market your SEO-optimized Content. + + Weird, quirky personal blogs of the early 2000's turned into cleanly + crafted brands with publishing strategies and media campaigns. Everyone + now has a modern minimalist logo and an LLC. + + Digital gardening is the response to the professional personal blog; + it's both intimate and public, weird and welcoming. It's less + performative than a blog, but more intentional and thoughtful than a + Twitter feed. It wants to build personal knowledge over time, rather + than engage in banter and quippy conversations. + + Think of it as a spectrum. Things we dump into private WhatsApp group + chats, DMs, and cavalier Tweet threads are part of our chaos streams - + a continuous flow of high noise / low signal ideas. On the other end we + have highly performative and cultivated artefacts like published books + that you prune and tend for years. + + Gardening sits in the middle. It's the perfect balance of chaos and + cultivation. + + This ethos of imperfection opens up a world of possibility that + performative blogging shut down. First, it enables you to ; the + practice of sharing what you learn as you're learning it, not a decade + later once you're an "expert.” + + This freedom of course comes with great responsibility. Publishing + imperfect and early ideas requires that we make the status of our notes + clear to readers. You should include some indicator of how "done” they + are, and how much effort you've invested in them. + + This could be with a simple categorisation system. I personally use an + overly horticultural metaphor: + * 🌱 Seedlings for very rough and early ideas + * 🌿 Budding for work I've cleaned up and clarified + * 🌳 Evergreen for work that is reasonably complete (though I still + tend these over time). + + I also include the dates I planted and last tended a post so people get + a sense of how long I've been growing it. + + Other gardeners include an epistemic status on their posts – a short + statement that makes clear how they know what they know, and how much + time they've invested in researching it. + + was one of the earliest and most consistent gardeners to offer + meta-reflections on their work. Each entry comes with: + * topic tags + * start and end date + * a stage tag: draft, in progress, or finished + * a certainty tag: impossible, unlikely, certain, etc. + * 1-10 importance tag + + These are all explained in their , which is worth reading if you're + designing your own epistemological system. + + Devon Zuegal is another notable gardener who has epistemic status and + epistemic effort on their posts, indicating both their certainty level + about the material, and how much effort went into making it. They also + make a strong case for as a feature, not a bug. + + In a similar vein, Shawn Wang has written the Digital Gardening which I + adore and ascribe to. They ask the reader to allow the writer to be + wrong, offer constructive criticism, and attribute their work. They ask + gardeners to be considerate of others (don't share private information + or name and shame), offer epistemic disclosure, and respond to + feedback. + The digital gardening terms of service – Source: Shawn Wang, swyx.io + + All of these design patterns feed our growing desire for transparency, + meta information, and breadcrumbs back to the source of ideas. + +4. Playful, Personal, and Experimental + + Gardens are non-homogenous by nature. You can plant the same seeds as + your neighbour, but you'll always end up with a different arrangement + of plants. + + Digital gardens should be just as unique and particular as their + vegetative counterparts. The point of a garden is that it's a personal + playspace. You organise the garden around the ideas and mediums that + match your way of thinking, rather than off someone else's standardised + template. + + Ideally, this involves experimenting with the native languages of the + web – HTML, CSS, and JavaScript. They're the most flexible and robust + tools we have for building interconnected knowledge online. Gardens are + a chance to question the established norms of a 'personal website', and + make space for weirder, wilder experiments. + + That said, I should acknowledge that jumping into full-on web + development is simply beyond the abilities and interests of many + people. There is still room for personalisation and play if you're + using a pre-made template or service – it'll just be within the + constraints of that system. + + One goal of these hyper-personalised gardens is deep contextualisation. + The overwhelming lesson of the Web 2.0 social media age is that dumping + millions of people together into decontextualised social spaces is a + shit show. Devoid of any established social norms and abstracted from + our specific cultural identities, we end up in awkward, aggravating + exchanges with people who are socially incoherent to us. We know + nothing of their lives, backgrounds, or belief systems, and have to + assume the worst. Twitter only offers us a 240 character bio. Facebook + pre-selects the categories it deems important about you – relationship + status, gender, hometown. + + Gardens offer us the ability to present ourselves in forms that aren't + cookie cutter profiles. They're the higher-fidelity version, complete + with quirks, contradictions, and complexity. + +5. Intercropping & Content Diversity + + Gardens are not just a collection of interlinked words. While linear + writing is an incredible medium that has served us well for a little + over 5000 years, it is daft to pretend working in a single medium is a + sufficient way to explore complex ideas. + + It is also absurd to ignore the fact we're living in an audio-visual + cornucopia that the web makes possible. Podcasts, videos, diagrams, + illustrations, interactive web animations, academic papers, tweets, + rough sketches, and code snippets should all live and grow in the + garden. + [intercropping-garden_shrink_mx6nx8.png] + + Historically, monocropping has been the quickest route to starvation, + pests, and famine. Don't be a lumper potato farmer while everyone else + is sustainably intercropping. + +6. Independent Ownership + + Gardening is about claiming a small patch of the web for yourself, one + you fully own and control. + + This patch should not live on the servers of Facebook, LinkedIn, + Twitter, Instagram (aka. also Facebook), or Medium. None of these + platforms are designed to help you slowly build and weave personal + knowledge. Most of them actively fight against it. + + If any of those services go under, your writing and creations sink with + it (crazier things have happened in the span of humanity). None of them + have an easy export button. And they certainly won't hand you your data + in a transferable format. + A set of walled gardens with the Twitter, Medium, and Facebook logos + next to an open garden built on HTML, CSS, and Markdown + + Independently owning your garden helps you plan for long-term change. + You should think about how you want your space to grow over the next + few decades, not just the next few months. + + If you give it a bit of forethought, you can build your garden in a way + that makes it easy to transfer and adapt. Platforms and technologies + will inevitably change. Using old-school, reliable, and widely used web + native formats like HTML/CSS is a safe bet. Backing up your notes as + flat markdown files won't hurt either. + + Keeping your garden on the open web also sets you up to take part in + the future of gardening. At the moment our gardens are rather solo + affairs. We haven't figure out how to make them multi-player. But + there's an enthusiastic community of developers and designers trying to + fix that. It's hard to say what kind of libraries, frameworks, and + design patterns might emerge out of that effort, but it certainly isn't + going to happen behind a Medium paywall. + A set of gardens with plant life moving between them + __________________________________________________________________ + + This is all my take on gardening, but knowledge and neologisms always + live within communities. No one owns The Official Definition of digital + gardening. Numerous people have contributed to the growing conversation + and you should read their thoughts as well. + + Want to share? (BUTTON) Tell Twitter About It + +8 Backlinks + +The Expanding Dark Forest and Generative AI + + Proving you're a human on a web flooded with generative AI content + +A Short History of Bi-Directional Links + + Seventy years ago we dreamed up links that would allow us to create + two-way, contextual conversations. Why don't we use them on the web? + +Digital Gardening for Non-Technical Folks + + How to build a digital garden without touching code + +Transclusion and Transcopyright Dreams + + The lost permissioning and copyright system of the Web + +The Pattern Language of Project Xanadu + + Project Xanadu as a pattern language, rather than a failed software + project + +Growing the Evergreens + + Illustrated notes on the concept of 'Evergreen notes' and how to write + them + +A Meta-Tour of This Site + + A video tour through how I build the old version of this site + +Tending Evergreen Notes in Roam Research + + A walkthrough of how I manage and tend Evergreen notes in Roam + +Mentions around the web + + subterraneanwebZ + a new hope + with-heart + Winson Tang + Hacker News + Abra Tusz + King | "OG" Zettelkasten 🧠 2nd Brain 🚢 + HN Front Page + ⎯ΘωΘ⟶ + lqdev + Evgeny Kuznetsov + Brad + Brad + Chris Aldrich + DixOnGE + talyssa + Chris Krycho + márcio moreira + 84 Likes and Retweets + [44]wildrye.commentionedMarch 10, 2023 + Image by Pallangor, How to Make a Beautiful Minecraft GardenGarden of + Infinite Possibilities Jorge Luis Borges’ story the “Garden of Forking + Paths” is set in an elaborate garden, but the real garden is a book + that is structured in such a way as to allow infinite possibilities. + [45]wildrye.commentionedMarch 09, 2023 + Mike Caufield talks about his collection of notes in his wiki and how + they work together as a rich network of ideas. Part of his method is to + very carefully describe the relationship between two ideas when he + builds his links. These descriptions become ideas in their own right. + [46]Cristinamentionedin What the heck is a digital garden?March 04, + 2023 + Digital gardens are a relatively new concept that are gaining + popularity online. They are often described as a cross between a blog + and a personal wiki. At its core, a digital garden is a place for + someone to share their thoughts, ideas, and learning experiences in a + more casual + Whatdefang + [47]WhatdefangmentionedFebruary 28, 2023 + Naming is a political act as much as a poetic one. + (BUTTON) Show 33 more + +Want to stay up to date? + + (BUTTON) Subscribe via RSS Feed + © 2023 Maggie Appleton + * [48]The Garden + * [49]Essays + * [50]About + * [51]Notes + * [52]Now + * [53]Patterns + * [54]Library + * [55]Projects + * [56]Colophon + +References + + Visible links: + 1. https://maggieappleton.com/rss.xml + 2. https://maggieappleton.com/ + 3. https://maggieappleton.com/now + 4. https://maggieappleton.com/about + 5. https://maggieappleton.com/topics/digital-gardening + 6. https://maggieappleton.com/topics/personal-knowledge + 7. https://maggieappleton.com/topics/the-web + 8. https://maggieappleton.com/garden-history#a-brief-history-of-digital-gardens + 9. https://maggieappleton.com/garden-history#the-early-gardens-of-hypertext + 10. https://maggieappleton.com/garden-history#digital-puttering-on-twitter + 11. https://maggieappleton.com/garden-history#gardens-streams-and-caufield's-metaphors + 12. https://maggieappleton.com/garden-history#carrying-on-caufield + 13. https://maggieappleton.com/garden-history#digital-gardening's-fertile-soil + 14. https://maggieappleton.com/garden-history#developer-led-gardening + 15. https://maggieappleton.com/garden-history#the-six-patterns-of-gardening + 16. https://maggieappleton.com/garden-history#1-topography-over-timelines + 17. https://maggieappleton.com/garden-history#2-continuous-growth + 18. https://maggieappleton.com/garden-history#3-imperfection-&-learning-in-public + 19. https://maggieappleton.com/garden-history#4-playful-personal-and-experimental + 20. https://maggieappleton.com/garden-history#5-intercropping-&-content-diversity + 21. https://maggieappleton.com/garden-history#6-independent-ownership + 22. https://maggieappleton.com/garden-history#a-brief-history-of-digital-gardens + 23. https://maggieappleton.com/garden-history#the-early-gardens-of-hypertext + 24. https://maggieappleton.com/garden-history#digital-puttering-on-twitter + 25. https://maggieappleton.com/garden-history#gardens-streams-and-caufield's-metaphors + 26. https://maggieappleton.com/garden-history#carrying-on-caufield + 27. https://maggieappleton.com/garden-history#digital-gardening's-fertile-soil + 28. https://maggieappleton.com/garden-history#developer-led-gardening + 29. https://maggieappleton.com/garden-history#the-six-patterns-of-gardening + 30. https://maggieappleton.com/garden-history#1-topography-over-timelines + 31. https://maggieappleton.com/garden-history#2-continuous-growth + 32. https://maggieappleton.com/garden-history#3-imperfection-&-learning-in-public + 33. https://maggieappleton.com/garden-history#4-playful-personal-and-experimental + 34. https://maggieappleton.com/garden-history#5-intercropping-&-content-diversity + 35. https://maggieappleton.com/garden-history#6-independent-ownership + 36. https://maggieappleton.com/garden-history#a-brief-history-of-digital-gardens + 37. https://maggieappleton.com/neologisms + 38. https://maggieappleton.com/cozy-web + 39. https://maggieappleton.com/nontechnical-gardening + 40. https://maggieappleton.com/bidirectionals + 41. https://maggieappleton.com/garden-history#the-six-patterns-of-gardening + 42. https://maggieappleton.com/pattern-languages + 43. https://maggieappleton.com/bidirectionals + 44. https://wildrye.com/what-is-a-digital-garden/ + 45. https://wildrye.com/the-digital-garden-as-an-experience-generator/ + 46. https://embersonthehearth.com/2023/03/04/what-the-heck-is-a-digital-garden/ + 47. https://twitter.com/whatdefang/status/1630464510740815872 + 48. https://maggieappleton.com/garden + 49. https://maggieappleton.com/essays + 50. https://maggieappleton.com/about + 51. https://maggieappleton.com/notes + 52. https://maggieappleton.com/now + 53. https://maggieappleton.com/patterns + 54. https://maggieappleton.com/library + 55. https://maggieappleton.com/projects + 56. https://maggieappleton.com/colophon + + Hidden links: + 58. https://github.com/MaggieAppleton + 59. https://uk.linkedin.com/in/maggieappleton + 60. https://dribbble.com/mappleton + 61. https://twitter.com/Mappletons + 62. https://indieweb.social/@maggie diff --git a/static/archive/warpspire-com-bhv7lv.txt b/static/archive/warpspire-com-bhv7lv.txt new file mode 100644 index 0000000..66cda09 --- /dev/null +++ b/static/archive/warpspire-com-bhv7lv.txt @@ -0,0 +1,333 @@ + #[1]alternate + + * [2]Now + * [3]Giving + * [4]Offsets + * [5]About Me + +Some Favorite Reads From 2022 + + January 15, 2023 + + Another year, and another [6]blog post (singular). Oh well. I always + have aspirations to publish more! But you know, one of the joys of + being semi-retired is not having to do anything. You know, it’s been a + hard few years. So I tried to take it easy on myself in 2022. I spent a + lot of time exploring, a lot of time reflecting, and a good bit of time + just doing whatever felt right at the time. + + For example, going on a road trip with my mountain bike + + Recently I’ve been reflecting on some of my favorite things from last + year. Maybe as a way to focus on the positive. Maybe as a way to keep + track of time in our time sick world. Maybe just to get back into the + habit of writing. So here’s some of my favorite reads of 2022. + __________________________________________________________________ + +Books + + I really enjoy reading, but this year I kind of gave myself a pass on + anything too serious — mostly sticking to my trusty home base + of science fiction. + * [7][this-is-how-you-lose-the-time-war.jpg] + +This is How You Lose The Time War + * [8][rendevous-with-rama.jpg] + +Rendevous with Rama + * [9][elder-race.jpg] + +Elder Race + * [10][artifact-space.jpg] + +Artifact Space + +Amal El-Mohtar and Max Gladstone’s [11]This is How You Lose the Time War + + From the publisher: + + Among the ashes of a dying world, an agent of the Commandment finds + a letter. It reads: Burn before reading. + + Thus begins an unlikely correspondence between two rival agents + hellbent on securing the best possible future for their warring + factions. Now, what began as a taunt, a battlefield boast, becomes + something more. Something epic. Something romantic. Something that + could change the past and the future. + + I fucking loved this book. I started it based on a recommendation from + a friend, and didn’t really look into it much before I started. This + book is much less about the plot (which is a play off The End of + Eternity) and more about the writing and world building. The best way I + could describe it is a spy story told through love letters in a poetic + universe. + + Think of birds as a comms channel I can open and close seasonally; + fellow operatives relate their work to me at the equinoxes; Garden + blooms more brightly in my belly. There’s enough traffic that it’s a + simple matter to disguise incoming and outgoing correspondence, + misdirect, hide in plain sight. + + It’s also a short read, which was a nice breath of fresh air after + finishing off the Dune series prior to picking this one up. I have a + feeling this is going to be one of my most recommended books going + forward. + +Arthur C. Clarke’s [12]Rendevous with Rama + + From the publisher: + + An enormous cylindrical object has entered Earth’s solar system on a + collision course with the sun. A team of astronauts are sent to + explore the mysterious craft, which the denizens of the solar system + name Rama. What they find is astonishing evidence of a civilization + far more advanced than ours. They find an interior stretching over + fifty kilometers; a forbidding cylindrical sea; mysterious and + inaccessible buildings; and strange machine-animal hybrids, or + “biots,” that inhabit the ship. But what they don’t find is an alien + presence. So who–and where–are the Ramans? + + I’d never read the Rama books before, so when I heard that Denis + Villeneuve was going to be [13]tackling Rendevous with Rama, I took the + opportunity to read the whole series (Rendevous with Rama, Rama II, The + Garden of Rama, and Rama Revealed). + + Rendevous with Rama is a fantastically Clarke book. A team of highly + trained professionals all work together to explore a mysterious object + in space. Does much more need to be said? This book went down like a + peanut butter and jelly sandwich. My only criticism is that it left me + wanting for was more. + + Rama is a cosmic egg, being warmed by the fires of the Sun. It may + hatch at any moment. + + And unfortunately, there is more. + + Clarke teamed up with Gentry Lee to write three more novels — Rama II, + The Garden of Rama, and Rama Revealed and I all I can say is: I do not + recommend them. They are upsetting in very odd child-bride wedding + night kinds of ways. + +Adrian Tchaikovsky’s [14]Elder Race + + From the publisher: + + A junior anthropologist on a distant planet must help the locals he + has sworn to study to save a planet from an unbeatable foe. + + I loved Tchaikovsky’s Children of Time, so when I heard Jason Snell + offer up Elder Race on The Incomperable, I decided to give it a go. I + absolutely love the premise of this book. It’s a singular story told + from two different viewpoints, one of them science fiction, and the + other fantasy — both happening in parallel — because the two main + characters don’t share enough dialect to explain themselves to each + other. + + They think I’m a wizard. They think I’m a fucking wizard. That’s + what I am to them, some weird goblin man from another time with + magic powers. And I literally do not have the language to tell them + otherwise. I say, “scientist,” “scholar,” but when I speak to them, + in their language, these are both cognates for “wizard.” I imagine + myself standing there speaking to Lyn and saying, “I’m not a wizard; + I’m a wizard, or at best a wizard.” It’s not funny. + + And who doesn’t love an old, cranky wizard anthropologist? + +Miles Cameron’s [15]Artifact Space + + From the publisher: + + Out in the darkness of space, something is targeting the Greatships. + + With their vast cargo holds and a crew that could fill a city, the + Greatships are the lifeblood of human occupied space, transporting + an unimaginable volume - and value - of goods from City, the + greatest human orbital, all the way to Tradepoint at the other, to + trade for xenoglas with an unknowable alien species. + + This was another recommendation from a friend, and I’m glad I picked it + up. At it’s core, it’s about highly competent people all working + together, pushing their limits, and achieving success. It’s the kind of + genre someone once described to me as competency porn — Star Trek: The + Next Generation being the ultimate example. + + There was very little drama in Space Operations. In fact, every + station projected an elaborate aura of calm, as if they were + competing to be dry and emotionless. No one swore, no one spat, no + one was angry or afraid. Nbaro loved it. + + This book pulls from a lot of familiar ideas — the Greatships are an + obvious call back to Battlestars, while a lot of the socialist themes + call back to Star Trek’s economy. My biggest criticism of this book is + the maddening way Cameron switches back and forth between using + character’s first and last names — even within the same scene! It makes + it incredibly difficult to keep track of who is who with such a large + cast, and toward the end I caught myself not even remembering who a + certain person was. + +Dennis E. Taylor’s [16]Heaven’s River (Audiobook) + + From the publisher: + + More than a hundred years ago, Bender set out for the stars and was + never heard from again. There has been no trace of him despite + numerous searches by his clone-mates. Now Bob is determined to + organize an expedition to learn Bender’s fate—whatever the cost. + + The Bobiverse is probably my favorite audiobook series of all time. + It’s all a part of a grand space opera spanning the galaxy… but also + pretty sarcastic and silly? Ray Porter does an amazing job of narrating + these books, and is a large part of why I enjoy them so much. + + Heaven’s River finds a way to pull the series back from the infinite + and focuses back down on a single planet for a great little beaver + adventure. + + Well, space beavers. + __________________________________________________________________ + +Even More Books + + Neal Stephenson’s [17]Termination Shock: Okay, I actually like + Stephenson, and this is a very good book about the inevitable future of + Geoengineering and it’s political consequences. Coupled with a very + weird Queen fetish. It’s weird. Weird enough to take away from the + story line. But if the climate angle of the book interests you — I + highly recommend [18]After Geoengineering as a follow-up. + + Baoshu’s [19]The Redemption of Time: A semi-official 4th book of the + Three Body Problem. This is a great continuation of the series, and a + good way to answer some lingering questions about the Trisolarians. + + Frank Herbert’s [20]Heretics of Dune (Dune 5): I was a little shocked + at how much I loved this book. I mean, I love Dune. But this one ended + up being one of my favorites of the series. Great new characters, new + technologies, and a whole new set of powers for the Atreides genetics. + + Adrian Tchaikovsky’s [21]Children of Time: This was actually a re-read + in preparation of reading Children of Ruin and the upcoming Children of + Memory. What can I say? It’s one of my favorite science fiction books + of all time — even if only for the worldbuilding. Sentient spiders? + Sentient spiders! + __________________________________________________________________ + +Newsletters + +Alex Steffen’s [22]The Snap Forward + + From [23]Discontinuity is the Job: + + To be alive right now is to find ourselves flattened against the + fact that the entire human world—our cities and infrastructure, our + economy and education system, our farms and factories, our laws and + politics—was built for a different planet. + + I can’t remember exactly how I stumbled on Alex Steffen’s The Snap + Forward but the idea instantly clicked with me. His newsletter focuses + on how climate has affected our infrastructure, our society, and our + relationship to the world. I love his newsletter because it makes me + feel more sane in a world that keeps trying to sell a new carbon offset + marketplace as the solution. + + From [24]Tempo, Timing, and the Translucence of the Future + + The tempo of change, and our refusal to acknowledge its + acceleration, has turned our visions of continuity, stability and + value into fantasy worlds. We’re cosplaying people who live in past + decades before discontinuity ate our societies. + + I wouldn’t classify The Snap Forward as doomerism, either. It’s a focus + on accepting the world as it is and looking for solutions within that + framework. Even if all emissions were cut to zero tomorrow, we’d still + be facing a myriad of very challenging futures. What do we do with that + knowledge? How do we prepare for the transapocalyptic now? + +Matt Levine’s [25]Money Stuff + + I’ve been reading Money Stuff for a few years now, and I can’t really + put my thumb on why I love it so much. Sure, it’s about finance… but + kind of the weird stuff in finance. More about the cogs of the + machinery and the weird personalities in the news than it is about + whether the S&P 500 is going to go up or down next week. + + From [26]FTX’s Balance Sheet Was Bad: + + But then there is the “Hidden, poorly internally labeled ‘fiat@’ + account,” with a balance of negative $8 billion. I don’t actually + think that you’re supposed to subtract that number from net equity — + though I do not know how this balance sheet is supposed to work! — + but it doesn’t matter. If you try to calculate the equity of a + balance sheet with an entry for HIDDEN POORLY INTERNALLY LABELED + ACCOUNT, Microsoft Clippy will appear before you in the flesh, + bloodshot and staggering, with a knife in his little paper-clip + hand, saying “just what do you think you’re doing Dave?” You cannot + apply ordinary arithmetic to numbers in a cell labeled “HIDDEN + POORLY INTERNALLY LABELED ACCOUNT.” The result of adding or + subtracting those numbers with ordinary numbers is not a number; it + is prison. + + It’s an understatement to say I don’t love finance, but I do enjoy me + some Money Stuff. + __________________________________________________________________ + +What’s Next? + + I’ve really been enjoying re-visiting some of my favorite authors and + finishing off big series I never quite got around to. Last year I + finally finished off the whole of Frank Herbert’s Dune (never having + read 5 & 6 before), and this year I’m getting the itch to do the same + for Foundation. To be frank, I don’t even remember where I ended with + that series. But it does feel like a good opportunity to maybe just + re-visit the entirety of the Asimov Universe… [27]in chronological + order. I’m also getting a terrible itch to revisit a bunch of + Vonnegut’s work after watching the excellent [28]Unstuck in Time. But I + like new authors too! + + I’m also interested in finding more books and newsletters about… I + guess you’d call it urban design. Stuff like [29]Strong Towns and other + sources of how to adapt our cities into resilient communities. I + actually have background in city planning from my Civil Engineering + days, but I feel like there’s been a big surge in new thinking that + goes farther than the YIMBY/NIMBY noise of the past decade. + + Have some recommendations? Hit me up on Mastadon: + [30]@kneath@indieweb.social. + + Est. 2003 • Do Hard Things • Build. Learn. Explore. + +References + + Visible links: + 1. http://warpspire.com/feed/ + 2. https://warpspire.com/now + 3. https://warpspire.com/giving + 4. https://warpspire.com/offset + 5. https://warpspire.com/about + 6. https://warpspire.com/posts/money-pit + 7. https://bookshop.org/p/books/this-is-how-you-lose-the-time-war-amal-el-mohtar/18270911?aid=13508&ean=9781534430990&gclid=CjwKCAiAy_CcBhBeEiwAcoMRHMYspqPk88ZoP8--CUUbXYfJi5-1npSPEUSq-QroPTijJK-cIC1CAxoCIGsQAvD_BwE&listref=this-is-how-you-lose-the-time-war + 8. https://bookshop.org/p/books/rendezvous-with-rama-arthur-c-clarke/8296887?ean=9780358380221 + 9. https://bookshop.org/p/books/elder-race-adrian-tchaikovsky/15877279 + 10. https://bookshop.org/p/books/artifact-space-miles-cameron/18367466?ean=9781473232617 + 11. https://bookshop.org/p/books/this-is-how-you-lose-the-time-war-amal-el-mohtar/18270911?aid=13508&ean=9781534430990&gclid=CjwKCAiAy_CcBhBeEiwAcoMRHMYspqPk88ZoP8--CUUbXYfJi5-1npSPEUSq-QroPTijJK-cIC1CAxoCIGsQAvD_BwE&listref=this-is-how-you-lose-the-time-war + 12. https://bookshop.org/p/books/rendezvous-with-rama-arthur-c-clarke/8296887?ean=9780358380221 + 13. https://www.hollywoodreporter.com/movies/movie-news/denis-villeneuve-rendezvous-with-rama-movie-1235062337/ + 14. https://bookshop.org/p/books/elder-race-adrian-tchaikovsky/15877279 + 15. https://bookshop.org/p/books/artifact-space-miles-cameron/18367466?ean=9781473232617 + 16. https://www.amazon.com/Heavens-River-Bobiverse-Book-4/dp/B088C51F5H/ref=tmm_aud_swatch_0?_encoding=UTF8&qid=&sr= + 17. https://bookshop.org/p/books/termination-shock-neal-stephenson/18272978?ean=9780063028067 + 18. https://bookshop.org/books/after-geoengineering-climate-tragedy-repair-and-restoration/9781788730365 + 19. https://bookshop.org/p/books/the-redemption-of-time-a-three-body-problem-novel-baoshu/6986329?ean=9781250306005 + 20. https://bookshop.org/p/books/heretics-of-dune-frank-herbert/7513860?ean=9780593098264 + 21. https://bookshop.org/p/books/children-of-time-adrian-tchaikovsky/113411?ean=9780316452502 + 22. https://alexsteffen.substack.com/ + 23. https://alexsteffen.substack.com/p/discontinuity-is-the-job + 24. https://alexsteffen.substack.com/p/tempo-timing-and-the-translucence + 25. https://www.bloomberg.com/account/newsletters/money-stuff + 26. https://newsletters.feedbinusercontent.com/818/8185a1196937308adee75e80f544a29a36b34a5f.html + 27. https://gist.github.com/kneath/27a2772f5e1871e3c314ef05a4cacd44 + 28. https://www.vonnegutmovie.com/ + 29. https://www.strongtowns.org/ + 30. https://indieweb.social/@kneath + + Hidden links: + 32. https://warpspire.com/ diff --git a/static/archive/www-viget-com-biybeb.txt b/static/archive/www-viget-com-biybeb.txt new file mode 100644 index 0000000..d38d318 --- /dev/null +++ b/static/archive/www-viget-com-biybeb.txt @@ -0,0 +1,419 @@ + #[1]Viget Articles + + IFRAME: [2]https://www.googletagmanager.com/ns.html?id=GTM-5V7V + + [3]Skip to Main Content + + [4]Viget + + * [5]Work + * [6]Services + * [7]Articles + * [8]Careers + * [9]Contact + * (BUTTON) Open Menu + +Navigation + + [10]Viget (BUTTON) Close + * Practice + * [11]Work + * [12]Services + * [13]Articles + + We’re a full-service digital agency that’s been helping clients make + lasting change since 1999. + [14]Contact Us + +People + + * [15]Company + * [16]Careers + * [17]Code of Ethics + * [18]Diversity & Inclusion + +More + + * [19]Pointless Corp. + * [20]Explorations + * [21]Code at Viget + +Featured + + Read the Article: AI in Recruiting + + Newsletter + +AI in Recruiting + + Git logo variation + + Article + +Simple Commit Linting for Issue Number in GitHub Actions + +Simple Commit Linting for Issue Number in GitHub Actions + + Git logo variation + [22]David Eisinger + + [23]David Eisinger, Development Director + + Article Category: [24]#Code + + Posted on April 28, 2023 + * Share + * Share + * Tweet + + Including relevant ticket numbers in your git commit messages is a gift + to your future self. Here's how to ensure you do it consistently. + + I don't believe there is a right way to do software; I think teams can + be effective (or ineffective!) in a lot of different ways using all + sorts of methodologies and technologies. But one hill upon which I will + die is this: referencing tickets in commit messages pays enormous + dividends over the long haul and you should always do it. As someone + who regularly commits code to apps created in the Obama era, nothing + warms my heart like running [25]:Git blame on some confusing code and + seeing a reference to a GitHub Issue where I can get the necessary + context. And, conversely, nothing sparks nerd rage like fix bug or PR + feedback or, heaven forbid, oops. + + In a recent [26]project retrospective, the team identified that we + weren't being as consistent with this as we'd like, and decided to take + action. I figured some sort of commit linting would be a good candidate + for [27]continuous integration — when a team member pushes a branch up + to GitHub, check the commits and make sure they include a reference to + a ticket. + + I looked into [28]commitlint, but I found it a lot more opinionated + than I am — I really just want to make sure commits begin with either + [#XXX] (an issue number) or [n/a] — and rather difficult to + reconfigure. After struggling with it for a few hours, I decided to + just DIY it with a simple inline script. If you just want something you + can drop into a GitHub Actions YAML file to lint your commits, here it + is (but stick around and I'll break it down and then show how to do it + in a few other languages): + steps: + - name: Checkout code + uses: actions/checkout@v3 + with: + fetch-depth: 0 + + - name: Set up ruby 3.2.1 + uses: ruby/setup-ruby@v1 + with: + ruby-version: 3.2.1 + + - name: Lint commits + run: | + git log --format=format:%s HEAD ^origin/main | ruby -e ' + $stdin.each_line do |msg| + next if /^\[(#\d+|n\/a)\]/.match?(msg) + warn %(Commits must begin with [#XXX] or [n/a] (#{msg.strip})) + exit 1 + end + ' + + A few notes: + * That fetch-depth: 0 is essential in order to be able to compare the + branch being built with main (or whatever you call your primary + development branch) — by default, your Action only knows about the + current branch. + * git log --format=format:%s HEAD ^origin/main is going to give you + the first line of every commit that's in the source branch but not + in main; those are the commits we want to lint. + * With that list of commits, we loop through each message and compare + it with the regular expression /^\[(#\d+|n\/a)\]/, i.e. does this + message begin with either [#XXX] (where X are digits) or [n/a]? + * If any message does not match, print an error out to standard error + (that's warn) and exit with a non-zero status (so that the GitHub + Action fails). + + If you want to try this out locally (or perhaps modify the script to + validate messages in a different way), here's a docker run command you + can use: +echo '[#123] Message 1 +[n/a] Message 2 +[#122] Message 3' | docker run --rm -i ruby:3.2.1 ruby -e ' + $stdin.each_line do |msg| + next if /^\[(#\d+|n\/a)\]/.match?(msg) + warn %(Commits must begin with [#XXX] or [n/a] (#{msg.strip})) + exit 1 + end +' + + Note that running this command should output nothing since these are + all valid commit messages; modify one of the messages if you want to + see the failure state. + +Other Languages [29]# + + Since there's a very real possibility you might not otherwise install + Ruby in your GitHub Actions, and because I weirdly enjoy writing the + same code in a bunch of different languages, here are scripts for + several of Viget's other favorites: + +JavaScript [30]# + +git log --format=format:%s HEAD ^origin/main | node -e " + let msgs = require('fs').readFileSync(0).toString().trim().split('\n'); + for (let msg of msgs) { + if (msg.match(/^\[(#\d+|n\/a)\]/)) { continue; } + process.stderr.write('Commits must begin with [#XXX] or [n/a] (' + msg + ')' +); + process.exit(1); + } +" + + To test: +echo '[#123] Message 1 +[n/a] Message 2 +[#122] Message 3' | docker run --rm -i node:18.15.0 node -e " + let msgs = require('fs').readFileSync(0).toString().trim().split('\n'); + for (let msg of msgs) { + if (msg.match(/^\[(#\d+|n\/a)\]/)) { continue; } + process.stderr.write('Commits must begin with [#XXX] or [n/a] (' + msg + ')' +); + process.exit(1); + } +" + +PHP [31]# + +git log --format=format:%s HEAD ^origin/main | php -r ' + while ($msg = fgets(STDIN)) { + if (preg_match("/^\[(#\d+|n\/a)\]/", $msg)) { continue; } + fwrite(STDERR, "Commits must begin with #[XXX] or [n/a] (" . trim($msg) . ") +\n"); + exit(1); + } +' + + To test: +echo '[#123] Message 1 +[n/a] Message 2 +[#122] Message 3' | docker run --rm -i php:8.2.4 php -r ' + while ($msg = fgets(STDIN)) { + if (preg_match("/^\[(#\d+|n\/a)\]/", $msg)) { continue; } + fwrite(STDERR, "Commits must begin with #[XXX] or [n/a] (" . trim($msg) . ") +\n"); + exit(1); + } +' + +Python [32]# + +git log --format=format:%s HEAD ^origin/main | python -c ' +import sys +import re +for msg in sys.stdin: + if re.match(r"^\[(#\d+|n\/a)\]", msg): + continue + print("Commits must begin with #[xxx] or [n/a] (%s)" % msg.strip(), file=sys +.stderr) + sys.exit(1) +' + + To test: +echo '[#123] Message 1 +[n/a] Message 2 +[#122] Message 3' | docker run --rm -i python:3.11.3 python -c ' +import sys +import re +for msg in sys.stdin: + if re.match(r"^\[(#\d+|n\/a)\]", msg): + continue + print("Commits must begin with #[xxx] or [n/a] (%s)" % msg.strip(), file=sys +.stderr) + sys.exit(1) +' + __________________________________________________________________ + + So there you have it: simple GitHub Actions commit linting in most of + Viget's favorite languages (try as I might, I could not figure out how + to do this in [33]Elixir, at least not in a concise way). As I said up + front, writing good tickets and then referencing them in commit + messages so that they can easily be surfaced with git blame pays huge + dividends over the life of a codebase. If you're not already in the + habit of doing this, well, the best time to start was Initial commit, + but the second best time is today. + + [34]David Eisinger + + [35]David is Viget's managing development director. From our Durham, + NC, office, he builds high-quality, forward-thinking software for PUMA, + the World Wildlife Fund, NFLPA, and many others. + [36]More articles by David + +Related Articles + + * Maintenance Matters: Timely Upgrades + Article + +Maintenance Matters: Timely Upgrades + Chris Manning + * Styling the Native File Upload Input Field + Article + +Styling the Native File Upload Input Field + Eric Fuhrmann + * 10 SQL Tricks That I Like + Article + +10 SQL Tricks That I Like + Noah Over + +The Viget Newsletter + + Nobody likes popups, so we waited until now to recommend our + newsletter, featuring thoughts, opinions, and tools for building a + better digital world. [37]Read the current issue. + + [38]Subscribe Here (opens in new window) + +Site Footer + + Have an unsolvable problem or audacious idea? + + Let’s get to work + [39]Contact Us [40]hello@viget.com [41]703.891.0670 + + * Practice + * [42]Work + * [43]Services + * [44]Articles + + * People + * [45]Company + * [46]Careers + * [47]Code of Ethics + * [48]Diversity & Inclusion + + * More + * [49]Pointless Corp. + * [50]Explorations + * [51]Code at Viget + +Sign Up For Our Newsletter + + A curated periodical featuring thoughts, opinions, and tools for + building a better digital world. + [52]Check it out + +Social Links + + [53]Viget + * + * + * + * + * + * + +Office Locations + + * [54]Washington DC Metro + * [55]Durham, NC + * [56]Boulder, CO + * [57]Chattanooga, TN + + © 1999 – 2023 Viget Labs, LLC. [58]Terms [59]Privacy [60]MRF + + * [61]Home + * [62]Articles + * [63]Simple Commit Linting for Issue Number in GitHub Actions + + [64]Subscribe (opens in a new window) + (BUTTON) Share + * [65]Share this page + * [66]Share this page + * [67]Tweet this page + +References + + Visible links: + 1. https://feeds.feedburner.com/Viget + 2. https://www.googletagmanager.com/ns.html?id=GTM-5V7V + 3. https://www.viget.com/articles/simple-commit-linting-for-issue-number-in-github-actions/#content + 4. https://www.viget.com/ + 5. https://www.viget.com/work/ + 6. https://www.viget.com/services/ + 7. https://www.viget.com/articles/ + 8. https://www.viget.com/careers/ + 9. https://www.viget.com/contact/ + 10. https://www.viget.com/ + 11. https://www.viget.com/work/ + 12. https://www.viget.com/services/ + 13. https://www.viget.com/articles/ + 14. https://www.viget.com/contact/ + 15. https://www.viget.com/about/ + 16. https://www.viget.com/careers/ + 17. https://www.viget.com/code-of-ethics/ + 18. https://www.viget.com/diversity-equity-and-inclusion/ + 19. https://pointlesscorp.com/ + 20. https://explorations.viget.com/ + 21. https://code.viget.com/ + 22. https://www.viget.com/about/team/deisinger/ + 23. https://www.viget.com/about/team/deisinger/ + 24. https://www.viget.com/articles/category/code/ + 25. https://github.com/tpope/vim-fugitive#fugitivevim + 26. https://www.viget.com/articles/get-the-most-out-of-your-internal-retrospectives/ + 27. https://www.viget.com/articles/maintenance-matters-continuous-integration/ + 28. https://commitlint.js.org/ + 29. https://www.viget.com/articles/simple-commit-linting-for-issue-number-in-github-actions/#other-languages + 30. https://www.viget.com/articles/simple-commit-linting-for-issue-number-in-github-actions/#javaScript + 31. https://www.viget.com/articles/simple-commit-linting-for-issue-number-in-github-actions/#php + 32. https://www.viget.com/articles/simple-commit-linting-for-issue-number-in-github-actions/#python + 33. https://elixir-lang.org/ + 34. https://www.viget.com/about/team/deisinger/ + 35. https://www.viget.com/about/team/deisinger/ + 36. https://www.viget.com/about/team/deisinger/ + 37. https://www.viget.com/newsletter + 38. http://eepurl.com/gtHqsj + 39. https://www.viget.com/contact/ + 40. mailto:hello@viget.com?subject=Hello, Viget! + 41. tel:7038910670 + 42. https://www.viget.com/work/ + 43. https://www.viget.com/services/ + 44. https://www.viget.com/articles/ + 45. https://www.viget.com/about/ + 46. https://www.viget.com/careers/ + 47. https://www.viget.com/code-of-ethics/ + 48. https://www.viget.com/diversity-equity-and-inclusion/ + 49. https://pointlesscorp.com/ + 50. https://explorations.viget.com/ + 51. https://code.viget.com/ + 52. https://www.viget.com/newsletter/ + 53. https://www.viget.com/ + 54. https://www.viget.com/dc-metro-hq/ + 55. https://www.viget.com/durham/ + 56. https://www.viget.com/boulder/ + 57. https://www.viget.com/chattanooga/ + 58. https://www.viget.com/terms-conditions/ + 59. https://www.viget.com/privacy-policy/ + 60. https://individual.carefirst.com/individuals-families/mandates-policies/machine-readable-file.page + 61. https://www.viget.com/ + 62. https://www.viget.com/articles + 63. https://www.viget.com/articles/simple-commit-linting-for-issue-number-in-github-actions/#hero + 64. http://eepurl.com/gtHqsj + 65. https://www.facebook.com/sharer/sharer.php?u=https://www.viget.com/articles/simple-commit-linting-for-issue-number-in-github-actions/ + 66. http://www.linkedin.com/shareArticle?mini=true&url=https://www.viget.com/articles/simple-commit-linting-for-issue-number-in-github-actions/ + 67. https://twitter.com/intent/tweet?text=Including relevant ticket numbers in your git commit messages is a gift to your future self. Here's how to ensure you do it consistently. https://www.viget.com/articles/simple-commit-linting-for-issue-number-in-github-actions/ + + Hidden links: + 69. https://www.viget.com/newsletter/ai-in-recruiting/ + 70. https://www.viget.com/articles/simple-commit-linting-for-issue-number-in-github-actions/ + 71. https://www.facebook.com/sharer/sharer.php?u=https%3A%2F%2Fwww.viget.com%2Farticles%2Fsimple-commit-linting-for-issue-number-in-github-actions%2F + 72. http://www.linkedin.com/shareArticle?mini=true&url=https%3A%2F%2Fwww.viget.com%2Farticles%2Fsimple-commit-linting-for-issue-number-in-github-actions%2F + 73. https://twitter.com/intent/tweet?text=Including%20relevant%20ticket%20numbers%20in%20your%20git%20commit%20messages%20is%20a%20gift%20to%20your%20future%20self.%20Here%27s%20how%20to%20ensure%20you%20do%20it%20consistently.%20https%3A%2F%2Fwww.viget.com%2Farticles%2Fsimple-commit-linting-for-issue-number-in-github-actions%2F + 74. https://www.viget.com/articles/maintenance-matters-timely-upgrades/ + 75. https://www.viget.com/articles/styling-native-file-upload-input-field/ + 76. https://www.viget.com/articles/10-sql-tricks-that-i-like/ + 77. https://twitter.com/viget + 78. https://github.com/vigetlabs + 79. https://dribbble.com/viget + 80. https://www.instagram.com/viget/ + 81. https://www.linkedin.com/company/viget-labs + 82. https://vimeo.com/viget/collections