Forem: kaan karakoc

How a "Boring" CLI Cleanup in Apache Kafka Tells a Big Story

kaan karakoc — Thu, 04 Sep 2025 05:24:51 +0000

How a "Boring" CLI Cleanup in Apache Kafka Tells a Big Story

What's the most "unglamorous" Pull Request you've ever submitted?

Not a complex new feature, but a small cleanup? Maybe just tidying up some help text in a command-line tool?

We often dismiss these refinements as "chores." They don't change functionality, so they feel less important. We rarely talk about them.

But what if these small "cleanup" tasks tell a much bigger story about quality, consistency, and respect for the user?

Today, I want to prove this by taking a genuinely boring PR from a world-class open-source project and turning it into a full story.

The Case Study: Standardizing Text in Kafka's CLI

I found this Pull Request in the official Apache Kafka repository.

It doesn't add a new feature or fix a critical bug.

👉 It standardizes the placeholder names (metavariables) in the help text for several of Kafka's command-line tools.

Most would see this, merge it, and forget it instantly.

"It's just a cosmetic change, right?"

But what's the real story here?

The Magic: Turning the "Cleanup" PR into a Story

I took the URL of this PR and fed it into my side project, DevToPost.

The tool’s job is to analyze the PR and generate a structured blog post draft from it.

Here’s the raw, unedited article it generated 👇

Improving Metavariable Names in Kafka's CLI Usage Messages

In the world of software engineering, the command-line interface (CLI) remains a primary point of interaction for developers. A well-designed CLI is intuitive, predictable, and self-documenting. Every detail, no matter how small, contributes to the overall developer experience. A recent change to Apache Kafka's command-line tools underscores this principle by refining the clarity and consistency of its usage messages.

This update focuses on standardizing the format of "metavariables"—the placeholder names that appear in help text to indicate the expected value for a given argument. While seemingly a minor cosmetic fix, this effort enhances readability and aligns Kafka's tooling with established CLI conventions.

The Case for Consistency

When a developer runs a command-line tool with the --help flag, the output should be as clear as possible. Metavariables play a crucial role by providing a hint about the data type or format of the required input. For example, --topic TOPIC immediately suggests that TOPIC should be replaced with a topic name.

Prior to this change, the metavariable names in Kafka's verifiable consumer and producer tools lacked a consistent format. Different arguments used different conventions, mixing unseparated PascalCase, snake_case, and other styles. This could lead to minor confusion and a less polished feel.

Consider the previous usage message for the verifiable-consumer:

usage: verifiable-consumer [-h] --topic TOPIC
    [--group-protocol GROUP_PROTOCOL]
    [--group-remote-assignor GROUP_REMOTE_ASSIGNOR]
    --group-id GROUP_ID
    [--group-instance-id GROUP_INSTANCE_ID]
    [--max-messages MAX-MESSAGES]
    [--session-timeout TIMEOUT_MS] [--verbose]
    [--enable-autocommit] [--reset-policy RESETPOLICY]
    [--assignment-strategy ASSIGNMENTSTRATEGY]
    [--consumer.config CONFIG_FILE] [--command-config CONFIG_FILE]
    --bootstrap-server HOST1:PORT1[,HOST2:PORT2[...]]

Notice the variations in style for placeholders like RESETPOLICY, ASSIGNMENTSTRATEGY, and TIMEOUT_MS. The lack of separators in the first two makes them harder to read at a glance, while the mix of underscore and unseparated conventions feels inconsistent.

The Solution: A Uniform Naming Standard

The implemented solution was straightforward: update all multi-word metavariables to use a consistent, hyphenated, uppercase format. This simple change significantly improves the scannability and professionalism of the help text.

Here is the updated usage message for the verifiable-consumer:

