Guides

Guides (Micronaut Maintainer)

Use this skill for standalone tutorial work in micronaut-projects/micronaut-guides. Start from the caller's local Micronaut repository to understand the API, module, or behavior being taught, then do the guide implementation in a current clone of micronaut-guides.

Do not use this skill for ordinary module documentation under src/main/docs/guide; use the docs skill for that work. Do not use it for generic non-Micronaut tutorials.

Goal

Produce a reviewable pull request against micronaut-projects/micronaut-guides with source-backed guide content, validation evidence, and a PDF export of the rendered guide page for maintainers.

Procedure

1. Define the topic from the local repository.
2. Refresh upstream micronaut-guides and deduplicate against existing guides.
3. Inspect current repository conventions before writing.
4. Author the smallest correct guide change.
5. Validate the guide and render the page.
6. Export a PDF and prepare the PR handoff.

1) Define the Topic

• Identify the exact Micronaut feature, module, API, integration, or migration path the guide should teach.
• Read the local implementation, tests, module docs, and examples that prove the behavior.
• Decide the target reader task in one sentence, for example: "Use Micronaut Serialization with a custom serializer in a controller response."
• Prefer a runnable application and tests over prose-only explanation.

2) Refresh and Deduplicate

Work from current upstream facts, not this skill's snapshot:

git clone https://github.com/micronaut-projects/micronaut-guides.git
cd micronaut-guides
git fetch origin
git switch master
git pull --ff-only

Before creating a new guide, inventory guides/*/metadata.json and nearby guide source. Check titles, slugs, tags, categories, apps, base, publish, and guide bodies for duplicates or near-duplicates. Treat publish: false guides as base or partial guides, not public topics, but inspect them when a new guide could reuse them.

If an existing guide already teaches the task, update that guide instead of creating a duplicate. If overlap is ambiguous, stop and ask for maintainer direction.

3) Inspect Current Conventions

Always read these current upstream files before editing:

• README.md
• build.gradle
• buildSrc/src/main/java/io/micronaut/guides/core/Guide.java
• buildSrc/src/main/java/io/micronaut/guides/Category.java
• buildSrc/src/main/resources/guide-metadata.schema.json
• Nearby guides in the same topic family

Use references/repository-workflow.md for clone, branch, build-output, task naming, and validation details. Use references/guide-authoring-conventions.md for metadata, directory layout, macros, placeholders, and base-guide rules.

4) Author the Guide

• Choose a kebab-case slug that matches the reader task and does not collide with existing guide directories.
• Create or update guides/<slug>/metadata.json.
• Use one root AsciiDoc file named <slug>.adoc unless current metadata conventions require asciidoctor.
• Put source under the expected Java, Groovy, and Kotlin layout when the guide supports multiple languages. If the feature is language-specific, set languages in metadata and explain why in the PR.
• For single-app guides, use an app named default. For multi-app guides, mirror existing app-directory patterns and declare each app in metadata.
• Use validated guide macros such as common:, source:, resource:, test:, testResource:, callout:, external:, dependency:, and guideLink: instead of manually duplicating generated paths.
• Use conditional blocks such as :exclude-for-languages: and :exclude-for-build: for language-specific or build-tool-specific text.
• Keep secrets out of source, generated code, rendered HTML, and the PDF. Use placeholders and documented cleanup steps for cloud resources.

5) Validate

Convert the guide slug from kebab-case to lowerCamelCase for dynamic tasks:

./gradlew <guideLowerCamel>Build
./gradlew <guideLowerCamel>RunTestScript

For broad validation or shared infrastructure changes, run:

./gradlew build

Generated applications are under build/code. Rendered HTML and site assets are under build/dist. For cloud, credentialed, or cost-incurring guides, do not run provisioning commands without explicit confirmation; document skipped validation and the reason.