Onboarding: doocs/jvm

Generated by RepoPilot · 2026-05-07 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/doocs/jvm shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

WAIT — Single-maintainer risk — review before adopting

• Last commit 3w ago
• 13 active contributors
• CC-BY-SA-4.0 licensed
• CI configured
• ⚠ Single-maintainer risk — top contributor 80% of recent commits
• ⚠ Non-standard license (CC-BY-SA-4.0) — review terms
• ⚠ No test directory detected

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

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live doocs/jvm repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/doocs/jvm.

What it runs against: a local clone of doocs/jvm — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in doocs/jvm | Confirms the artifact applies here, not a fork | | 2 | License is still CC-BY-SA-4.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 49 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>doocs/jvm</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of doocs/jvm. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/doocs/jvm.git
#   cd jvm
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of doocs/jvm and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "doocs/jvm(\\.git)?\\b" \\
  && ok "origin remote is doocs/jvm" \\
  || miss "origin remote is not doocs/jvm (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(CC-BY-SA-4\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"CC-BY-SA-4\\.0\"" package.json 2>/dev/null) \\
  && ok "license is CC-BY-SA-4.0" \\
  || miss "license drift — was CC-BY-SA-4.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "docs/.vitepress/config.mts" \\
  && ok "docs/.vitepress/config.mts" \\
  || miss "missing critical file: docs/.vitepress/config.mts"
test -f "docs/00-quickstart.md" \\
  && ok "docs/00-quickstart.md" \\
  || miss "missing critical file: docs/00-quickstart.md"
test -f "docs/01-jvm-memory-structure.md" \\
  && ok "docs/01-jvm-memory-structure.md" \\
  || miss "missing critical file: docs/01-jvm-memory-structure.md"
test -f "docs/02-hotspot-jvm-object.md" \\
  && ok "docs/02-hotspot-jvm-object.md" \\
  || miss "missing critical file: docs/02-hotspot-jvm-object.md"
test -f "package.json" \\
  && ok "package.json" \\
  || miss "missing critical file: package.json"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 49 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~19d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/doocs/jvm"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

A comprehensive Chinese-language knowledge hub documenting JVM (Java Virtual Machine) internals through 10 focused markdown documents covering memory structure, garbage collection, class loading, and performance tuning. It's built as a Vitepress static site (deployed to jvm.doocs.org) that aggregates the most critical low-level JVM concepts without aiming for exhaustive coverage. Flat document structure: docs/ directory contains 10 sequential markdown files (01-jvm-memory-structure.md through 10-class-loader.md) plus index and quickstart, all wired into a Vitepress site config at docs/.vitepress/config.mts. GitHub Actions workflows in .github/workflows/ handle image compression, Cloudflare/Vercel deployment, and PR checks. Single Main.java file suggests minimal code examples.

Who it's for

Java developers and engineers preparing for technical interviews, studying JVM internals for performance optimization, or seeking a curated alternative to reading the full JVMTI specification and Zhou Zhiming's textbook. Contributors are likely members of the Doocs open-source community building Chinese technical education content.

Maturity & risk

Moderately mature and stable. The repo has a clean CI/CD setup (GitHub Actions for Cloudflare deployment, Vercel fallback), is part of an established organization (Doocs), but shows limited recent activity indicators in the provided metadata. The core content (10 docs files) appears settled; primary maintenance is likely doc updates rather than feature development.

Low risk for consumers, moderate for active contribution. Single-language content (Chinese) limits contributor pool. Dependency count is minimal (vitepress@^2.0.0-alpha.17, wrangler@^4.83.0), but vitepress is pre-release; the cc-by-sa license requires derivative works to maintain attribution/share-alike terms. No automated tests visible in the file list (only docs files and build scripts).

Active areas of work

Primary activity appears to be maintaining documentation content and deployment infrastructure. The package.json lists vitepress at pre-alpha version (^2.0.0-alpha.17), indicating the site may be tracking upstream Vitepress changes. GitHub workflows (compress.yml, deploy.yml) suggest active image and asset optimization for the static site.

Get running

Clone the repo and install with pnpm: git clone https://github.com/doocs/jvm.git && cd jvm && pnpm install. Start the dev server: pnpm run docs:dev (runs vitepress dev server on docs/). Build for production: pnpm run docs:build. Preview: pnpm run docs:preview.

Daily commands: Development: pnpm run docs:dev (starts Vitepress dev server with HMR on localhost:5173 typically). Production build: pnpm run docs:build (outputs dist/). Deployment to Cloudflare: pnpm run deploy:cf (runs build then wrangler deploy per deploy.yml).

