Local Build Failures and Infrastructure Roadblocks for Contributors

[omatheusmesmo]

Description

Contributing to the Jakarta EE specifications repository is currently blocked for local development and verification. A developer cannot run hugo server to verify changes (such as renaming specification directories or updating content) without first manually fixing multiple errors in both the content data and the external theme/layout logic.

Because the provided build.sh is destructive, any local fixes applied to the website/ directory are wiped out on the next build attempt, creating a "Catch-22" where the contributor cannot verify their PR because the environment required to run it is broken.

Root Causes and Detailed Findings

1. Strict YAML Parsing Errors (Duplicate Keys)

Hugo's YAML parser (Go-YAML) fails the build if a key is defined more than once. Several files in the repository contain duplicate keys, likely due to merging different language versions or manual edits.

• Files with Duplicate hide_sidebar:
  • website/content/community/newsletter/index.md
  • website/content/community/newsletter/index.ja.md
  • website/content/community/newsletter/index.zh.md
  • website/content/blogs/_index.ja.md
• Files with Duplicate description:
  • website/content/release/8/_index.zh.md (Two different description values present).

2. Nil Pointer Evaluation in Layouts (File is nil)

The layouts provided by the jakartaee/jakarta.ee repository (which build.sh clones) contain logic that assumes .File is always present. In certain contexts (like list pages or sidebars), this evaluates to nil, causing a hard crash.

• Affected Files:
  • website/layouts/specifications/list.html:152
  • website/layouts/partials/sidebars/specifications.html:45
• The Error: execute of template failed: ...: File is nil; wrap it in if or with: {{ with .File }}{{ .Dir }}{{ end }}.
• **The Problem:**Contributors to this repo (specifications) are forced to fix the other repo's (jakarta.ee) layout code locally just to see their changes.

3. Critical Flaws in build.sh

The root build.sh script, intended to automate the setup, is currently unusable for local development:

• Destructive Reset: The very first command is rm -rf website, which deletes the entire development environment, including any local fixes applied to layouts or Node dependencies.
• Dependency on Production Toolchain: It calls npm run production, which requires webpack to be in the path. On many local machines, npm install inside the script does not correctly link binaries to the shell, leading to sh: line 1: webpack: command not found and an incomplete build.
• Recursive/Nested Directory Logic: In Step 3, the find and cp commands can lead to nested structures (e.g., website/website/content) if the script is run more than once or from slightly different paths.
• Hard Failure at Step 7: The script ends with rm ../static/_redirects. If this file is missing (common in local clones), the script exits with an error code, potentially stopping CI/CD pipelines or local automation.

Impact on PRs (e.g., Issue #881)

When attempting to fulfill a request like "Align Jakarta Validation specification URL with standard naming convention", which involves:

1. Renaming bean-validation/ to validation/.
2. Updating canonical links in validation/4.0/*.html.

A contributor cannot verify if the new URL (/specifications/validation/) renders correctly because Hugo will not start until all the unrelated YAML and Template errors mentioned above are resolved.

Required Actions

1. Cleanup Content: Remove all duplicate YAML keys in the specifications repository (Newsletter, Release 8, and Blogs files).
2. Fix Theme Logic: Submit a PR to jakartaee/jakarta.ee to safely wrap .File.Dir access with {{ with .File }}.
3. Refactor build.sh:
   • Make it non-destructive (e.g., only git clone if the directory is missing).
   • Handle rm failures gracefully using rm -f.
   • Ensure the Webpack build is optional or better documented for local environments.