javaevolved.github.io/CONTRIBUTING.md at main · javaevolved/javaevolved.github.io

Contributions are welcome! Content is managed as YAML files — never edit generated HTML.

Adding a new pattern

1. Fork the repo
2. Create a new YAML file in the appropriate content/<category>/ folder (e.g. content/language/my-feature.yaml)
3. Copy content/template.json as a starting point for all required fields (see the snippet schema for details)
4. Update the prev/next fields in adjacent pattern files to maintain navigation
5. Run jbang html-generators/generate.java to verify your changes build correctly
6. Open a pull request

Please ensure JDK version labels only reference the version where a feature became final (non-preview).

Translating the site

The site supports multiple languages. See specs/i18n/i18n-spec.md for the full specification.

Adding a new locale

1. Add the locale to html-generators/locales.properties (e.g. ja=日本語)
2. Create translations/strings/<locale>.yaml with all UI strings translated (copy translations/strings/en.yaml as a starting point)
3. Create content translation files under translations/content/<locale>/<category>/<slug>.yaml
4. Run jbang html-generators/generate.java and verify the build succeeds
5. Open a pull request

Translating content files

Translation files contain only translatable fields — the generator merges them onto the English base at build time. This prevents translated files from diverging structurally from the English source of truth.

A translation file should contain exactly these fields:

title: "Inferencia de tipos con var"
oldApproach: "Tipos explícitos"
modernApproach: "Palabra clave var"
summary: "Usa var para inferencia de tipos..."
explanation: "Desde Java 10, el compilador infiere..."
whyModernWins:
  - icon: "⚡"
    title: "Menos código repetitivo"
    desc: "No es necesario repetir tipos genéricos..."
  - icon: "👁"
    title: "Mejor legibilidad"
    desc: "..."
  - icon: "🔒"
    title: "Igualmente seguro"
    desc: "..."
support:
  description: "Ampliamente disponible desde JDK 10 (marzo 2018)"

Do not include id, slug, category, difficulty, jdkVersion, oldCode, modernCode, prev, next, related, or docs — these are always taken from the English source.

Important: If your text contains colons (:), ensure the value is properly quoted in YAML to avoid parse errors. Always validate with jbang html-generators/generate.java before submitting.