Onboarding: krahets/hello-algo

Generated by RepoPilot · 2026-05-05 · Source

Verdict

WAIT — Mixed signals — read the receipts

• Last commit 2w ago
• 5 active contributors
• Other licensed
• CI configured
• ⚠ Small team — 5 top contributors
• ⚠ Concentrated ownership — top contributor handles 60% of commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

TL;DR

hello-algo is an open-source, animated, interactive textbook on data structures and algorithms (DSA), written primarily in Chinese (with English, Traditional Chinese, and Japanese translations). It provides runnable code examples across 13+ languages (Python, Java, C++, Go, Swift, Rust, Ruby, JavaScript, etc.) organized by DSA chapter under codes/, with animated visual explanations hosted at hello-algo.com. Monorepo: all runnable code lives under codes/<language>/chapter_<topic>/ (e.g., codes/c/chapter_dynamic_programming/, codes/java/chapter_backtracking/). Each language folder has its own build config (CMakeLists.txt for C, build.gradle or pom.xml for Java, etc.). The book content (Markdown + assets) lives separately from code and is published via MkDocs to hello-algo.com.

Who it's for

CS students and self-taught developers (especially Chinese-speaking) who are learning DSA fundamentals from scratch and want to see animated explanations alongside executable, multi-language reference implementations — not just pseudocode.

Maturity & risk

The repo is highly mature for an educational resource: it has 14 language CI pipelines under .github/workflows/ (java.yml, python.yml, cpp.yml, go.yml, swift.yml, rust.yml, ruby.yml, etc.), a published PDF/EPUB release, and a live website. It is actively maintained with a large contributor base and consistent commit activity. Verdict: production-quality educational content, actively developed.

Risk is low for consumers (readers/students) — it is a textbook, not a library dependency. For contributors, the main risk is scope: maintaining identical implementations across 13+ languages means any algorithmic correction must propagate to all language variants, which is labor-intensive. Single-maintainer (krahets) risk exists for editorial decisions, though community PRs are active.

Active areas of work

Active work includes multi-language translation (English and Japanese versions visible in en/ and ja/ README references), adding new language implementations, and CI pipeline maintenance across all 14 language workflows. The Dockerfile and codes/Dockerfile suggest containerized execution environments are being refined.

Get running

git clone https://github.com/krahets/hello-algo.git && cd hello-algo

To run a specific language example, e.g. C:

cd codes/c && mkdir build && cd build && cmake .. && make && ./chapter_dynamic_programming/climbing_stairs_dp

For Python (no install needed):

python3 codes/python/chapter_dynamic_programming/climbing_stairs_dp.py

For Java (requires JDK):

cd codes/java && gradle run # or javac/java per chapter

Daily commands: Per language: C/C++: cd codes/c && cmake -B build && cmake --build build; Go: cd codes/go/chapter_X && go run *.go; Python: python3 codes/python/chapter_X/file.py; Java: cd codes/java && gradle run; Rust: cd codes/rust && cargo run --bin chapter_X; Ruby: ruby codes/ruby/chapter_X/file.rb. Docker: docker build -f codes/Dockerfile . && docker run <image>.

Map of the codebase

• README.md — Primary entry point describing the project's purpose, supported languages, and how to navigate the educational content across all implementations.
• codes/c/CMakeLists.txt — Top-level CMake build configuration that aggregates all C chapter subdirectories and defines how the entire C codebase is compiled.
• codes/c/chapter_computational_complexity/time_complexity.c — Canonical reference implementation establishing the coding style and pedagogical pattern used across all algorithm implementations in the repo.
• codes/c/chapter_dynamic_programming/knapsack.c — Representative complex algorithm file showing how multi-step DP solutions are structured, annotated, and presented for learners.
• codes/c/chapter_graph/graph_adjacency_list.c — Core graph data structure implementation that is reused by graph_bfs.c and graph_dfs.c, making it a foundational dependency within the graph chapter.
• .github/workflows/c.yml — CI workflow that validates all C code compiles and runs correctly; defines the quality gate every contributor's code must pass.
• Dockerfile — Container definition enabling one-click reproducible execution of all code examples, central to the repo's 'one-click run' promise.

How to make changes

Add a new algorithm implementation in C