Map of the codebase

• docs/.vitepress/config.mts — Site configuration and navigation structure; defines how all documentation is organized and deployed to production.
• docs/00-quickstart.md — Entry point for new readers; establishes foundational concepts and learning path for JVM fundamentals.
• docs/01-jvm-memory-structure.md — Core architectural document explaining JVM memory layout (heap, stack, method area); prerequisite for all other JVM topics.
• docs/02-hotspot-jvm-object.md — Details object representation in HotSpot; essential for understanding garbage collection and memory allocation strategies.
• package.json — Declares build pipeline (VitePress) and deployment targets (Cloudflare Workers); controls how content reaches production.
• docs/10-class-loader.md — Explains class loading mechanism and loader hierarchy; fundamental to understanding runtime class instantiation.

How to make changes

Add a new JVM topic chapter

1. Create new markdown file in docs/ with sequential number prefix (e.g., docs/11-new-topic.md), following existing format with headings and cross-references (docs/11-new-topic.md)
2. Update docs/.vitepress/config.mts sidebar array to include the new file path and display title in correct sequence (docs/.vitepress/config.mts)
3. Add internal links from related existing docs (e.g., docs/01-jvm-memory-structure.md) to the new topic for discoverability (docs/01-jvm-memory-structure.md)
4. Run pnpm run docs:dev locally to verify rendering and navigation work correctly (package.json)

Add a new visual diagram or image

1. Save image file (PNG/JPG) to images/ directory with descriptive name (e.g., images/new-gc-flow.png) (images/new-gc-flow.png)
2. Reference the image in the appropriate markdown file using relative path: (docs/04-hotspot-gc.md)
3. Commit both the image and updated markdown to version control for CI/CD to compress and optimize (.github/workflows/compress.yml)

Deploy updated documentation to production

1. Commit changes to main branch; GitHub Actions automatically triggers the deploy workflow (.github/workflows/deploy.yml)
2. Workflow builds static site via vitepress build docs and outputs to dist/ (package.json)
3. Cloudflare Workers deployment runs via wrangler CLI, publishing to jvm.doocs.org using worker.js as entry (wrangler.toml)
4. Monitor deployment logs in GitHub Actions to confirm successful publish and site is live (.github/workflows/deploy.yml)

Why these technologies

• VitePress — Modern static site generator for fast, SEO-friendly documentation with minimal configuration and excellent markdown support
• Cloudflare Workers — Global edge deployment for sub-10ms latency; serverless model eliminates infrastructure management while supporting dynamic routing via worker.js
• pnpm — Stricter dependency management than npm; faster installs via hard links; ensures reproducible builds across CI/CD environments
• GitHub Actions — Native CI/CD integrated with repo; free for public projects; automates compression, building, and deployment workflows

Trade-offs already made

• Static site generation (VitePress) instead of dynamic server

  • Why: Content rarely changes; prioritizes performance, simplicity, and cost
  • Consequence: No real-time content updates; all changes require rebuild and redeploy cycle (~30–60s)

• Markdown-only format instead of interactive tutorials

  • Why: Lowers maintenance burden; content remains version-controlled and reviewable
  • Consequence: Readers cannot run code examples directly; limited hands-on learning engagement

• Cloudflare Workers + GitHub Pages as primary targets

  • Why: Zero infrastructure cost; global CDN coverage; simple one-line deploy
  • Consequence: Vendor lock-in to Cloudflare ecosystem; limited customization of runtime environment

• Single source of truth: GitHub main branch

  • Why: Simplifies collaboration, review, and audit trails
  • Consequence: No staging environment; mistakes in main are immediately visible to readers

