jakartaee / jakartaee/specifications

Local Build Failures and Infrastructure Roadblocks for Contributors

Open
#883 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
HTML
Stars
140
Forks
91
Avg merge
10d 19h
Merged PRs (30d)
6

Description

## 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.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with build.sh and reproduce the local failure with hugo server, then inspect the listed Markdown files and the affected layout templates. Check how the script handles website removal, dependency setup, nested paths, and missing _redirects. Done means duplicate YAML keys and listed build blockers are addressed, while local specification changes can be verified without destructive resets.

Written by the indexing model from the issue text.

Assessment

Tech stack
html, shell, yaml
Domain
build-system, devops, documentation
Issue type
Refactor
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.