Contributing to Nanolaba Readme Generator

April 27, 2026 · View on GitHub

[ en | ru ]

Contributing to Nanolaba Readme Generator

Thanks for your interest in improving NRG! This document explains how to report issues, propose changes, and get a pull request merged. By participating, you agree to be respectful and constructive — please assume good faith on both sides.

Table of contents

  1. Ways to contribute
  2. Reporting bugs
  3. Proposing features
  4. Security issues
  5. Development setup
  6. Project layout
  7. Building and testing
  8. Coding conventions
  9. Documentation
  10. Commit messages
  11. Pull request checklist
  12. Release process
  13. License

Ways to contribute

  • Report bugs or unexpected behavior via GitHub Issues.
  • Propose features via GitHub Discussions or as an issue with the enhancement label.
  • Improve documentation — README, Javadoc, or examples in nrg/src/test/java/com/nanolaba/nrg/examples/ (these double as documentation samples imported by the README).
  • Submit code — bug fixes, new widgets, or other improvements via pull request.
  • Help others by answering questions in Discussions.

Reporting bugs

Before opening a new issue, please:

  1. Search existing issues to avoid duplicates.
  2. Confirm the bug reproduces against the latest release (or main).
  3. Open a new issue with a clear, descriptive title and include:
    • NRG version, Java version, and operating system.
    • The minimal .src.md template (or code snippet) that reproduces the problem.
    • The exact command or invocation used.
    • Expected vs. actual output (paste both, don't paraphrase).
    • Stack traces or log output, if any (run with --log-level debug or NRG_LOG_LEVEL=debug for more detail).

Proposing features

Open an issue first — even a short one — before writing a feature PR. This avoids duplicated work and lets us discuss scope and design up front. Useful things to include:

  • The problem the feature solves and a concrete use case.
  • A short proposal of the template syntax / CLI flag / API surface.
  • Alternatives you considered.

For larger changes, a discussion thread is often a better starting point than an issue.

Security issues

Do not open a public issue for security reports. Email nrg@nanolaba.com with the subject prefixed [SECURITY]. We will acknowledge receipt and coordinate a fix and disclosure timeline.

Development setup

Prerequisites:

  • Java 8 or higher (Temurin 8 or 17 are what CI uses).
  • Maven 3.6+ (the IntelliJ IDEA bundled distribution works; any standard install does too).
  • Git.

Clone and build:

git clone https://github.com/nanolaba/readme-generator.git
cd readme-generator
mvn install -Dgpg.skip=true

The parent build wires up GPG signing for releases, so local builds without GPG keys will fail at verify. Pass -Dgpg.skip=true (or stop at the package phase) when iterating locally.

Project layout

NRG is a multi-module Maven project:

  • nrg/ — core library and CLI (Main-Class = com.nanolaba.nrg.NRG). Produces a fat jar nrg.jar plus a release zip with nrg.sh / nrg.bat wrappers.
  • nrg-maven-plugin/ — thin Maven plugin (create-files goal) that wraps the CLI.
  • nrg-action/ — GitHub Action distribution.
  • docs/*.src.md — source fragments imported by the top-level README.src.md (the project dogfoods itself: never hand-edit README.md or README.ru.md — change the source template and regenerate).

The generation pipeline is documented at the top of nrg/src/main/java/com/nanolaba/nrg/core/Generator.java and TemplateLine.java; widget contracts live in widgets/NRGWidget.java.

Building and testing

Common commands (run from the repository root):

# Full build, run tests, install to local Maven repo
mvn install -Dgpg.skip=true

# Compile core only
mvn -pl nrg compile

# Run all tests in the core module
mvn -pl nrg test

# Run a single test class or method
mvn -pl nrg test -Dtest=TableOfContentsWidgetTest
mvn -pl nrg test -Dtest=TableOfContentsWidgetTest#methodName

# Mutation testing (PIT) — opt-in
mvn -pl nrg test -Dpit.skip=false

When changing widget behavior or anchor generation, please also run the focused tests (TableOfContentsWidgetTest, TableOfContentsWidgetSlugifyTest, ImportWidgetTest, etc.) — they exercise the most fragile logic in the codebase.

CI runs mvn verify against JDK 8 and JDK 17 on every push and pull request to main. Your changes need to pass on both.

Coding conventions

Language level — Java 8. No var, no records, no switch expressions, no text blocks. Streams and lambdas are fine and encouraged where they read well.

Logging. Use the in-house com.nanolaba.logging.LOG (NOT SLF4J). Pattern is LOG.debug("msg {}", arg).

Checked exceptions in lambdas. Wrap with com.nanolaba.sugar.Code.run(...) rather than try/catch boilerplate.

Constants for property names live in NRGConstants (PROPERTY_LANGUAGES, PROPERTY_DEFAULT_LANGUAGE, etc.). Don't hard-code "nrg.xxx" strings in widgets.

Class-level Javadoc on every new class. Match the style of nrg/src/main/java/com/nanolaba/nrg/core/json/MinimalJsonParser.java: a short paragraph stating what the class is and why it exists, followed by a <p> paragraph for scope, invariants, or non-obvious behavior. Add Javadoc on non-trivial methods too (subtle algorithms, multi-style branches, contract corner cases) — skip simple getters/setters and self-explanatory delegators. Document the why and edge cases, not the what; well-named identifiers already say what.

Inspect surrounding code when adding a new class. Before opening a PR, scan it for low-effort cleanups in the same pass: prefer proper imports over new java.xxx.Yyy() style fully-qualified names, drop redundant intermediate variables, remove dead branches.

Tests. JUnit 5 (org.junit.jupiter). Place new tests under nrg/src/test/java/. If you add a test under the examples/ package, remember it doubles as a documentation sample (it may be imported by docs/Advanced.src.md and rendered into the README) — regenerate the README if you rename or restructure such files.

Defensive code. Don't add validation, error handling, or fallbacks for scenarios that can't happen. Trust internal callers; only validate at system boundaries (CLI input, external files, network). Don't introduce backwards-compatibility shims when changing internal APIs.

Documentation

The top-level README.md and README.ru.md are generated from README.src.md (which ${widget:import}s fragments under docs/). Workflow when documentation needs to change:

  1. Edit the relevant .src.md source — never the generated .md.
  2. Regenerate locally: 
    nrg -f README.src.md
# or, if not installed:
java -jar nrg/target/nrg.jar -f README.src.md
  3. Commit both the .src.md change and the regenerated .md files in the same commit.

CI runs the generator in --check mode and fails the build if the committed .md files don't match what the source would regenerate.

Commit messages

Follow the convention used in the existing history (a Conventional Commits flavour):

<type>: <short summary>

<optional body explaining why, not what>

Common types: feat, fix, docs, refactor, test, chore, build, revert. Keep the subject line under ~70 characters and write in the imperative mood ("add X", not "added X"). Reference issues in the subject when applicable: feat: \${widget:asset} per-language widget (#42).

Pull request checklist

Before submitting:

  • Branch is up to date with main.
  • Code compiles cleanly: mvn -pl nrg compile.
  • All tests pass: mvn install -Dgpg.skip=true.
  • New behavior has unit tests (and, where it touches widget output, an integration sample).
  • New or changed public classes/methods have Javadoc.
  • If you touched template-driven docs, the generated README.md / README.ru.md have been regenerated and committed alongside the source.
  • Commit messages follow the convention above.
  • No unrelated changes are bundled in (no formatting churn outside the modified files, no IDE settings, no .idea/, .claude/, or local plan files).

When opening the PR:

  • Describe what changed and why, not just the diff.
  • Link the issue it resolves (Closes #123).
  • Include before/after examples if the change affects rendered output.

We aim to give first feedback within a few days. If you don't hear back in a week, feel free to ping the PR.

Release process

Releases are cut from main by maintainers. Versioning follows Semantic Versioning. Contributors don't need to touch pom.xml versions in feature PRs — that happens at release time.

License

By contributing, you agree that your contributions will be licensed under the project's Apache License 2.0.

If you're contributing on behalf of an employer, please ensure you have permission to do so under your employment agreement.

Thanks again for helping make Nanolaba Readme Generator (NRG) better! For anything not covered here, open a discussion or reach out at nrg@nanolaba.com.