1. Create a new .c file in the relevant chapter directory following the naming convention <algorithm_name>.c, with a main() function and inline educational comments matching existing files (codes/c/chapter_sorting/your_sort.c)
2. Add the new executable target to the chapter's CMakeLists.txt using add_executable() and target_link_libraries() matching the pattern of existing entries (codes/c/chapter_sorting/CMakeLists.txt)
3. Verify the new file is picked up by the root CMake configuration via add_subdirectory() — no change needed if the chapter directory is already listed (codes/c/CMakeLists.txt)
4. Test compilation locally or via the CI workflow to ensure the new file builds and runs without errors (.github/workflows/c.yml)

Add a new chapter (topic) to the C section

1. Create a new directory under codes/c/ named chapter_<topic>/ and add at least one .c implementation file with a main() entry point (codes/c/chapter_<topic>/<algorithm>.c)
2. Create a CMakeLists.txt inside the new chapter directory listing all executable targets for that chapter (codes/c/chapter_<topic>/CMakeLists.txt)
3. Register the new chapter directory with add_subdirectory(chapter_<topic>) in the root C CMakeLists.txt (codes/c/CMakeLists.txt)

Add a new data structure with test file

1. Implement the data structure in a new .c file under the most relevant chapter, e.g. chapter_hashing/, exposing init/insert/delete/print functions (codes/c/chapter_hashing/hash_map_your_method.c)
2. Create a companion _test.c file (following the pattern of graph_adjacency_list_test.c) that exercises all operations with printed output (codes/c/chapter_hashing/hash_map_your_method_test.c)
3. Register both files as separate executable targets in the chapter's CMakeLists.txt (codes/c/chapter_hashing/CMakeLists.txt)

Add CI validation for a new language

1. Create a new workflow YAML under .github/workflows/ named <language>.yml, modelled on an existing workflow like c.yml, specifying build and run steps (.github/workflows/<language>.yml)
2. Add the corresponding Dockerfile stage or script in codes/Dockerfile if the language requires a custom runtime environment (codes/Dockerfile)

Why these technologies

• Multi-language implementations (C, Python, Java, Go, Rust, etc.) — Maximises accessibility for learners from any programming background; each reader can study algorithms in their language of choice without translation overhead.
• CMake for C builds — Cross-platform build system that works on Linux, macOS, and Windows, ensuring the 'one-click run' promise holds regardless of developer environment.
• Docker — Eliminates environment setup friction by providing a pre-configured container where all language runtimes and compilers are available.
• GitHub Actions CI per language — Isolated per-language workflows prevent a broken Rust file from blocking Python PR checks, reducing noise and speeding up feedback.
• Static site (MkDocs / hello-algo.com) — Allows animated diagram embeds and side-by-side code display; decouples documentation rendering from code execution.

Trade-offs already made

• One file per algorithm with self-contained main()
  • Why: Makes each file independently runnable and easy to read in isolation without needing to understand the whole codebase.
  • Consequence: Significant code duplication across files (e.g. print helpers, common node structs redefined in every file); no shared utility library.

Traps & gotchas

Each language implementation must be kept algorithmically identical to all others — diverging logic between language versions is a common contributor mistake caught in review. The C and C++ builds require CMake 3.x; the CMakeLists.txt files must be updated manually when adding new .c/.cpp files — forgetting this breaks CI. Swift examples may require a specific Xcode or Swift toolchain version matching the CI image in .github/workflows/swift.yml. No shared test framework exists — correctness is verified by stdout matching expected output, so print statement format must be consistent.

Architecture

Concepts to learn

• Backtracking with pruning — codes/c/chapter_backtracking/ contains subset_sum_i_naive.c vs subset_sum_i.c — understanding how pruning eliminates branches is essential to follow the performance difference shown.
• Dynamic programming state compression — climbing_stairs_constraint_dp.c demonstrates reducing a 2D DP table to a 1D rolling array — a non-obvious optimization pattern repeated across many DP problems in the book.
• Divide and conquer tree construction — codes/c/chapter_divide_and_conquer/build_tree.c shows how recursive divide-and-conquer maps directly onto binary tree construction from traversal arrays — a key insight for tree chapters.
• Space complexity analysis — codes/c/chapter_computational_complexity/space_complexity.c explicitly demonstrates stack frame growth, heap allocation, and auxiliary space — concepts beginners typically overlook when analyzing algorithms.
• Tower of Hanoi recursion — codes/c/chapter_divide_and_conquer/hanota.c is used as the canonical example for teaching recursive problem decomposition; understanding it unlocks the mental model for all recursive chapters.
• Permutation with deduplication — permutations_ii.c vs permutations_i.c in chapter_backtracking shows how a visited[] boolean array plus sorting eliminates duplicate permutations — a subtle but frequently tested pattern.

