A Hacktoberfest Quest Through TDK CLI's Islands

TDK CLI's open Hacktoberfest issues are grouped into islands, each with its own difficulty ladder. Here is a route through them, from your first translation to your first engine change.

Most Hacktoberfest advice is a list. Pick five issues, read the labels, and go. That works, but it hides the best part of a contribution repo: the issues are arranged to be learned in order.

TDK CLI's open hacktoberfest issues are grouped into islands, each one a different part of the codebase with its own ladder of difficulty. I counted about 139 open issues when I checked. You do not need to try them all. You need a route.

The map

The repo's own Hacktoberfest map uses the same idea. Each island has a theme, and each issue has a rank, from 8 kyu for a small documentation fix to 6 kyu for a refactor that needs context.

Island	Theme	Typical rank	What you do there
Docs Harbor	Documentation and translation	8 kyu	Translate pages, fix wording, map a module
Test Atoll	Tests and test infrastructure	7 kyu to 6 kyu	Add tests for code that already works
Engine Volcano	Generated Docker and Compose	7 kyu to 6 kyu	Refactor small helpers in the engine
CLI Cove	Commands, flags and errors	7 kyu to 6 kyu	Make error messages and flags consistent

The island names are in the repo, in issues such as #459, which lists CLI Cove. Read the labels on any issue and you will see which island it belongs to.

Route 1: the first week in Docs Harbor

Start where the stakes are lowest. Translation issues come in several languages, and each one maps to a single documentation page. You read carefully, you write clearly, and you learn how the tool describes itself.

Good first stops:

• #1131: map the Starlark topology module boundaries (8 kyu). Read the engine's topology modules and write a current map of them. This is a reading exercise that teaches you how a service.json reaches the generated files.
• A translation issue in a language you read well. The titles tell you which page. Pick the one you would want to read yourself.

Route 2: learn to test in Test Atoll

Once you are comfortable with the repo, tests are the next step. A test issue adds coverage to code that already works, so you can learn how the code behaves before you change it.

• #1130: cover generated Docker network initialization and cleanup commands (7 kyu). Find the code that creates and removes Docker networks, then write tests for it.
• #1174: test the generated Axum routes over HTTP (6 kyu). A step up: you start a generated Rust service and check its routes. Take this after one easy test.

Route 3: a small refactor in Engine Volcano

When you want to change code, the engine is where the real structure lives. These issues are small on purpose.

• #1126: parse Compose load-balancer ports in one helper (7 kyu). Find the places that parse the same port data, and move them into one helper. Your existing tests tell you whether you broke anything.
• #1128: move migrator Compose generation into a focused module (7 kyu). A small move with clear boundaries. Good practice for reading how the generator is split.

Before you open a pull request

The repo's rules are short, and the checks enforce them, so it is worth reading them first.

1. Sign off every commit. Use git commit -s. Each commit needs a Signed-off-by line under the Developer Certificate of Origin. The pull request check fails without it. If you forgot, run git rebase --signoff origin/main and push again.
2. Keep one issue to one pull request. The easy issues are built for a focused change.
3. Read CONTRIBUTING.md. It explains the labels and the process.
4. Check lint by its exit code. Run the CI's lint command and read $?. Piping it through tail can hide a failure.

What you get out of it

A small Hacktoberfest contribution teaches more than a fresh side project. You see how a CLI is structured, how generated Docker and Compose files are produced, and how tests check them. You also get a real review from maintainers who know the code.

Pick an island, climb its ladder one rank at a time, and you finish the month knowing the codebase better than most people who used it.

A note on DEV challenges

This is a contribution guide, not a DEV challenge entry. The current challenge's rules require a new project built during the challenge window, and pull requests to existing projects do not count. If you want to enter a challenge, build something new. The islands are a good place to learn the habits you will need.