
<br />

Short answer: Explain the what, and why, but not how; cover the edge cases; break or adapt templates where necessary.

![User Stories](how-to-write-effective-user-stories/UserStories.png)

As an experienced user story writer, let me tell you that it’s completely okay to break away from the user story mold wherever it’s needed. The “As a user(or persona), I [want to], [so that]” [template](https://www.atlassian.com/agile/project-management/user-stories) is a great starting point for people new to the user stories game. However, there are places where this completely falls flat.

Here’s why: Sometimes users describe the app you’ve developed as “clunky” and “not slick”. However, writing a user story that states “As a user I would like the app to be more responsive” would not cut it for an engineering team trying to fix the performance of an app (which could involve improving API response times, frame rate drops, or layout shifts).

> **In a world deluged by irrelevant information, clarity is power.**
– [Yuval Noah Hariri, 21 Lessons for the 21st Century](https://www.goodreads.com/quotes/9455105-in-a-world-deluged-by-irrelevant-information-clarity-is-power)

The point of the user story does still hold: empathise with the end user. The template is one way–a standardised way–to get there, but typically doesn’t fit well with the engineering/design team’s needs, and often misses the point, in favour of the process.
In this post, I want to walk through the core idea behind user stories, that should help you to write your own stories more effectively by cutting out the noise.

### What, and Why, not How

Focus your user stories on what you want done–changed, added, fixed. Some examples:

- The sign up process needs to implement a second factor authentication using phone numbers since our users don’t use emails very often.
- Our transactions list tab needs to respond faster, ideally showing up-to-date data that was fetched in the background.
- Add support for exporting reports in an Excel format.

Of course, this is only a part of the whole story–we will build up to the rest in the coming sections. However, so far, this is an accurate (although simplified for the sake of brevity) capture of the way a story might communicate what needs to be built–without any of the noise.
Based on your context and the way your team likes functioning, you would go a bit more detailed on these fronts, explaining the functionality a bit further. For example, you could elaborate the third example in the following way: “Add support for exporting reports in an Excel format. Users are okay to wait and receive these reports via email. However, they expect a granular selection of fields in their reports that map into columns in the exported Excel”.

Next, the “why” adds important context to the change you want done. Let’s evolve the previous examples:

- The sign up process needs [...] emails very often. This is an imperative for further sales to happen to corporate customers where a second factor of authentication is mandatory for all software used within the organisation.
- Our transactions list tab [...] background. Analytics data gathered in the app, and on the website indicate that users, upon completing a transaction, look at the transactions tab 78% of the time in order to confirm a successful transaction.
- Add support for exporting [...] in Excel. This need comes from customers’ tracking and analytics teams that prefer to look at their raw data so that they can fit it into their existing reporting workflows.

With this added context, it becomes immediately clear to any reader within your team that the first story is the most important since it is actively blocking sales to new customers, whereas the importance of the other two are up for debate.

> **I would have written a shorter letter, but I did not have the time.**
– [Blaise Pascal, Lettres Provinciales](https://en.wikipedia.org/wiki/Lettres_provinciales#Other).

#### Forget the How

Now that you have the two main items down, let’s focus on one that you shouldn’t worry about (or even write). That is: How do you go about achieving the change? The biggest reason why is, while conceiving the feature, you can’t limit your thinking by what state the designs or codebases are in.

This isn’t to say those aren’t practical considerations–they absolutely are. However, that can come as push back from those who need to build out the change in question. This is where it’s important to stick to user empathy–the user doesn’t care about technical debt, or internal priorities etc. They care about the change–no holds barred. So, at least when it’s your turn to document it, ensure that your imagination isn’t constrained by practical limitations. What gets built will involve those practical limitations due to constraints of money, time, availability and factors (possibly) out of your control.

Another reason to forget the how: The development/design team might anyway be better suited to navigate the best way to build the change in question.

### The Devil is in the Details

Now that the basics of What, Why, but not How, are out of the way, there’s another critical element to touch upon–sort of the icing on the cake–the details, especially around the edge cases. Let’s explore our original examples with some questions one might want to explore:

- Two factor authentication is great, but how does a user who has lost their password or phone get it back? How do existing users get migrated into the new system? Is this opt-in for a certain period after which it’s mandatory? Should the cost of sending SMSes result in an increased billing to customers who opt into this system?
- If the background fetch of data fails, but an older copy of transactions is present on the screen, is it okay to indicate to the user that the data they are seeing is not up to date and may need a refresh of some sort? Or should the screen not even show the original data?
- What are the limits that should be imposed on the Excel export? What if the data is of the order of hundreds of thousands or more? Should the files sent to the user be split up instead?

Answers to such questions may not come to you right off the bat. But without them, it’s impossible for any team to start conceiving of solutions to the change you are proposing. Further, your team would have specific questions to think about compared to another, that can only be learned by experience. For example, an e-commerce app would really care about SEO optimization so each change might need considerations there, versus an app that deals with transactions would have a much higher emphasis on API response times. 

### Engage and Evolve

This post is mostly to highlight the core of what should be covered–with some simplistic examples to anchor the explanation. Some things will work for you and your team and others won’t–even within the same team, as your team scales and other teams such as QA, analytics, and such get involved. The whole point of agile is not to settle into a template, and instead change as change presents itself.

Have fun out there.

![Have Fun](how-to-write-effective-user-stories/HaveFun.png)


Explain the what, and why, but not how; cover the edge cases; break or adapt templates where necessary.

How to Write Effective User Stories


## Introduction

PostgreSQL’s query planner is one of its greatest strengths, but it can also be a source of mystery and frustration when your queries suddenly slow down and indexes seem to stop working.  
Often, the culprit isn’t a missing or broken index, but **outdated statistics**.

In this post, I’ll walk you through:

- How PostgreSQL’s statistics system works
- How the query planner makes decisions using those stats
- Why and when statistics become outdated
- How to reproduce, detect, and fix this issue yourself with real SQL examples

## 1. What Are PostgreSQL Statistics?

PostgreSQL tracks detailed statistics for every table and column, including:

- Number of live tuples (`n_live_tup`)
- Most common values and their frequencies (`most_common_vals`, `most_common_freqs`)
- Histograms (distribution buckets for the rest of the data)
- Null fraction, number of distinct values, and more

These statistics are maintained in the system catalogs:

- **`pg_stats`**

The **query planner** relies on these to estimate how many rows will match each filter in a query.

## 2. How the Query Planner Uses Statistics

### Understanding `pg_stats`

The planner’s decision to use a sequential scan, an index scan, or a bitmap index scan is *entirely dependent* on up-to-date column statistics.

#### What’s inside `pg_stats`?

- **most_common_vals**: The most frequent values in the column.
- **most_common_freqs**: The frequency (as a decimal) for each value in `most_common_vals`.
- **histogram_bounds**: Buckets that describe the spread of remaining values.
- **null_frac**: Fraction of NULL values in the column.
- **n_distinct**: Number of distinct values seen in the column.

#### Example

Suppose you have a table with status values, mostly `'active'`, some `'inactive'`:

```sql
SELECT attname, most_common_vals, most_common_freqs, null_frac, n_distinct
FROM pg_stats
WHERE tablename = 'useractivity';
```

Sample output:

| attname | most_common_vals   | most_common_freqs    | null_frac | n_distinct |
|---------|--------------------|----------------------|-----------|------------|
| status  | \{active,inactive\}  | \{0.9527,0.0473\}      |    0      |     2      |

**Interpretation:**

- ~95% of rows have `'active'`, ~5% have `'inactive'`, and there are 2 possible status values.

### How the Planner Uses These Stats to Pick a Scan Type

- **If your filter matches very few rows** (e.g., `status = 'inactive'`), the planner prefers an index scan.
- **If your filter matches most rows** (e.g., `status = 'active'`), the planner prefers a sequential scan.

### What if the Stats Are Outdated?

If you *change* your data—say, update all rows to `'inactive'`, but do **not** run `ANALYZE`, the planner will continue to make its decisions based on old, now-wrong numbers.  
This leads to bad query plans and poor performance.


## 3. When and How Are Statistics Updated?

**Postgres does NOT update statistics after every data change.**  
Stats are refreshed in only two ways:

- When you run `ANALYZE` (or `VACUUM ANALYZE`) manually.
- When **autovacuum**’s **autoanalyze** process triggers—based on thresholds.

### How Is the Autoanalyze Threshold Calculated?

Autoanalyze will only run after the following number of rows have been changed (inserted, updated, or deleted):

```
autovacuumAnalyzeThreshold + (autovacuumAnalyzeScaleFactor × number_of_rows_in_table)
```

**Default values:**

- `autovacuumAnalyzeThreshold = 50`
- `autovacuumAnalyzeScaleFactor = 0.1` (i.e., 10%)

#### Example Calculation

If your table has 100,000 rows:

- `0.1 × 100,000 = 10,000`
- Add the threshold: `10,000 + 50 = 10,050`

So **autoanalyze will not run until you have at least 10,051 row changes**.  
If you only do 9,999 changes, statistics will remain stale until more changes are made or you run `ANALYZE` manually.

#### See These Settings in Your DB

```sql
SHOW autovacuum_analyze_threshold;
SHOW autovacuum_analyze_scale_factor;
```

## 4. Deep Dive: When Indexes “Fail”

Let’s reproduce the problem from scratch:

### Step 1: Create Table and Index

```sql
CREATE TABLE useractivity (
    id serial PRIMARY KEY,
    userid integer NOT NULL,
    status varchar(20) NOT NULL
);

CREATE INDEX idxuseractivitystatus ON useractivity(status);
```

### Step 2: Insert Data (skewed)

```sql
-- 100,000 inactive users
INSERT INTO useractivity (userid, status)
SELECT generate_series(1, 100000), 'inactive';

-- 1,000 active users
INSERT INTO useractivity (userid, status)
SELECT generate_series(100001, 101000), 'active';

ANALYZE useractivity;
```

### Step 3: See Current Stats

```sql
SELECT attname, most_common_vals, most_common_freqs, null_frac, n_distinct
FROM pg_stats
WHERE tablename = 'useractivity';
```

Sample output:

| attname | most_common_vals   | most_common_freqs    | null_frac | n_distinct |
|---------|--------------------|----------------------|-----------|------------|
| status  | \{inactive,active\}  | \{0.9527,0.0473\}      |    0      |     2      |

### Step 4: Query Plans

```sql
EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM useractivity WHERE status = 'inactive';
EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM useractivity WHERE status = 'active';
```

You’ll likely see:
- `'active'`: Index Scan or Bitmap Index Scan (planner expects a small fraction of rows)
- `'inactive'`: Seq Scan (planner expects almost all rows to match)

### Step 5: Bulk Data Change Without Analyze

```sql
-- Make everyone active
UPDATE useractivity SET status = 'active';

-- Add 10,000 inactive users
INSERT INTO useractivity (userid, status)
SELECT generate_series(105001, 115000), 'inactive';

-- Do NOT run ANALYZE yet!
```

### Step 6: See What Planner Does With Stale Stats

```sql
EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM useractivity WHERE status = 'inactive';
```

You may find the planner still does an sequential scan based on the old stats even though now there are less `'inactive'` rows. This means that the query could be much slower than it should be.

### Step 7: Refresh Stats and Observe the Change

```sql
ANALYZE useractivity;

EXPLAIN (ANALYZE, BUFFERS) SELECT * FROM useractivity WHERE status = 'inactive';
```

Now that the statistics are fresh, the planner realizes 'inactive' is actually rare, and it will likely switch to using an Index Scan for this query.


## 5. How to Fix and Prevent Bad Plans

- Always run `ANALYZE` after big updates/inserts/deletes.
- Monitor last stats update:

    ```sql
    SELECT relname, last_analyze, last_autoanalyze FROM pg_stat_user_tables WHERE relname = 'useractivity';
    ```
- Lower the threshold for critical tables:

    ```sql
    ALTER TABLE useractivity SET (autovacuum_analyze_scale_factor = 0.01);
    ```

## 6. Tuning Autovacuum and Analyze

- See your global settings:

    ```sql
    SHOW autovacuum_analyze_scale_factor;
    SHOW autovacuum_analyze_threshold;
    ```

- Set lower thresholds on a per-table basis with `ALTER TABLE ... SET (...)`.

## 7. Conclusion

Indexes themselves rarely break in PostgreSQL, what fails is the planner’s ability to recognize when to use them if statistics are outdated. By keeping your table statistics current, you empower PostgreSQL to make optimal decisions, ensuring your queries are fast and your indexes deliver the performance you expect.


PostgreSQL’s powerful query planner relies heavily on up-to-date table and column statistics to decide whether to use indexes or full-table scans for your queries. When these statistics become outdated—often after bulk updates or large data changes—Postgres can start making bad decisions, causing indexes to be ignored and query performance to drop sharply.

Why PostgreSQL Indexes Fail - The Role of Outdated Statistics


## Before We Begin

> **Note:** The CLI tools discussed in this post are primarily tailored for macOS and Linux users. While some of these tools may work on Windows, others might not be available or require additional setup to function properly.

Before we dive in, let’s talk about terminal emulators. Your command line tools are only as good as the terminal they run in. While the default terminal works fine for most, switching to a modern emulator can really level up your experience. Some popular options include:

- [Alacritty](https://alacritty.org/) (macOS, Windows, Linux)
- [Kitty](https://sw.kovidgoyal.net/kitty/) (macOS, Linux)
- [Wezterm](https://wezterm.org/) (macOS, Windows, Linux)
- [Ghostty](https://ghostty.org/) (macOS, Linux)
- [iTerm2](https://iterm2.com/index.html) (macOS)
- [Terminal](https://github.com/microsoft/terminal) (Windows: good [WSL](https://learn.microsoft.com/en-us/windows/wsl/about) support)

I personally use Kitty for its rich feature set and stability. What makes it feature rich are features such as:

- Quick access terminal (like Quake): [Kitty Quick Access](https://sw.kovidgoyal.net/kitty/kittens/quick-access-terminal/)
- Cursor trail: [Kitty Cursor Trail](https://sw.kovidgoyal.net/kitty/conf/#opt-kitty.cursor_trail)
- Plugins (“Kittens”): [Kitty Kittens](https://sw.kovidgoyal.net/kitty/kittens_intro/)
- Integrations: [Kitty Integrations](https://sw.kovidgoyal.net/kitty/integrations/)

If you spend a significant amount of time in your terminal, even small enhancements can greatly improve your experience.

## CLI Tools

### Shell

The second most important thing in a CLI environment is the shell you’re working with. Bash is the default for a reason: it’s reliable and gets the job done. But once you start exploring, you’ll find other shells that offer features you might not want to live without.

The most common alternative is [zsh](https://www.zsh.org/), especially when paired with the [Oh-My-Zsh](https://ohmyz.sh/) plugin manager. With this setup, you get things like [Powerlevel prompts](https://github.com/romkatv/powerlevel10k), syntax highlighting, and auto-suggestions. These might sound like small additions, but once you get used to them, it’s hard to go back.

That said, configuring Oh-My-Zsh can get a bit complicated, especially when you need to manually clone repositories for some plugins to work. If you want something simpler, [Antidote](https://antidote.sh/) is a solid replacement. It supports Oh-My-Zsh plugins, so you can switch over at your own pace without losing your setup.

Personally, I prefer [Fish](https://fishshell.com/). Out of the box, Fish gives you auto-suggestions and syntax highlighting, and I’ve found its configuration much easier to understand, especially if you’re just starting out. Fish has also become popular enough that most tools now provide completion scripts for it. If you want to extend Fish, [fisher](https://github.com/jorgebucaran/fisher) is a great plugin manager.

The only real downside to Fish is that it’s not POSIX compliant, so a few commands don’t work the same way. For example:

- `sudo !!` won’t repeat the last command with sudo.
- You can’t start ssh-agent with `eval $(ssh-agent)`.

But for most day-to-day tasks, Fish is a pleasure to use, and the trade-offs are pretty minor.

### Zoxide

One of the major pain points of using terminals is navigating directories. For example, if I have a directory like `~/.config/kitty/`, the usual way to get there is:

```bash
cd ~/.config/kitty/
```

This works, but when you’re working on a large project or jumping between lots of folders, it quickly gets tedious. That’s where [zoxide](https://github.com/ajeetdsouza/zoxide) comes in. It gives you a smarter way to move around: zoxide remembers the directories you visit, so next time, you can just type a part of the name and jump straight there. For instance:

```bash
z kitty
```

That’s it. No need to type the full path every time. It might seem like a small thing, but it really does make a difference when you’re moving around your filesystem all day. Instead of thinking about the absolute path, you just give it a hint, and you’re there.

If you want to take this idea even further, there’s another tool called [broot](https://github.com/Canop/broot). It builds on the same concept, but changes the way you think about navigating files in the terminal. I wouldn’t call it as beginner-friendly as zoxide, but it’s worth a look if you want to experiment.

### Tmux

[Tmux](https://github.com/tmux/tmux) is what’s called a terminal multiplexer, which basically means you can run several programs in a single terminal window—either by splitting the window into panes or by using tabs. While most modern terminal emulators already let you split windows or open tabs, the real strength of tmux is its ability to keep your sessions alive, no matter what happens to your connection.

I can’t count how many times I’ve been working over SSH, only to have the connection drop in the middle of something important. Or maybe I accidentally close the terminal window and lose all my work. With tmux, you don’t have to worry about that. You can detach from a session at any time, close your terminal, and then come back later and pick up exactly where you left off. It’s saved me more than once from losing a half-finished script or a long-running process.

Recently, I’ve started using [Zellij](https://zellij.dev) because it offers a better experience out of the box, but tmux is so widely used that you’ll find it preinstalled on most remote machines. That’s why it’s worth getting comfortable with tools like tmux, nano, and vim—sometimes, you just need to work with what’s already there.

If you spend any time working on remote servers, or you want a bit more control over your terminal sessions, tmux is one of those tools that’s good to have in your toolkit.

### Mise

When I first thought about writing this blog, the obvious choice for managing runtime versions that came to mind was [asdf](https://asdf-vm.com). It’s been around for a while and does the job well enough. However, after using [mise](https://mise.jdx.dev/) for the past couple of weeks, I’ve found it to be a real gamechanger in my workflow.

One thing that always bugged me with asdf is the number of first-party plugins you get out of the box. If you want to manage runtimes for other languages, you end up installing community plugins. It’s not a huge deal, but the less configuration I have to worry about, the more I can focus on what I actually want to do. At the end of the day, I just need a tool that can manage different versions of Node or Java across different projects, and mise does that right out of the box—and then some.

Mise not only supports everything asdf does (thanks to its asdf backend), but also has [support for other backends](https://mise.jdx.dev/dev-tools/backends/) like cargo, dotnet, and npm. There’s no extra setup required for these; they just work.

But that’s not where it ends. Mise also lets you manage [environment variables](https://mise.jdx.dev/environments/), [secrets](https://mise.jdx.dev/environments/secrets.html), and [hooks](https://mise.jdx.dev/hooks.html) directly.

One feature I find myself using a lot is tasks. You can define custom tasks in your `mise.toml` file and run them from anywhere in your project. For example, to set up a build task:

```toml
[tasks.build]
description = "Build project"
run = "npm run build"
```

And then you just run:

```bash
mise run build
```

Tasks are a powerful feature, and honestly, they deserve their own blog post. If you’re curious, you can read more about them [here](https://mise.jdx.dev/tasks/).

What I really appreciate is that you don’t have to be in the root of your project to run a task. If I’m buried somewhere in `foo/bar/baz`, I can still run `mise run build` and it’ll execute from the project root. It’s a small thing, but it takes away the mental overhead of remembering where you need to be to run a command.

You can also commit your `mise.toml` to your repository, so everyone on your team has the same setup without extra hassle.

### Chezmoi

Even if you try to keep your setup simple, there’s always some configuration you can’t avoid. Managing all your dotfiles and keeping them in sync across different machines can quickly turn into a headache. That’s where [chezmoi](https://www.chezmoi.io/) comes in—it helps you centralize and version control your configuration files, so you don’t have to worry about missing settings or manual copy-pasting.

Getting started is straightforward:

```bash
chezmoi init                             # Initializes a local git repo to track your config files
chezmoi add ~/.config/fish/config.fish   # Add files you want to track
chezmoi edit ~/.config/fish/config.fish  # Edit files using your $EDITOR
chezmoi apply -v                         # Apply your changes
```

When you’re setting up a new machine, you just need to run:

```bash
chezmoi init https://github.com/$GITHUB_USERNAME/dotfiles.git
chezmoi apply -v
```

That’s it—your configuration is now set up just the way you like it.

Chezmoi also comes with a bunch of features that make managing your setup even easier:

- [Password manager integration](https://www.chezmoi.io/user-guide/password-managers/) for keeping secrets safe
- [File encryption](https://www.chezmoi.io/user-guide/encryption/) for sensitive configs
- [Declarative package installs](https://www.chezmoi.io/user-guide/advanced/install-packages-declaratively/) so you can automate more of your environment

If you want to spend less time fiddling with configs and more time actually working, chezmoi is worth a look.

## Conclusion

There’s no shortage of CLI tools out there, and finding the right ones can make your daily workflow a lot smoother. The tools I’ve mentioned here have saved me time and frustration, and I hope they’ll do the same for you. Of course, everyone’s setup is a little different, so don’t hesitate to experiment and see what fits best with your way of working.

If you have a favorite CLI tool or a tip that’s made your life easier, feel free to share it—I’m always looking to learn something new.

Happy tinkering!


A practical look at terminal emulators, shells, and a handful of CLI tools that can help streamline your workflow, save time, and reduce friction in your daily development tasks.


Some CLI Tools That Make Life Easier


## What is Locust?

[Locust](https://locust.io/) is a scalable, user-friendly load-testing tool designed for testing APIs, websites, or any system that can handle HTTP requests. Unlike traditional performance testing tools, Locust uses Python to define user behavior, making it flexible and easy to integrate with existing workflows.

### Why Use Locust?

- Python-Based Scripting: Write test scripts in Python, giving you complete control over user behavior.
- Distributed Load Testing: Scale tests across multiple machines for testing large systems.
- Web-Based UI: Monitor test results in real time through a web interface.
- Extensibility: Easily integrates with other tools or systems using Python libraries.

### Setting Up Locust

To get started with Locust, follow these steps:

1. Install Locust using pip:
```
pip install locust
```
2. To verify the installation, run the following command:
```
locust -V
```
This command should display the installed version of Locust.

## Preparing Data For Testing

Effective performance testing often requires bulk data to simulate realistic scenarios, such as testing APIs that query databases or interact with application components. If your use case involves a database, ensure sufficient test data is prepared.

### Generating Test Data

Create scripts to generate bulk records in a format suitable for your application, such as CSV. There are python libraries like [Faker](https://faker.readthedocs.io/en/master/) that can be used to generate fake data. For random numeric data, one of the most commonly used module is [random](https://docs.python.org/3/library/random.html).

### Importing Test Data

If the test requires data to be loaded into a database:

1. Write a script to import the generated CSV records into the relevant database tables.
2. Test the import script to verify that the data loads correctly.

## Writing Locust Test Scripts

A Locust test script defines user behavior using Python code. For instance, if you’re testing an API, the script can simulate multiple users sending requests.

### Basic Structure of a Locust Test Script

A typical Locust script includes:

- User Behavior: Define tasks that represent user actions.
- Load Simulation: Specify the number of users and spawn rate.
- Data Handling: Include logic to read test data if required.

Here’s a simple example:

```python
from locust import HttpUser, task, between

class MyUser(HttpUser):
    wait_time = between(1, 3)  # Simulates wait time between tasks

    @task
    def perform_task(self):
        self.client.get("/api/endpoint")  # Replace with your endpoint
```

### Handling Bulk Data

When performance testing involves large volumes of data, it’s essential to simulate realistic scenarios by loading bulk data into your test scripts. 

For example, if you are testing an API that processes user records, you may need a large set of user data to stress-test the system.

Let us consider you’re testing a user registration system. To do so effectively, you would need to generate a large number of user records and simulate requests that process this data.
Assuming that we have a CSV file containing user records, when simulating the registration of users, you would read the CSV file and use the data in your HTTP requests.

```python
import csv
from locust import HttpUser, task, between

class UserRegistrationTest(HttpUser):
    wait_time = between(1, 3)

    def on_start(self):
        self.users = []
        with open('users.csv', newline='') as csvfile:
            reader = csv.DictReader(csvfile)
            for row in reader:
                self.users.append(row)

    @task
    def register_user(self):
        user = self.users.pop()
        self.client.post("/register", json={
            "username": user['username'],
            "email": user['email'],
            "password": user['password'],
        })
```

In this example, the `on_start` method reads the CSV and stores the user data in a list. The register_user task simulates the registration process by sending a POST request with user data.

## Running Locust Tests

### Executing the Test Script

Once your Locust script is ready, you can execute it as follows:

1. Navigate to the directory containing the script.
2. Run Locust with the script file:
```
locust -f your_locust_script.py
```
3. Open the Locust web interface by visiting http://localhost:8089 in your browser.

### Configuring Test Parameters

In the Locust web interface:

- Number of Users: Set the total number of peak concurrent users.
- Spawn Rate: Define how many users start per second.
- Host: Specify the URL of the API endpoint to test.
- Run Time: Specify the duration of the test.

![Locust Configuration](performance-testing-apis-with-locust/ConfiguringTestParameters.png)

Click “Start” to begin the test and monitor the results, such as request rates, response times, and failure counts, in real-time.

## Understanding Locust Reports

Locust provides detailed reports that help identify system bottlenecks. Here’s how to interpret them:

### Request Statistics

This section gives an overview of each API endpoint’s performance:

| Type | Name           | # Requests | # Fails | Median (ms) | Average (ms) | Min (ms) | Max (ms) | Current RPS |
|------|----------------|------------|---------|-------------|--------------|----------|----------|-------------|
| POST | /api/endpoint  | 500        | 0       | 55          | 63.44        | 39       | 445      | 0.2         |


Key columns include:
- Requests: Total number of requests made to the endpoint.
- Median/Average (ms): Median and average response times.
- Current RPS: Requests per second at the time of reporting.

### Response Time Statistics

This section provides response time percentiles:

| Method | Name          | 50%ile (ms) | 90%ile (ms) | 99%ile (ms) | 100%ile (ms) |
|--------|---------------|-------------|-------------|-------------|--------------|
| POST   | /api/endpoint | 51          | 63          | 88          | 420          |

Interpretation:
- Percentiles give insights into response times experienced by most users (e.g., 90% of requests are completed within 63 ms).
- High 99th or 100th percentiles may indicate outliers or bottlenecks.

### Failures Statistics

Failures are summarized in a dedicated section:

| Failures | Method | Name          | Message       |
|----------|--------|---------------|---------------|
| 3        | POST   | /api/endpoint | Timeout Error |

Investigate errors to identify system issues, such as timeouts or bad requests.

### Charts

Locust generates interactive charts for:

- Requests per second: Tracks traffic patterns over time.
- Response times: Visualizes latency trends in milliseconds.
- Number of users: Shows the load profile during testing.

### Final Ratios

Summarizes the traffic distribution among tasks or classes.

## Best Practices for Using Locust

- Prepare Adequate Data: Ensure test data matches real-world scenarios. Generate bulk data as needed. For example, if you are testing an e-commerce platform, simulate different types of product data (e.g., electronics, clothing, books) and user actions/tasks such as browsing, searching, applying product filters, adding to cart, and checking out.
- Modular Scripts: Keep your test scripts modular to reuse for different endpoints or workflows.
- Monitor System Resources: Observe your system’s CPU, memory, and network usage during tests to identify bottlenecks.
- Iterate and Refine: Run multiple test cycles, adjusting parameters and scenarios to cover edge cases.

## Conclusion

Locust is a versatile tool for performance testing that can simulate user behavior, measure system capabilities, and uncover potential bottlenecks. By preparing appropriate test data and crafting detailed Locust scripts, you can effectively validate your system’s performance under load. Whether you’re testing APIs, databases, or workflows, Locust makes the process streamlined and efficient.


Performance testing is essential to ensure your system performs reliably under real-world conditions. This blog introduces Locust, a powerful and scalable load-testing framework, guiding you through its setup, data preparation, and script writing. Learn how to handle bulk test data, analyze Locust’s detailed reports, and use its intuitive interface to identify performance bottlenecks and make optimizations for a more reliable system.

Performance Testing APIs with Locust: A Practical Guide for Developers


## What is a Product Backlog?

As a Scrum master, I would say: *Product Backlog is an emergent, ordered list of what is needed to improve the product*. However, after working on multiple projects and watching this list closely I have realised that a product backlog when poorly managed is often the first visible symptom of a struggling project. It’s the repository of forgotten tasks, unclear priorities, and abandoned ideas. In such scenarios, team members are often firefighting, unsure of where their efforts are most needed. 

## The Hidden Cost of a Messy Backlog

When the backlog is a tangle of outdated tickets, vague requirements, and misaligned priorities, the whole project suffers. The team wastes time deciphering what’s relevant, stakeholders lose trust in timelines, and critical features can slip through the cracks.
We’ve seen this firsthand. In one project, seemingly minor functionalities were marked as complete in the backlog but were missing in the build. The issue wasn’t discovered until late in the timeline, creating last-minute pressure and risking the release. This type of oversight isn’t a one-off problem; it’s a symptom of an unmanaged backlog. And the cure always starts with cleaning.

### Why Backlog Cleaning is a Must

- **It Resets the Compass**: For a project losing direction, backlog cleaning is like recalibrating the compass. It ensures team focuses on tasks that align with the priorities and project goals rather than being scattered in every direction. 
- **It Builds Clarity**: An unmanaged backlog breeds confusion—tasks are unclear, duplicates go unnoticed, and outdated items linger. Cleaning it ensures every ticket is *relevant*, *detailed*, and *actionable— has a clear acceptance criteria*. 
- **It Prevents Bottlenecks**: A messy backlog doesn’t just delay work—it creates bottlenecks. When tasks aren’t well-organized, sprint planning turns into a ***guessing game***, and the team spends more time discussing issues than solving them.
- **It Revives Team Morale**: *No one likes working in chaos*. A cluttered backlog adds to the team’s stress and drains morale. Cleaning it brings structure and restores a sense of control, helping the team feel confident and motivated.

## Backlog Cleaning: The Foundation for Recovery

Cleaning the backlog isn't just about deleting outdated tasks — its about restoring focus and setting the team up for success. Before diving into the backlog, I make sure to align with the project lead or stakeholders to understand the expectations for the immediate deliverable. Instead of overloading tasks with multiple labels or tags, I prefer to use them in just two specific cases:
- Someday: Not an immediate priority, but a good-to-have for the future.
- Needs Clarity: When the requirements, scope, expectations, or acceptance criteria are unclear.
And about those not in scope anymore? Just close the tickets and get rid of them from the list!
<br/>

**Two Essential Practices to Start from Day One**:
- Refine Task Description/Scope: For any task to be actionable, it needs to meet the Definition of Ready: clear requirements, defined acceptance criteria, and an estimate. You revisit and refine stories with the team, ensuring there’s no ambiguity.
- Set Up a Feedback Loop: A cleaned backlog won’t stay clean on its own. Regular grooming sessions ensure new tasks align with the project’s goals and prevent clutter from building up again. 

## Takeaways for Project Teams

Backlog cleaning might feel tedious, but it’s one of the most impactful steps you can take to rescue a struggling project. Here’s how to make it work for you:
- **Start with the Basics**: Remove outdated tickets, merge duplicates, and archive anything that no longer aligns with project goals.
- **Reassess Priorities**: Work with stakeholders to identify what’s critical and what can wait.
- **Clarify Requirements**: Ensure every task in the backlog has clear acceptance criteria, so the team knows exactly what’s expected.
- **Involve the Team**: Backlog cleaning isn’t a solo activity. Involve developers, designers, and key stakeholders to ensure no detail is overlooked.
- **Make it a Habit**: Cleaning the backlog shouldn’t be a one-time event. Regular backlog grooming ensures you stay on track and avoid future chaos.

## A Clean Backlog = A Clear Path Forward

Backlog cleaning isn’t just about tidying up; it’s about setting the project up for success. It transforms a chaotic, unfocused effort into one with *clarity*, *direction*, *purpose* & *DELIVERY!*


Backlog grooming is an essential practice for restoring clarity and direction to struggling projects. A poorly managed backlog— filled with outdated tasks, unclear priorities, and abandoned ideas— causes inefficiencies, delays, and reduced morale. Cleaning it ensures alignment with project goals, creates actionable tasks, prevents bottlenecks, and boosts team confidence. By prioritizing regular backlog grooming and focusing on clarity, teams can transform chaos into structured progress, setting the foundation for successful delivery.

Why Backlog Cleaning Isn’t Optional: Lessons for Project Teams


## Introducing Contact Card Generator

In today’s digital age, traditional paper business cards persist despite their environmental impact and tendency to get lost or discarded. Here’s a simpler, greener solution.

Transform your contact information into a scannable QR code instantly. No apps or subscriptions required!

### Why QR Codes?

While phones offer built-in contact sharing [features](https://support.apple.com/en-in/guide/iphone/iph1b6c664b7/ios), they often mix personal and professional information. Our generator lets you create dedicated business contact cards, sharing only what you want others to see.

### How It Works

1. Go to [Contact Card Generator](/contact-card-generator)
2. Fill in your details
3. Add a photo (optional)
4. Generate your unique QR code or download a VCF
5. Save or share (only on iOS) instantly
6. Show the QR code for your contacts to scan from their phone’s camera
7. Send your VCF file via WhatsApp, Email, Messages, etc.

Note that due to limitations of QR codes, your photo will not be transferred. VCFs do embed your photo.

#### Pro Tip

> Save the QR code in the Files app & create a shortcut for quick access 

[https://www.youtube.com/embed/-8OxmJF3Eco?si=TjOCo0pcMapYw1zH](https://www.youtube.com/embed/-8OxmJF3Eco?si=TjOCo0pcMapYw1zH)
<br />

#### Pro Tip

> If you’re on an iPhone, you can [add a QR code scanner to control center](https://support.apple.com/en-in/guide/iphone/iphe8bda8762/ios). This will allow you to quickly scan QR codes from your phone’s camera.

[https://www.youtube.com/embed/tgakuPQXHVk?si=iSJRZgqoS4cpeBU8](https://www.youtube.com/embed/tgakuPQXHVk?si=iSJRZgqoS4cpeBU8)

## Make the Switch Today

Join the movement toward sustainable networking. Your contacts (and the trees) will thank you.

For those still using physical cards, consider printing your QR code on the back - it makes a lot easier for folks to save your contact information by scanning the QR code.


Introducing our Contact Card Generator - a simple yet powerful tool designed to modernize business networking while reducing paper waste. By generating a custom QR code containing your professional contact details, we’re making it easier than ever to share your business information digitally. No more carrying stacks of paper cards or mixing personal and professional contact details on your phone. Simply create your QR code once, save it to your device, and share it effortlessly whenever needed. Whether you scan it directly or download the VCF file, your professional connections can instantly save your contact information to their phones. It’s our small contribution to making networking both smarter and more sustainable.

Introducing Contact Card Generator


## Glossary

Before we dive into the topic, let's first understand some of the terminology that we will be using throughout this post.

- [Gradle](https://gradle.org/) is a build automation tool that is used to build, test, and package software written in Java, Kotlin, Groovy, Scala, or any other JVM language. In layman terms, just think of it as a wrapper around the language compiler that adds some extra functionality to make it easier to build and test your software.
- Dependencies are the libraries that your project depends on. Think of these as a set of useful code bundled up together that your project can use, instead of rewriting it everytime it is required.

## Introduction to Version Catalogs

Generally, in a Gradle project, when you want to use a dependency, you need to define the following things:

- The group of the dependency
- The name of the dependency
- The version of the dependency

For example, if you want to use the [OkHttp](https://square.github.io/okhttp/) library, you would define the following:

```kotlin
dependencies {
    implementation("com.squareup.okhttp3:okhttp:4.9.3")
}
```

Now, if you want to use the same library in another module of your project, you will need to make sure that you are using the same version of the library, or you might face compatibility issues.

This can still be resolved by defining the version of the dependency in your project's `gradle.properties` file, like this:

```ini
okhttpVersion=4.9.3
```

and then referencing it in your `build.gradle.kts` file:

```kotlin
dependencies {
    private val okhttpVersion: String by project
    implementation("com.squareup.okhttp3:okhttp:$okhttpVersion")
}
```


This is a good solution, and does solve our issue to a certain extent, but once you have to manage multiple projects, it becomes quite cumbersome to make sure that the versions are consistent across all the projects. Let's take a scenario where:

- You have a set of functions that provide useful abstractions over the OkHttp library, and you use them in multiple projects.
- To make it easier to manage these sets of functions, you decide to create a separate project that contains the functions that are common across all the projects, and you name the library `common`. This library uses OkHttp version `4.9.3` as its dependency.
- In your project, you import the `common` library, but instead of using the version `4.9.3` that you are using in the `common` library, you use the version `4.10.0`.

The given scenario might lead to the following issues:

- The `common` library might not be compatible with the version of OkHttp that you are using in your project, which results in either a compilation error or a runtime error.
- You might not be aware of the OkHttp version that you are using in your `common` library, and assume it's using the same version as your project, which might not be the case. This can lead to you not realizing that you are using an outdated version of OkHttp, which can result in security vulnerabilities in your code.
- Every time you update the OkHttp version in your `common` library, you need to update it in all the projects that use the library, which can be a tedious and time-consuming process.

__Here comes `version catalogs` to the rescue.__

A [version catalog](https://docs.gradle.org/current/userguide/version_catalogs.html) is a selected list of dependencies that can be referenced in a Gradle build script in a type-safe manner.

To explain it in developer terms, think of it as a file where you mention all the strings required by the project, so that instead of mentioning the same string again and again, you can just reference it from that file, with auto-completion support as icing on the cake. It also helps that every time you need to update that string, you only need to do it in one place, instead of updating it in multiple places.

## Using Version Catalogs in Gradle

Version catalog is defined in a file called `libs.versions.toml` in the `gradle` directory of your project. The `libs.versions.toml` file has four sections:

- `[versions]`: Declare versions of the dependencies. If you have a set of libraries which belong to the same group, instead of mentioning versions for them separately, you can define them in a single place, and reference it for all the libraries for which it is applicable.
- `[libraries]`: Here you can define the group, artifact, and version of the libraries that you are using in your project. For version, you can either mention the version directly, or you can reference a version from the `[versions]` section.
- `[bundles]`: If you have a set of libraries that are commonly used together, you can define them as a bundle, and import the bundle in your project. Gradle will check which libraries belong to that bundle, and import them all.
- `[plugins]`: Define plugins that you are using in your project. This is different from the `[libraries]` section, because plugins are not libraries, and instead of consisting of a group, artifact, and version, they consist of an id and a version.


An example `libs.versions.toml` file would look like this:

```toml
[versions]
okhttp = "4.9.3"

[libraries]
okhttp-core = { group = "com.squareup.okhttp3", name = "okhttp", version = "4.9.3" } # mentioning the version directly
okhttp-logging = { group = "com.squareup.okhttp3", name = "logging-interceptor", version.ref = "okhttp" } # referencing the version from the okhttp version

[bundles]
okhttp = ["okhttp-core", "okhttp-logging"]

[plugins]
kotlin-jvm = { id = "org.jetbrains.kotlin.jvm" , version = "1.9.20" }
```

To use the version catalog in your project, you need to add the following lines to your `build.gradle.kts` file:

```kotlin
plugins {
    alias(libs.plugins.kotlin.jvm) // to use the kotlin-jvm plugin
}

dependencies {
    // You can either import the libraries separately
    implementation(libs.okhttp.core)
    implementation(libs.okhttp.logging)
    // Or as a part of a bundle
    implementation(libs.bundles.okhttp)
}
```

## Publishing Version Catalogs

So far, we have seen how to define version catalogs in a `libs.versions.toml` file, and how to use them in a Gradle project. However, this still does not solve the inherent problem of managing dependencies across multiple projects. 

Fortunately, you can publish your version catalog, just like any other library! To do that, you need to import the following plugins:

```kotlin
plugins {
    `version-catalog`
    `maven-publish`
}
```

This will allow you to configure your version catalog, and configure `maven-publish` plugin to publish the catalog, like this:

```kotlin
catalog {
   versionCatalog {
       // Import the version catalog from the libs.versions.toml file
       from(files("${rootProject.projectDir}/gradle/libs.versions.toml"))
   }
}

publishing {
    publications {
        create<MavenPublication>("maven") {
            from(components["versionCatalog"])
            artifactId = "version-catalog"
            group = "com.yourgroup"
            version = "1.0" // or a version from a configuration file
        }
    }
}
```

Now, along with your `common` library, you can import the version catalog in your projects, and use the same version of the OkHttp library that you are using in the `common` library.

Add this to your `settings.gradle.kts` file:

```kotlin
dependencyResolutionManagement {
    versionCatalogs {
        create("libs") {
            from("com.yourgroup:version-catalog:1.0")
        }
    }
}
```

Voilà! Your version catalog is ready to be used in your project:

```kotlin
dependencies {
    implementation(libs.okhttp.core)
    implementation(libs.okhttp.logging)
}
```

Now, every time you update the OkHttp version in `common` library, you only need to update your library version in the project, and the OkHttp version will automatically be updated!

> But what if you want to use a library, that is not a part of version catalog?

In that case, you can customize the version catalog at the project level to include the library that you want to use:

```kotlin
dependencyResolutionManagement {
    val log4jToSlf4jVersion: String by settings
    versionCatalogs {
        create("libs") {
            from("com.yourgroup:version-catalog:1.0")
            library("log4jToSlf4j", "org.apache.logging.log4j:log4j-to-slf4j:$log4jToSlf4jVersion") // log4jToSlf4jVersion is defined in gradle.properties
        }
    }
}
```

Later you can add this library to your version catalog if you want this to be used across projects.

> Can we publish the `common` library as a part of the version catalog?

Since the `common` library is getting published along with the version catalog, we would need to make sure that the library version is updated in `libs.versions.toml` with every release.

To avoid this, you can define the `common` library not as a part of `libs.versions.toml`, but as a part of the version catalog Gradle plugin, like this:

```kotlin
catalog {
   versionCatalog {
       // Import the version catalog from the libs.versions.toml file
       from(files("${rootProject.projectDir}/gradle/libs.versions.toml"))
       library("common", "com.yourgroup:common:$version")
   }
}
```

Where you can dictate how the `version` is defined (environment variable, property, etc.).

## Conclusion

We have seen how to define version catalogs, and how to use them in a Gradle project. Instead of spending days updating each and every dependency manually across projects, you can reduce the effort to just a couple of hours!!

Additionally, to reduce the time even more, you can use a plugin like [version-catalog-update-plugin](https://github.com/littlerobots/version-catalog-update-plugin), which will automatically update the version of your dependencies to the latest version available that it can find. However, be careful while using such plugins, as sometimes they might update the version to an unstable one, which might not be desirable for your project.

Hope you found this post helpful!


Managing dependencies of your project is something that no one wants to do, but it is a necessary part of developing a project. When you have a set of runtime libraries that you need to use across multiple projects, it becomes quite challenging to make sure that your project is using the correct version of the common dependencies between the library and the project. In this post, we will take a look at what version catalogs are, how they can help you simplify dependency management, and how you can use them in Gradle.


Simplifying Dependency Management Using Version Catalogs in Gradle

## Two Common Pitfalls Identified, Which Any Team May Encounter

- Assuming that everything the client had listed must be included in the MVP
- Mistaking precision for accuracy

Let‘s break these down further & see what we learn!

### Assumption: Everything Listed Is Part of the MVP

Clients often come with a broad list of features they envision for their product, though these are often high-level and not fully thought through. While such input is valuable, it’s essential to focus on zing features for a Minimum Viable Product (MVP), ensuring a incremental approach to delivery rather than attempting to include everything at once.

An MVP is about identifying and prioritizing the *‘must-haves’* that will provide value early, allowing the product to have early launches with iterative improvements. Simply including all client requests without filtering or questioning the *‘why’* behind each feature can lead to bloated scopes, extended timelines, and unnecessary complexities.

The role of the team is not just to deliver what is requested but to refine the client’s vision. This involves asking questions, analysing feasibility, and offering alternative solutions that align with business goals. By doing so, teams can help clients achieve *‘faster time-to-market’*.

### Mistaking Precision for Accuracy

Another challenge arises when teams focus on precision rather than accuracy in their estimates.
- **Accuracy**: Saying, “This feature will take about a week to implement”, keeps expectations reasonable.
- **Precision**: Claiming, “This feature will take exactly 34 hours”, might seem confident but is less likely to account for changes or setbacks.

In early project planning, focusing on accuracy allows teams to provide high-level estimates that guide decisions effectively without creating rigid or unrealistic expectations. Precise estimates at this stage, while detailed, can mislead and slow down progress if they don’t align with evolving project details. By doing this, teams fosters more productive conversations with clients, enabling them to make informed decisions faster.

## Key Takeaways

- Always question and refine client requirements to deliver the most value.
- Remember, an MVP is about *‘minimal effort’* with *‘maximum viability’*.
- Prioritize *‘accuracy’* over precision in early-stage estimations.

Estimation is more than a technical exercise; it is a collaborative process between the client and the team which requires questioning and a clear focus to deliver faster, but with something that holds value. 


Effective early-stage estimation goes beyond calculating numbers—it’s about refining client visions, questioning assumptions, and setting realistic expectations. Challenges like assuming all client-listed features belong in the MVP or mistaking precision for accuracy can derail progress. This blog shares lessons learned, emphasizing prioritizing value-driven features, adopting an iterative approach, and focusing on accuracy over precision to streamline early project planning.

Stories From the Trenches