Related repos

• TheAlgorithms/Python — Largest alternative multi-language algorithm reference repo; no animated explanations but broader algorithm coverage.
• labuladong/fucking-algorithm — Another Chinese-language DSA tutorial repo targeting LeetCode problem patterns, often used alongside hello-algo.
• youngyangyang04/leetcode-master — Companion Chinese DSA repo focused on LeetCode problem-by-problem walkthroughs with C++ and Java code.
• krahets/LeetCode-Book — Same author's LeetCode problem book, directly complementary to hello-algo for applied practice.
• algorithm-visualizer/algorithm-visualizer — Predecessor/inspiration for animated algorithm visualization; hello-algo adds multi-language runnable code on top of this concept.

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions CI workflow for Zig language implementation

The repo already has CI workflows for 13 languages (Python, Java, C++, C, C#, JS, Go, Swift, Rust, Ruby, Kotlin, TS, Dart) under .github/workflows/. Zig is a growing systems programming language with strong appeal to algorithm learners. Adding a Zig implementation with a corresponding .github/workflows/zig.yml would follow the exact pattern of existing workflows like .github/workflows/rust.yml or .github/workflows/c.yml, and expand the repo's language coverage meaningfully.

• [ ] Study the structure of an existing workflow, e.g. .github/workflows/rust.yml or .github/workflows/c.yml, to understand the CI pattern used
• [ ] Create codes/zig/ directory mirroring the chapter structure seen in codes/c/ (e.g. chapter_array_and_linkedlist, chapter_computational_complexity, etc.)
• [ ] Implement at least one complete chapter in Zig, such as codes/zig/chapter_array_and_linkedlist/array.zig, linked_list.zig, and my_list.zig
• [ ] Add a build.zig file at codes/zig/ level to allow 'zig build' to compile and run all examples
• [ ] Create .github/workflows/zig.yml that installs the Zig toolchain and runs 'zig build test' or equivalent against codes/zig/
• [ ] Open the PR with at least the CI workflow file and one fully working chapter so reviewers can verify the pipeline end-to-end

Add missing chapter_greedy C implementations to mirror the dynamic programming chapter coverage

The codes/c/chapter_greedy/ directory currently contains only coin_change_greedy.c and fractional_knapsack.c, while codes/c/chapter_dynamic_programming/ has 13 well-covered files. The greedy chapter in other languages likely includes additional problems (e.g. max_capacity.c for the container-with-most-water problem, and max_product_cutting.c). Filling in these gaps ensures the C implementation is consistent with other language implementations and provides a complete reference for C learners.

• [ ] Check the greedy chapter implementations in another complete language (e.g. codes/python or codes/java under chapter_greedy/) to identify which files are present but missing from codes/c/chapter_greedy/
• [ ] Implement the missing files such as max_capacity.c and max_product_cutting.c inside codes/c/chapter_greedy/, following the style and structure of the existing coin_change_greedy.c
• [ ] Add the new source files to codes/c/chapter_greedy/CMakeLists.txt so they are compiled as part of the existing CMake build
• [ ] Verify the new files compile and run cleanly using the CMake build defined in codes/c/CMakeLists.txt
• [ ] Confirm the .github/workflows/c.yml CI pipeline passes with the new files included

Refactor codes/c/chapter_graph/ by extracting shared graph utilities into a reusable graph_common.h header

The codes/c/chapter_graph/ directory contains graph_adjacency_list.c, graph_adjacency_list_test.c, graph_adjacency_matrix.c, graph_bfs.c, and graph_dfs.c. These files very likely duplicate node/edge struct definitions and helper functions (e.g. Vertex structs, adjacency list node types, queue helpers for BFS). Extracting shared definitions into a graph_common.h file would eliminate duplication, make each .c file shorter and easier to read, and establish the same modular pattern already used elsewhere in the C codebase (e.g. the utils headers pattern seen across chapters).

• [ ] Audit codes/c/chapter_graph/graph_adjacency_list.c, graph_adjacency_matrix.c, graph_bfs

Good first issues

1. Add missing Ruby implementations: check codes/ruby/ against codes/python/ chapter-by-chapter — several chapters present in Python likely lack Ruby equivalents given Ruby's large byte count but narrower chapter coverage. 2. Add unit-style assertions to C examples in codes/c/chapter_computational_complexity/ — currently they only print output with no pass/fail signal, making CI less meaningful. 3. Translate inline code comments in codes/c/chapter_backtracking/*.c from Chinese to English to support the English translation effort visible in en/README.md.

Top contributors

• @krahets — 37 commits
• @Phoenix0415 — 8 commits
• @sunshinesDL — 6 commits
• @pengchzn — 6 commits
• @rongyi — 5 commits

Recent commits

• 4935d2d — fix mobile reading media overflow (#1896) (krahets)
• 22b3b56 — fix Ru translation (#1894) (krahets)
• 1d12e2d — Update README translation review copy (#1886) (krahets)
• b01036b — Revisit the English version (#1885) (krahets)
• ae03a16 — docs: sync character encoding translations (#1884) (krahets)
• 56653a2 — Fix formatting of 'list' in documentation (#1883) (beatrix-chan)
• edd13d4 — Update giscus themes (#1879) (krahets)
• dcd4db3 — Update landing page videos (#1878) (krahets)
• 6e600f5 — Add animation player (#1877) (krahets)
• e3c74cf — Sync multilingual versions (#1875) (krahets)

Security observations

• Medium · HTTP Server Without TLS/HTTPS — Dockerfile. The Dockerfile exposes port 8000 and starts a plain Python HTTP server (python -m http.server 8000) with no TLS configuration. All traffic between clients and the server is transmitted in cleartext, making it susceptible to eavesdropping and man-in-the-middle attacks. Fix: Place a reverse proxy (e.g., Nginx or Caddy) with TLS termination in front of the Python HTTP server, or serve static content directly through a web server that supports HTTPS. Never expose a plain HTTP server directly to the internet in production.
• Medium · Use of Outdated / Potentially Vulnerable Base Image — Dockerfile (FROM python:3.10.0-alpine). The Dockerfile uses python:3.10.0-alpine which is a very specific older patch release of Python 3.10. Python 3.10.0 has known security fixes addressed in subsequent patch releases (e.g., CVE fixes in 3.10.x series). Pinning to an old minor version means the image will not receive OS or runtime security patches automatically. Fix: Update the base image to the latest stable patch of the Python 3.10 or 3.12 Alpine image (e.g., python:3.12-alpine) and keep it updated regularly. Consider using a minimal distroless image for production deployments.
• Medium · Pinned but Potentially Outdated Third-Party Dependencies — Dockerfile (RUN pip install mkdocs-material==9.5.5 mkdocs-glightbox). mkdocs-material==9.5.5 and mkdocs-glightbox are pinned (one with a fixed version, one without). mkdocs-material 9.5.5 may have since received security or dependency patches. The unpinned mkdocs-glightbox could resolve to an arbitrary future version with unknown security properties, or conversely never update to receive fixes. Fix: Pin all dependencies to specific, audited versions (including mkdocs-glightbox). Regularly audit dependencies with tools such as pip-audit or Dependabot, and update to patched versions promptly.
• Medium · Container Runs as Root — Dockerfile. The Dockerfile does not specify a non-root USER. By default, Docker containers run as root (UID 0). If the HTTP server or any dependency has a vulnerability that allows code execution, the attacker would have root privileges inside the container, making container escape and privilege escalation easier. Fix: Add a dedicated non-root user to the Dockerfile before the CMD instruction, for example: RUN adduser -D appuser and USER appuser. Ensure the WORKDIR and files are accessible to this user.
• Low · No Security Headers on Served Content — Dockerfile (CMD ["python", "-m", "http.server", "8000"]). The built static site is served via python -m http.server, which does not add any HTTP security headers such as Content-Security-Policy, X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security, or Referrer-Policy. This exposes users to potential clickjacking, MIME-sniffing, and cross-site scripting risks from injected content. Fix: Serve static content via a production-grade web server (e.g., Nginx) configured with appropriate security headers. At minimum add: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Content-Security-Policy, and Referrer-Policy headers.
• Low · Commented-Out Mirror PyPI Index URL — Dockerfile (# ENV PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple). The Dockerfile contains a commented-out environment variable pointing to a third-party Chinese mirror (https://pypi.tuna.tsinghua.edu.cn/simple). If this line is uncommented (e.g., in a fork or CI environment), Python packages would be fetched from an uncontrolled third-party mirror, increasing the risk of dependency confusion or supply-chain attacks. Fix: Remove the commented-out mirror URL from the Dockerfile to avoid accidental activation. If a mirror is required in certain environments, manage this via a separate CI/CD configuration or a requirements file with hash-checking enabled (`pip install --require-

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.