Non-goals (don't propose these)

• Interactive JVM bytecode simulator or debugger
• Real-time performance benchmarking or profiling tools
• Multi-language localization (content is Chinese-only)
• User authentication, comments, or community features
• API endpoints or database backend
• Windows/macOS/Linux native application

Traps & gotchas

Vitepress is pinned to pre-release alpha (^2.0.0-alpha.17)—breaking changes possible without major version bump. Chinese-only content means build/deploy workflows use locale-specific path assumptions. The Main.java file is present but unused in the build; unclear if it's a legacy test file or stub. Cloudflare Workers deployment (deploy:cf script) requires valid wrangler.toml and Cloudflare API token in CI environment—missing token will fail silently if not configured in GitHub Secrets. No local .env.example or secrets documentation visible.

Architecture

Concepts to learn

• Generational Garbage Collection — HotSpot's GC strategy (doc 04) is built entirely on generational assumptions—young/old spaces; weak generational hypothesis; card marking—understanding this is mandatory for tuning GC performance
• Memory Tagging Extension (Mark Word) — HotSpot objects (doc 02) encode locking state, GC generation, and hashCode in the mark word; critical for understanding synchronization overhead and object layout
• Class Loading and the Bootstrap Problem — Class loaders (doc 10) form a hierarchical trust model; understanding parent-delegation and why 'new' requires the bytecode in memory is core to deployment, dependency conflicts, and reflection
• Tri-color Marking (GC Algorithm) — CMS and G1 collectors (docs 03–04) use tri-color marking (white/gray/black objects) to achieve concurrent GC; essential for tuning pause times in low-latency systems
• Object Allocation and TLAB (Thread-Local Allocation Buffer) — Doc 05 covers allocation strategies; TLAB eliminates synchronization on heap pointer bumping per thread—understanding this explains why allocation is 'nearly free' in HotSpot
• Constant Pool Resolution and Runtime Constant Pool — Class files (doc 07) contain symbolic references; the runtime constant pool (doc 08–09) resolves these to direct object pointers—this lazy binding is why first-time method calls are slower
• Escape Analysis and Scalar Replacement — JIT compiler optimization (doc 06) can eliminate heap allocation if an object never escapes the method—critical for understanding why some allocations have zero GC cost despite appearing in bytecode

Related repos

• doocs/advanced-java — Sibling Doocs project covering distributed systems, concurrency, and microservices—natural follow-up for engineers who master JVM internals and need to apply them in large-scale systems
• openjdk/jdk — Official OpenJDK source repository; the authoritative reference implementation for HotSpot VM behavior documented in this repo's 10 modules
• arthas-source/Arthas — Alibaba's JVM diagnostic tool; practical complement to this repo's theoretical knowledge—lets you inspect GC logs, thread dumps, and class metadata in live JVMs
• doocs/source-code-hunter — Another Doocs project analyzing common framework source code; readers of this JVM repo often want to understand how frameworks (Spring, Hibernate) leverage JVM features
• dunwu/jvm-tutorial — Alternative JVM tutorial in Chinese with similar scope; useful for comparison if readers want a different pedagogical approach or more code examples

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 interactive code examples and runnable JVM demos in docs/

The repo contains comprehensive JVM theory docs but lacks executable code examples. Adding a docs/examples/ directory with annotated Java programs (e.g., garbage collection behavior, class loading mechanics, memory layout visualization) would help readers validate concepts hands-on. This aligns with the repo's educational mission and could reference Main.java as a template.

• [ ] Create docs/examples/ directory with subdirectories for each major topic (gc, classloader, memory)
• [ ] Add 3-5 focused Java example files (e.g., GCBehaviorDemo.java, ClassLoaderDemo.java) with detailed comments
• [ ] Update relevant docs files (03-gc-algorithms.md, 10-class-loader.md) to link and reference these examples
• [ ] Add a new docs/examples.md or update docs/00-quickstart.md with instructions on compiling and running the demos

Create a comprehensive image alt-text audit and accessibility improvements in docs/

The repo has 15+ images in images/ directory used across markdown files (jvm-memory-structure.jpg, gc algorithms diagrams, etc.), but many likely lack proper alt-text for accessibility. This is a high-value improvement for SEO, accessibility compliance, and user experience for screen reader users.

• [ ] Audit all .md files in docs/ for image references and check for missing or weak alt-text
• [ ] Update image markdown syntax in docs files to include descriptive alt-text (e.g., ![JVM Memory Structure showing heap, stack, and metaspace regions](../images/jvm-memory-structure.jpg))
• [ ] Verify all 15+ images in images/ are referenced with proper alt-text: favicon variations, CMS diagram, mark-and-sweep, etc.
• [ ] Add a note to CONTRIBUTING.md (if exists) or README about alt-text requirements for future contributions

Add GitHub Actions workflow for broken link detection in VitePress docs

The repo has a .github/workflows/ directory with deploy and compress workflows, but lacks automated broken link checking. With VitePress as the doc framework, a workflow to validate internal/external links in built docs would catch regressions early. This is specific to the repo's VitePress v2 setup and build pipeline.

• [ ] Create .github/workflows/linkcheck.yml to run after vitepress build completes
• [ ] Use a tool like github-action-broken-links-checker or lychee to validate links in the generated site
• [ ] Configure the workflow to check both internal markdown links and external HTTP(S) references
• [ ] Add the workflow trigger to the existing deploy.yml or run it on PRs to docs/** changes

Good first issues

• Add English translations to any of the 10 core markdown documents (docs/01-.md through docs/10-.md) to expand the audience beyond Chinese speakers—start with docs/03-gc-algorithms.md as it has the most universal appeal
• Create a glossary/index document (docs/11-glossary.md) mapping JVM terminology (e.g., 'mark-and-sweep', 'card marking', 'young generation') to their definitions and cross-references to main docs, since none exists yet
• Add runnable code examples alongside Main.java—create a examples/ folder with minimal HelloWorld.java and JVMArgs.java demonstrating key concepts from docs 05-06 (memory allocation, GC tuning); wire into Vitepress config to show in sidebars

Top contributors

• @yanglbme — 80 commits
• @dependabot[bot] — 4 commits
• @kenny — 2 commits
• @Oliverwqcwrw — 2 commits
• @JoeMinty — 2 commits

Recent commits

• a10d562 — chore: upgrade deps (yanglbme)
• 02fd83b — chore: upgrade deps (yanglbme)
• b0ad4b2 — chore: deploy to cloudflare workers (yanglbme)
• db6b717 — chore: update gh actions (yanglbme)
• 569da9d — chore: use pnpm (yanglbme)
• a075af6 — chore: auto compress images (yanglbme)
• d8098b8 — chore: auto compress images (yanglbme)
• 1a09cd8 — chore: auto compress images (yanglbme)
• b534137 — chore: auto compress images (yanglbme)
• 7b21a94 — chore: upgrade vitepress (yanglbme)

Security observations

This is a documentation/knowledge base repository with relatively low security risk. The main concerns are dependency management practices: use of alpha versions (VitePress), lack of automated vulnerability scanning in CI/CD, and missing security headers in the Cloudflare Worker deployment. The codebase contains no apparent hardcoded secrets, injection vulnerabilities, or database interactions. Recommendations focus on updating dependencies, implementing automated security checks in workflows, and adding HTTP security headers for the deployed application.

• High · Outdated VitePress Dependency — package.json - devDependencies. The project uses vitepress@^2.0.0-alpha.17, which is an alpha release. Alpha versions are unstable and may contain unpatched security vulnerabilities. Production deployments should use stable, released versions. Fix: Upgrade to the latest stable VitePress release (v2.x or later stable version). Use 'pnpm update vitepress' to get the latest stable version.
• Medium · Wrangler Dependency Outdated — package.json - devDependencies. wrangler@^4.83.0 may have known vulnerabilities depending on the current date. Cloudflare Wrangler is a critical tool for deployment. Ensure it's kept up-to-date with the latest security patches. Fix: Regularly update wrangler using 'pnpm update wrangler' and monitor for security advisories from Cloudflare and npm security database.
• Medium · No Package Lock Integrity Verification — .github/workflows/*.yml, package.json. While pnpm-lock.yaml exists, there's no evidence of lock file verification in CI/CD pipelines. The wrangler.toml and worker.js files suggest Cloudflare Workers deployment without visible security checks. Fix: Add 'pnpm install --frozen-lockfile' in CI/CD pipelines to ensure lock file integrity. Implement package signature verification in deployment workflows.
• Low · Missing Security Headers Configuration — worker.js. The project deploys to Cloudflare Workers (via worker.js and wrangler.toml), but no visible security headers configuration (CSP, X-Frame-Options, etc.) is present in the worker script. Fix: Add comprehensive security headers to the Cloudflare Worker response: Content-Security-Policy, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Strict-Transport-Security.
• Low · No DEPENDENCY Vulnerability Scanning — .github/workflows/. No evidence of automated dependency vulnerability scanning (e.g., npm audit, Snyk, or GitHub Dependabot) in the CI/CD workflows. Fix: Add 'pnpm audit' to CI/CD pipeline or enable GitHub's Dependabot for automated vulnerability detection. Configure automatic updates for critical vulnerabilities.
• Low · Permissive Package Manager Version — package.json - devDependencies. package.json uses vitepress@^2.0.0-alpha.17 and wrangler@^4.83.0 with caret (^) ranges, allowing automatic minor and patch updates that could introduce breaking changes or vulnerabilities. Fix: Use more restrictive version constraints (e.g., ~4.83.0 for patch-only updates) or pin exact versions for critical dependencies. Implement semantic versioning review process.

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.