docs: update decision docs around slack, pnpm, uv, load-testing

Author: spwoodcock

docs/code-of-conduct.md

@@ -40,7 +40,7 @@ The HOT community principles are:
 - **Be respectful.** Not all of us will agree all the time, but disagreement is
   no excuse for poor behavior and poor manners. We might all experience some
   frustration now and then, but we cannot allow that frustration to turn into a
-  personal attack. It’s important to remember that a community where people feel
+  personal attack. It's important to remember that a community where people feel
   uncomfortable or threatened is not a productive one. Members of the HOT
   community should be respectful when dealing with other members as well as with
   people outside the HOT community.
@@ -79,9 +79,9 @@ The HOT community principles are:
   technical, happen easily and often. It is important that we resolve such
   disagreements and differing views constructively. At times it can be hard to
   appreciate a viewpoint that contradicts your own perceptions. Instead of pushing
-  back, try to understand where the other person is coming from, and don’t be
+  back, try to understand where the other person is coming from, and don't be
   afraid to ask questions. You can be most helpful if your own replies serve to
-  clarify, rather than to escalate an issue. Also don’t forget that it can be
+  clarify, rather than to escalate an issue. Also don't forget that it can be
   easy to make mistakes, and allow for the possibility that the mistake may have
   been yours. When this happens it is better to resolve the issue together, and
   to learn from the experience together, than to place blame.

docs/decisions/0006-slack.md

@@ -1 +1,55 @@
-# Use Slack to engage with our community members
+# Use Slack as our primary team and community chat platform
+
+## Context and Problem Statement
+
+We need a platform for:
+
+- Day-to-day team communication and asynchronous coordination.
+- Community engagement and support.
+- Integration with project tooling (e.g., CI/CD notifications, GitHub activity).
+- Easy onboarding for new collaborators and contributors.
+
+Our ideal platform would also:
+
+- Be accessible to external contributors.
+- Support persistent message history.
+- Be open and interoperable, with low risk of vendor lock-in.
+- Respect user privacy and data sovereignty.
+
+## Considered Options
+
+- Slack
+- Zulip
+- Mattermost
+- Rocket.Chat
+- Matrix / Element
+
+## Decision Outcome
+
+Slack was adopted early in our organizational growth, largely because:
+
+- Many existing and incoming collaborators were already on Slack.
+- It provided a smooth UX with strong mobile and desktop support.
+- NGO discounts made the Pro plan affordable, allowing for full message history and
+  integrations.
+
+However, as we scale and become more conscious of long-term sustainability, Slack's
+proprietary nature and closed ecosystem present issues.
+
+Migrating to an open platform would align better with our values, but the migration
+cost and risk of fracturing our community are currently too high.
+
+## Consequences
+
+- ✅ Good, because our community is already established on Slack.
+- ✅ Good, because integrations (e.g., with GitHub, monitoring tools, deployment
+  notifications) are mature and easy to configure.
+- ✅ Good UX, especially for newcomers, thanks to wide adoption and familiar UI.
+- ❌ Bad, because Slack is a proprietary, closed platform with limited options
+  for self-hosting or data ownership.
+- ❌ Bad, because the free tier is too limited (e.g., no full message history),
+  making us reliant on discounted paid plans.
+- ❌ Bad, migration to open alternatives (e.g., Zulip or Matrix) would be technically
+  possible but socially risky, as many users may not follow or adapt easily.
+- ❌ Bad, limited support for open standards and federation restricts long-term
+  resilience.

docs/decisions/0007-pnpm.md

@@ -1 +1,39 @@
 # Use `pnpm` as our frontend dependency manager
+
+## Context and Problem Statement
+
+In our frontend projects, we need a reliable, efficient, and developer-friendly package
+manager for JavaScript/TypeScript dependencies.
+
+Key concerns include:
+
+- Speed and disk usage efficiency.
+- Deterministic and reproducible installs.
+- Compatibility with existing tools and workflows.
+- Minimizing node_modules bloat and install conflicts.
+
+## Considered Options
+
+- npm
+- yarn (classic or berry)
+- pnpm
+
+Options not considered: package managers used by runtimes other than NodeJS,
+such as Deno or Bun.
+
+## Decision Outcome
+
+- pnpm was selected as our default package manager due to its performance benefits,
+  disk space efficiency, and strict dependency resolution.
+- Compared to npm and yarn, pnpm uses a content-addressable storage system and hard
+  links to avoid duplication.
+- It also enforces more consistent dependency resolution, helping to catch errors
+  early in development.
+
+## Consequences
+
+- ✅ Fast install speeds, especially in CI environments.
+- ✅ Reduced disk usage thanks to shared dependency storage.
+- ✅ More deterministic builds with stricter dependency isolation.
+- ❌ Less familiar for some contributors compared to npm/yarn.
+- ❌ Occasional compatibility issues with legacy packages expecting a flat node_modules.

docs/decisions/0008-uv.md

@@ -1 +1,37 @@
 # Use `uv` as our backend dependency manager