usage: verifiable-consumer [-h] --topic TOPIC
    [--group-protocol GROUP-PROTOCOL]
    [--group-remote-assignor GROUP-REMOTE-ASSIGNOR]
    --group-id GROUP-ID
    [--group-instance-id GROUP-INSTANCE-ID]
    [--max-messages MAX-MESSAGES]
    [--session-timeout TIMEOUT-MS] [--verbose]
    [--enable-autocommit] [--reset-policy RESET-POLICY]
    [--assignment-strategy ASSIGNMENT-STRATEGY]
    [--consumer.config CONFIG-FILE] [--command-config CONFIG-FILE]
    --bootstrap-server HOST1:PORT1[,HOST2:PORT2[...]]

As you can see, RESETPOLICY is now RESET-POLICY, ASSIGNMENTSTRATEGY is ASSIGNMENT-STRATEGY, and other variables have been updated to match this clear and readable convention. Similar improvements were applied to the verifiable-producer and verifiable-share-consumer tools.

The change was implemented directly in the argument parser definitions for each tool. By modifying the metavar attribute, we can control the placeholder text displayed in the usage message without altering the underlying argument destination or logic.

The following snippet from VerifiableConsumer.java illustrates how the metavariables for --reset-policy and --assignment-strategy were updated:

        parser.addArgument("--reset-policy")
            .action(store())
            .required(false)
            .setDefault("earliest")
            .type(String.class)
            .dest("resetPolicy")
            .metavar("RESET-POLICY")
            .help("Set reset policy (must be either 'earliest', 'latest', or 'none')");

        parser.addArgument("--assignment-strategy")
            .action(store())
            .required(false)
            .setDefault(RangeAssignor.class.getName())
            .type(String.class)
            .dest("assignmentStrategy")
            .metavar("ASSIGNMENT-STRATEGY")
            .help(String.format("Set assignment strategy (e.g. %s); only used if the group protocol is %s", RoundRobinAssignor.class.getName(), GroupProtocol.CLASSIC.name()));

This clean, declarative approach ensures that the user-facing documentation is instantly improved.

Impact and Benefits

This refinement, while subtle, carries several important benefits for the Kafka developer community:

Improved Readability: Hyphenated names like ASSIGNMENT-STRATEGY are inherently easier to parse than their unseparated counterparts. This reduces cognitive overhead and helps developers quickly understand the purpose of each argument.
Enhanced Consistency: By adopting a single, clear standard, the tools now present a more cohesive and predictable interface. Users can expect the same formatting conventions across different Kafka CLI tools, which simplifies learning and usage.
Adherence to Best Practices: Using a delimited, uppercase style for metavariables is a widely accepted convention in the world of command-line tools. This change brings Kafka's tools into better alignment with developer expectations.
Attention to Detail: This update demonstrates a commitment to a high-quality developer experience. Polished, professional tooling is the result of continuous refinement, where even the smallest details are considered important.

Final Thoughts

Building powerful, distributed systems like Apache Kafka is a complex endeavor. However, ensuring that the tools for interacting with that system are clear, consistent, and easy to use is just as critical. This enhancement to metavariable naming is a perfect example of a small change that delivers a tangible improvement to the daily workflow of countless developers. It is through such thoughtful refinements that a project maintains its high standards of quality and usability.

The Real Story is More Than the Code

Look at that. The generated article isn't about changing some text.

It's about developer experience, consistency, and modern CLI design.

The AI didn’t just see a text change. It understood the real story:

The Why: inconsistent naming was creating friction for users.
The Context: in Apache Kafka, a massive ecosystem where a professional interface is a necessity.
The Impact: improved readability and developer ergonomics.

Every Contribution Has Value

Your work deserves to be seen.

That "boring" cleanup you pushed last week wasn’t just a chore—it saved future users from confusion and frustration. It made the project better.

👉 If you have your own "small" PRs that you think are worthless, I challenge you to see the bigger story.

💬 What’s the smallest contribution you’ve ever made that had a hidden, important story?

Drop it in the comments below 👇

I Turned My 2-Year-Old GitHub PR into This Blog Post (Using My Own Tool)

kaan karakoc — Mon, 01 Sep 2025 18:49:11 +0000

