Home.md
... ...
@@ -1,17 +1,15 @@
1
+# Tea Garden
2
+
1 3
Hello and welcome to the Tea Garden!
2 4
This cozy corner, crafted by Gaiwan, is a wiki-style haven for sharing knowledge and growing together.
3 5
It's the perfect spot for curious minds eager to dive deep into the world of learning. We're thrilled to have you here and hope your journey through the Tea Garden is enlightening and rewarding.
4 6
5 7
## Navigation
6 8
7
-- [[WikiBestPractices]] - **Start Here**
8
-- [[Gaiwan Stack]] - Our technology stack
9
-- [[Patterns]] - collection of organizational and architectural patterns and principles
10
-- [[ReadingList]] - recommended books
9
+- [[Patterns]] - **Start Here** collection of organizational and architectural patterns and principles
10
+- [[LastUpdated]] - Last updated pages in the Tea Garden pages.
11 11
12 12
13 13
<<Navigation("Patterns Navigation", "Patterns", false)>>
14 14
15 15
<<Navigation("Research Navigation", "Research", false)>>
16
-
17
-<<Navigation("Gaiwan Stack Navigation", "Gaiwan Stack", false)>>
PatternOfPatterns.md
... ...
@@ -0,0 +1,50 @@
1
+## Introduction
2
+
3
+The concept of a Pattern Language was proposed by Christopher Alexander, an architect and design theorist active in the second half of the 20th century, in a sequence of three books. This influenced a design patterns movement within Software Development, kick-started by the book *Design Patterns: Elements of Reusable Object-Oriented Software (1994)* (colloquially known as the "Gang of Four" book). This book has had an out-sized impact on Software Development practice and discourse, and has shaped the general understanding of what design patterns are and how they apply to developing, deploying, and maintaining software.
4
+
5
+
6
+## What is a Pattern?
7
+
8
+As with any concept, such as Design Patterns, that has been around for a long while, interpreted and re-interpreted by many groups and individuals over the years, it is instructive to start by stating what Design Patterns are *not*:
9
+
10
+* Design patterns are *not* mainly about objects and classes
11
+* "Design pattern" does *not* refer specifically to one of the patterns in the book
12
+* A Design Pattern is *not* something you only use in specific cases (with the rest of what a programmer writes being just "regular code" )
13
+* Design Patterns are do *not* have a set size range
14
+* A Design Pattern is *not* something that is rigid and set in stone, such that every implementation must follow every detail of the pattern to the letter
15
+* The description of a Design Pattern does *not* have to follow the formal template used in the Design Pattern book
16
+
17
+So, if Design Patterns are not any of these things, then what are they?
18
+
19
+Patterns can exist at any level of system design or development, in any flavor of programming language or approach. There are many patterns beyond those described in any single book. Indeed, new patterns will naturally arise all the time as new problems are approached by developers in new and inventive ways. If you look closely, you will find patterns exist implicitly in almost all the code you write or systems you build. Furthermore, patterns are often fractal, meaning most patterns form a combination of smaller patterns, and are themselves components in bigger patterns. Finally, and perhaps most importantly, Design Patterns form a language that constantly evolves to adapt to a changing world.
20
+
21
+
22
+## A Pattern Language
23
+
24
+In terms of the source material, the most commonly referenced of Alexander's books is *A Pattern Language* (1977), which describes a concrete set of patterns which Alexander and his collaborators found to be a useful and sufficient language for building. However, to truly understand the intent and scope of design patterns we have to read *The Timeless Way of Building* (1979), which was published a few years later, but which Alexander saw as the predecessor of A Pattern Language, setting the stage and explaining his philosophy and intent. This is the source material that we go back to for our conceptualization of A Pattern Language.
25
+
26
+It is important to note that a Pattern Language is a language, an idiom, which shares many characteristics with natural language. It is shared by a group of people who use it daily as a means of communication. It forms a basis for developing and expressing ideas. Different, but adjacent, groups will often speak similar, overlapping but distinct pattern languages, and each person will use that language in their own unique way.
27
+
28
+Much like natural languages, a pattern language may evolve over time as it grows and changes and meanings shift. A word's meaning is its usage (this is descriptivist, rather than prescriptivist, view of language with which we agree), and so too with a pattern: how it is used determines what it means beyond any prescribed definition.
29
+
30
+The pattern language described in the **Tea Garden** is the language spoken by the Gaiwan team, our common vernacular. The patterns in our pattern language can extend from the very small (tiny programming language idioms) to the very large (deployment and maintenance of entire systems), and even beyond the purely technical to organizational and social patterns. We describe patterns wherever we see them and find them useful and hope that, by sharing them here, others can benefit from the growth and evolution of our pattern language.
31
+
32
+
33
+## The Pattern of Patterns
34
+
35
+When it is time to start a new project, or a major new feature of an existing project, there are typically many technical decisions that need to be made. How you approach these decisions, and how you evaluate the patterns you choose for crafting a solution, forms a pattern in and of itself. We call this the "Pattern of Patterns", and the patterns that you will find in the **Tea Garden** will, for the most part, follow this pattern. In a sense, this pattern forms the foundation upon which we hope to build the **Tea Garden**'s Pattern Language.
36
+
37
+So what is the "Pattern of Patterns"? We have found that approaching a new way of doing things (a new "Pattern", if you will) generally proceeds through 4 phases:
38
+
39
+1. High-Level Evaluation
40
+2. Narrowing of Candidate Approaches
41
+3. Adoption
42
+4. Dealing with the Consequences
43
+
44
+Within the Tea Garden project, we explore an array of patterns, presenting each with a concise overview, a comparison of possible approaches with a focus on Gaiwan's choice, and a discussion on common challenges with solutions. This structured exploration aims to equip users with the necessary insights to effectively implement these patterns, and hopefully elevate their software development practices.
45
+
46
+## Conclusion
47
+
48
+For Alexander, a Pattern describes a set of relationships between building or environmental elements that, when followed, help to resolve tensions and inner contradictions that exist within the larger system. This is a very useful framing. Much of the software pattern literature talks about "forces" rather than "tensions". We prefer "tension", since this is also what one feels while working on these systems. Trying to combine elements in software design is not always straightforward. The software pushes back. It creates tension, and we as developers and architects feel that tension within us. A good pattern will allow us to resolve these tensions, and when we reach that point we will literally experience a feeling of resolution and release.
49
+
50
+By applying these patterns, and resolving these tensions, we can hope to approach a Timeless Way of Building Software. Software that is imbued with the quality without a name. Alive, whole, elegant, precise, ego-less, eternal, free from inner contradictions.
UriAsData.md
... ...
@@ -0,0 +1,25 @@
1
+## High-Level Overview
2
+
3
+Uniform Resource Identifiers (URIs) are the familiar strings that we use to navigate to websites, to create links that send emails or make phonecalls, or even to connect to a database. However, unlike other strings that seem like they should follow a certain format, but don't (like [names](https://www.kalzumeus.com/2010/06/17/falsehoods-programmers-believe-about-names/), [addresses](https://www.mjt.me.uk/posts/falsehoods-programmers-believe-about-addresses/), and even [phone numbers](https://chromium.googlesource.com/external/libphonenumber/+/HEAD/FALSEHOODS.md)), URI strings are rigorously controlled and must adhere to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) to be considered valid.
4
+
5
+For this reason, even though URIs are most commonly transmitted between processes or machines as strings, for example when you type an address into a browser's navigation bar or read a database connection string from an environment variable, it is advisable to convert any URI you have to deal with into structured data at the "edge" of your code, and to work with it as structured data within your code. URIs should only be converted back to strings when they again reach the edge of your code and are being transmitted to a receiver that expects a string, when they are being displayed in a UI that expects a string for display, or when they are being stored on a medium that cannot efficiently serialize and restore structured data (e.g. a database with a "string" column for URIs).
6
+
7
+This is not a pattern that you need to apply if your application handles URIs only incidentally (i.e. as part of a payload being transmitted between two points, but not being manipulated or introspected), or if it never modifies, constructs, or destructures URIs. However, if you do any sort of manipulation with URIs, doing so with traditional string manipulation tools (such as regular expressions) is bound to lead to trouble.
8
+
9
+## Candidate Solutions
10
+
11
+There are a number of libraries available in Clojure to work with URIs as structured data. Since Clojure is a hosted language, there is always the option of using a library from the underlying platform to manage URIs, such as JavaScript's [URL](https://developer.mozilla.org/en-US/docs/Web/API/URL) or Java's [URI](https://kapeli.com/dash_share?docset_file=Java&docset_name=Java%20SE21&path=java.base/java/net/URI.html&platform=java&repo=Main&version=SE21). There are, however, a number of Clojure specific options:
12
+
13
+* [exploding-fish](https://github.com/wtetzner/exploding-fish): A Clojure-only library that can handle accessing parts of URIs, updating URIs, normalization, and resolution
14
+* [com.cemerick/url](https://github.com/cemerick/url): A now-archived library that works across Clojure and ClojureScript that allows access to parts of URIs
15
+* [Urly](https://github.com/michaelklishin/urly): A tiny, Clojure-only library that provides a protocol that allows accessing parts of URIs and can work with strings, `java.net.URI`s, `java.net.URL`s, and its own representation of URIs
16
+* [uri](https://github.com/codonnell/uri): A Clojure-only wrapper around `java.net.URI` that enables construction of URIs and conversion to maps of their parts
17
+* [lambdaisland/uri](https://github.com/lambdaisland/uri?tab=readme-ov-file): A pure Clojure and ClojureScript library that represents URIs as records and can join URIs as well as construct/deconstruct and manipulate them
18
+
19
+## The Gaiwan Recommendation
20
+
21
+Perhaps unsurprisingly, we recommend [lambdaisland/uri](https://github.com/lambdaisland/uri?tab=readme-ov-file). This is our recommendation not only because it is the library that we developed and maintain, but also because it is not reliant on an underlying platform dependency for its functionality. This may seem like a trivial concern, since URI libraries for the platforms Clojure runs on seem so stable, but the same could have been said about Java's `Date` and `Time` classes in 2013, before they were completely re-implemented in Java 8. Having complete control over how a URI's components are represented and manipulated within the library also ensures consistency across platforms.
22
+
23
+## Caveats and Potential Pit-Falls
24
+
25
+Perhaps the most important caveat to be aware of when working with URIs is that, since they are a data-structure that is most often represented and transmitted as strings, they have their own encoding of string data known as [percent-encoding](https://en.wikipedia.org/wiki/Percent-encoding). It is important to be aware of when components of a URI need to be string encoded and when they do not. For example, by not percent-encoding a path element of a URI that contains a "/", you may inadvertently create an additional path element when you did not intend to.