+
+## Context and Problem Statement
+
+We need a modern Python package management tool that is:
+
+- Much faster than pip and pip-tools.
+- Able to handle lock files and virtual environments cleanly.
+- Better at resolving complex dependency trees reproducibly.
+
+## Considered Options
+
+- pip + virtualenv
+- pipenv
+- poetry
+- pdm
+- uv
+
+## Decision Outcome
+
+uv (by Astral) was selected for its speed, strict reproducibility,
+and modern tooling ergonomics.
+
+It significantly improves dependency resolution times and offers a
+seamless developer experience.
+
+Unlike traditional tools like pip, uv performs rapid dependency resolution and installs,
+while producing lock files that ensure consistency across platforms and environments.
+
+## Consequences
+
+- ✅ Extremely fast dependency resolution and installation (Rust based).
+- ✅ Modern, opinionated tooling with strong defaults.
+- ✅ Simplifies management of virtual environments and lock files.
+- ✅ Support for workspace packages, to allow for easier monorepo setups.
+- ❌ Less mature ecosystem and community support (as of 2025, growing fast!).
+- ❌ Requires team familiarity with new workflows.

docs/decisions/0009-load-testing.md

@@ -0,0 +1,41 @@
+# Use k6 or Oha for application load testing
+
+## Context and Problem Statement
+
+We need lightweight tools to simulate real-world traffic for
+performance testing of our APIs and services.
+
+Requirements include:
+
+- Easy setup and usage.
+- Ability to run both quick, one-off benchmarks and complex scripted scenarios.
+- CI/CD integration capability.
+
+## Considered Options
+
+- Apache JMeter
+- Locust
+- k6
+- oha
+- wrk
+
+## Decision Outcome
+
+We adopted a hybrid approach using oha for simple benchmarks and
+k6 for more advanced, scripted load tests.
+
+oha is fast and easy to use for quick HTTP benchmarking (similar to wrk,
+but with a simpler interface and better reporting).
+
+k6 is a developer-centric load testing tool that supports JavaScript
+scripting for complex test scenarios, integrates well with CI pipelines,
+and produces meaningful metrics.
+
+## Consequences
+
+- ✅ oha gives us a fast, no-frills tool to test latency and throughput of HTTP endpoints.
+- ✅ k6 allows scripting advanced load test scenarios using JavaScript, including
+  auth flows and dynamic data.
+- ✅ Both tools are CLI-friendly and CI-compatible.
+- ❌ Splitting tools means learning two interfaces.
+- ❌ k6 can be resource-intensive during heavy test scenarios.

docs/techdoc/README.md

@@ -80,7 +80,7 @@ documentation is as follows:
 - Features: A breakdown of each integral part of the product, their
   functionality and purpose
 - Benefits: How the features give users an edge over other similar
-  products. In other words, what’s in it for the user.
+  products. In other words, what's in it for the user.
 - Usage: A step by step process of how to use the product
 - Support / Frequently Asked Questions (about the product)
 - License
@@ -93,7 +93,7 @@ these are what I believe to be some of the most important.
 #### 2. Structure for Project Documentation
 
 Project documentation is the process of recording the key project
-details that are needed to implement a project. It’s like a roadmap of
+details that are needed to implement a project. It's like a roadmap of
 what the project is and all necessary information about what it
 entails. Main structural components are in the following order:
 
@@ -112,7 +112,7 @@ entails. Main structural components are in the following order:
 
 System documentation is an all-encompassing record of details of a
 full working system. It is very similar to the structure of product
-documentation but it’s usually on a wider scale. It may even include
+documentation but it's usually on a wider scale. It may even include
 some forms of product and process documentation within it. In addition
 to the structure of product documentation above, other key components
 it might include are: **architecture design**, **program source code**
@@ -146,7 +146,7 @@ added to and built upon.
    negates confusion for readers / users and just simplifies things.
 
 2. **Important features should be put in bold**. For example “select
-   from map” and ‘’ODK Collect” can be easily overlooked by readers if
+   from map” and 'ODK Collect' can be easily overlooked by readers if
    they aren't highlighted, even though they are important features.
 
 3. **Generally simplifying words and phrases**. This makes
@@ -156,17 +156,17 @@ added to and built upon.
    “ODK incorporates a new functionality” can become “ODK has brought in a new feature”.
 
    “Field Mappers select (or are allocated) individual tasks within a
-   project’s AOI” could be changed to “Field Mappers choose or are
-   given tasks that are part of a project’s Areas Of Interest.”
+   project's AOI” could be changed to “Field Mappers choose or are
+   given tasks that are part of a project's Areas Of Interest.”
 
 4. **Avoid long paragraphs**. Short paragraphs that pass a clear
    message are less clumsy and flustering for readers. Breaking down
    topics into little, easy to understand chunks, is more user
    friendly.
 
 5. **Maintain a positive tone in the writing.**. Keep the text
-   positive and informative. Avoid words like ‘obviously’ and
-   ‘basically’, that may be interpreted as demeaning or
+   positive and informative. Avoid words like 'obviously' and
+   'basically', that may be interpreted as demeaning or
    condescending. Do not expect readers to have a certain amount of
    knowledge on specific aspects, break down everything that needs to
    be broken down.