We've all been there. You spend hours, maybe even days, crafting the perfect Pull Request for an open-source project. You document everything, polish the code, and finally see that satisfying purple "Merged" badge.

Fast forward a year or two, and that contribution is just a ghost in your commit history, its story untold.

I recently found one of my own forgotten PRs from about two years ago where I added a new module to the testcontainers-node library. (https://github.com/testcontainers/testcontainers-node/pull/646) I wanted to tell the story of that contribution, but I didn't want to spend hours writing it from scratch.

So, I decided to "eat my own dog food."

The core technical deep-dive of this article was generated in about 30 seconds using my own tool, DevToPost.

Here's a quick demo of the tool in action:
https://www.loom.com/share/d72bae1f4b944fee9fe2946e2833d5ea?sid=69e16458-137e-40f4-abf0-a1ee7306013c

The Story of the Contribution (Generated by DevToPost)

Streamlining Couchbase Integration Testing with the New Testcontainers-Node Module

We are pleased to announce the addition of a dedicated Couchbase module to Testcontainers-Node. This new module empowers developers to effortlessly spin up Couchbase instances as part of their integration tests, significantly simplifying the setup and teardown of complex database environments. For anyone building applications with Couchbase, this enhancement brings a new level of efficiency and reliability to the testing workflow.

The Challenge of Integrating Couchbase in Tests

Integrating a robust NoSQL database like Couchbase into automated testing environments can often be a source of friction. Developers face several challenges:

Setup Complexity: Couchbase is a distributed document database with various services (Key-Value, Query, Search, Analytics, Eventing) and configuration options for buckets, users, and memory quotas. Manually setting up a consistent Couchbase instance for each test run can be time-consuming and error-prone.
Environmental Parity: Ensuring that the test environment closely mirrors production can be difficult, leading to discrepancies and unreliable test results.
Isolation: Tests need to run in isolation to prevent side effects and ensure reproducibility. Managing separate Couchbase instances for parallel tests typically requires sophisticated orchestration.
Resource Management: Efficiently starting and stopping database instances, and cleaning up resources after tests, is crucial to maintain fast feedback cycles and avoid resource leakage.

These challenges often lead to developers resorting to slower, less reliable alternatives or even skipping integration tests altogether, which can compromise application quality.

Introducing the Couchbase Module for Testcontainers-Node

The new Couchbase module for Testcontainers-Node directly addresses these pain points by providing a programmatic, Docker-native way to manage Couchbase instances for testing. Leveraging the power of Testcontainers, developers can now define their Couchbase test environment in code, guaranteeing consistency and isolation.

The core of this new functionality resides in the CouchbaseContainer class, which extends GenericContainer and provides Couchbase-specific configuration methods.

Key features and capabilities include:

Automatic Lifecycle Management: CouchbaseContainer handles the entire lifecycle of a Couchbase Docker container, from pulling the image to starting it, waiting for it to be ready, and stopping it upon test completion.
Flexible Service Configuration: Developers can specify which Couchbase services (KV, Query, Search, Index, Analytics, Eventing) should be enabled for their test instance, tailoring the environment precisely to their needs. The module intelligently validates service compatibility with Couchbase editions (e.g., Analytics and Eventing services require an Enterprise image).
Customizable Buckets: The BucketDefinition class allows for detailed configuration of Couchbase buckets, including name, RAM quota, number of replicas, flush enablement, and primary index creation.
Credential Management: Easily configure administrative usernames and passwords for the Couchbase instance.
Support for Editions: Seamlessly switch between Couchbase Community and Enterprise editions by simply specifying the Docker image tag.

Getting Started: Installation and Basic Usage

To begin using the Couchbase module, install it as a development dependency in your project:

npm install @testcontainers/couchbase --save-dev

Once installed, you can integrate a Couchbase container into your tests with minimal effort. The following example demonstrates how to start a Couchbase container, create a bucket, connect to it using the Couchbase Node.js SDK, and perform a basic key-value operation.

Here's a concise example of initializing a Couchbase container and interacting with it:

import { CouchbaseContainer, BucketDefinition } from "@testcontainers/couchbase";
import { Cluster } from "couchbase"; // Assumes the couchbase SDK is installed

async function runCouchbaseExample() {
  const COUCHBASE_IMAGE = "couchbase/server:community-7.0.2";
  const bucketDefinition = new BucketDefinition("mytestbucket");

  // Initialize and start the Couchbase container
  const container = await new CouchbaseContainer(COUCHBASE_IMAGE)
    .withBucket(bucketDefinition)
    .withCredentials("testuser", "testpassword") // Custom credentials
    .start();

  console.log("Couchbase container started and ready.");

  // Connect to the Couchbase cluster using the provided connection string and credentials
  const cluster = new Cluster(container.getConnectionString(), {
    username: container.getUsername(),
    password: container.getPassword(),
  });

  const bucket = cluster.bucket(bucketDefinition.getName());
  const collection = bucket.defaultCollection();

  // Perform a simple upsert and get operation
  await collection.upsert("my_document_id", { message: "Hello from Testcontainers!" });
  const result = await collection.get("my_document_id");
  console.log("Retrieved document:", result.content);

  // Clean up: close the cluster connection and stop the container
  await cluster.close();
  await container.stop();
  console.log("Couchbase container stopped.");
}

runCouchbaseExample().catch(console.error);

This example demonstrates the simplicity of the API: instantiate CouchbaseContainer, configure it with buckets and credentials, and call .start(). Testcontainers handles the rest, providing you with a ready-to-use Couchbase instance.

Advanced Configuration Options

The module provides extensive configuration options to precisely match your testing needs. You can enable specific Couchbase services, set custom memory quotas for those services, and fine-tune bucket properties.

For instance, if your application requires Couchbase's Analytics service, you would use an Enterprise image and explicitly enable the service:

import { CouchbaseContainer, BucketDefinition, CouchbaseService } from "@testcontainers/couchbase";
import { Cluster } from "couchbase";

async function runAdvancedCouchbaseExample() {
  // Note: Analytics service requires an Enterprise image
  const COUCHBASE_IMAGE_ENTERPRISE = "couchbase/server:enterprise-7.0.3";
  const analyticsBucket = new BucketDefinition("analyticsData")
    .withFlushEnabled(true) // Enable flush for easy cleanup
    .withPrimaryIndex(true) // Create a primary index for querying
    .withQuota(200); // Set a custom RAM quota for the bucket (MB)

  const container = await new CouchbaseContainer(COUCHBASE_IMAGE_ENTERPRISE)
    .withBucket(analyticsBucket)
    .withEnabledServices(
      CouchbaseService.KV,
      CouchbaseService.QUERY,
      CouchbaseService.ANALYTICS // Enable the Analytics service
    )
    .withServiceQuota(CouchbaseService.ANALYTICS, 1200) // Set a custom RAM quota for the Analytics service (MB)
    .withCredentials("admin", "secretpassword")
    .start();

  console.log("Couchbase Enterprise container with Analytics service started.");

  const cluster = new Cluster(container.getConnectionString(), {
    username: container.getUsername(),
    password: container.getPassword(),
  });
  // ... perform advanced operations with the Analytics service ...

  await cluster.close();
  await container.stop();
  console.log("Advanced Couchbase container stopped.");
}

runAdvancedCouchbaseExample().catch(console.error);

This snippet illustrates how to provision a Couchbase Enterprise instance with the Analytics service enabled, set its memory quota, and configure a bucket with flush capabilities and a primary index, all within your test code.

Under the Hood: A Glimpse at the Setup Process

The CouchbaseContainer performs a sophisticated orchestration to bring up a fully configured Couchbase instance. Upon start(), it:

Exposes Necessary Ports: Dynamically determines and exposes the required Couchbase service ports.
Waits for Node Online: Waits for the Couchbase node to become accessible via its management API.
Determines Edition: Checks if the running image is an Enterprise or Community edition to validate service requests.
Renames Node: Configures the Couchbase node to use its correct network hostname.
Initializes Services: Enables the specified services (KV, Query, Search, etc.).
Sets Memory Quotas: Configures memory quotas for each enabled service, respecting custom settings or default minimums.
Configures Admin User: Sets up the administrative user credentials.
Maps External Ports: Ensures that external ports are correctly mapped for client connectivity.
Configures Indexer: Sets the storage mode for the indexer service.
Creates Buckets and Indexes: Iterates through all defined BucketDefinition objects, creating each bucket with its specified properties and, if requested, a primary index. Robust wait strategies ensure that buckets and indexes are fully operational before proceeding.

This intricate sequence, abstracted away from the developer, ensures a stable and ready-to-use Couchbase instance for every test.

Impact and Benefits

The introduction of the Couchbase module delivers significant benefits to developers:

Reproducible and Isolated Environments: Each test can run with its own dedicated Couchbase instance, ensuring that tests are truly isolated and results are consistent across different machines and runs.
Faster Feedback Loops: Eliminating manual setup and teardown of Couchbase instances accelerates test execution, providing quicker feedback on code changes.
Simplified Test Code: Reduces boilerplate in test suites by abstracting away the complexities of Couchbase provisioning and configuration.
Enhanced Test Reliability: By accurately simulating a Couchbase environment, integration tests become more reliable and better reflect real-world scenarios.
Comprehensive Configuration: Supports a wide range of Couchbase configurations, from basic Key-Value stores to multi-service clusters, enabling thorough testing of complex application interactions.

Conclusion

The new Couchbase module for Testcontainers-Node marks a significant step forward in simplifying the integration testing of applications that leverage Couchbase. By allowing developers to define and manage their Couchbase test environments as code, it promotes better testing practices, reduces development overhead, and ultimately leads to more robust and reliable software. We encourage all Couchbase developers to explore this powerful new tool and experience the benefits of streamlined, container-backed integration testing.

I built a tool that turns GitHub PRs into blog posts — looking for feedback

kaan karakoc — Sun, 31 Aug 2025 13:53:38 +0000

🎯 The Problem

As developers, we spend hours crafting Pull Requests: writing descriptions, explaining why the change matters, and documenting code.

But once the PR is merged… it often disappears into the void.

That effort rarely lives beyond GitHub.

I’ve always felt this was a wasted opportunity.

Every PR — especially in open source — tells a story: the problem, the reasoning, the solution.

Why not turn that into something more lasting, like a blog post?

💡 The Solution: devtopost

That’s why I’ve been working on devtopost, a small side project that automatically turns your GitHub PRs into polished blog posts.

Paste a PR link
The tool analyzes the title, description, commits, and diff
It generates a professional, markdown-ready article (introduction → problem → solution → impact → conclusion)

So instead of staring at a blank page, you already have a structured draft you can publish on your blog, dev.to, or LinkedIn.

🛠️ How It Works

Under the hood:

GitHub API to fetch PR metadata & diff
AI (LLM) to generate structured technical writing
Opinionated prompts to enforce professional tone, Markdown formatting, and code snippet rules

The current MVP just lets you try it out with 1 free PR → blog conversion.

Later I’m thinking of offering subscriptions for people who publish frequently.

🤔 Why I’m Sharing This Here

I don’t want this to be an “ad”.

I’m genuinely curious:

Would you use something like this?
Do you see this as useful for open source maintainers who want to highlight their contributions?
Or for engineers building a portfolio without rewriting the same stories?

I’d love feedback from this community — whether it’s “I’d never use it” or “here’s what could make it better”.

🚀 Try It

If you’re curious, you can try the MVP here:

👉 https://devtopost.ai

Thanks for reading!

Building this has been fun, but I want to make sure it actually solves a real pain point for devs.

Any feedback, feature requests, or even brutal honesty is welcome ✌️