Update AGENTS.md for AI bots

Author: vogella

AGENTS.md

@@ -1,330 +1,72 @@
-# Agent Instructions for www.eclipse.org-eclipse
-
-## Repository Overview
-
-This is the **Eclipse Project Website and New & Noteworthy (N&N) Repository**. It contains the public-facing website content for the Eclipse Platform, SWT, JDT, PDE, and Equinox projects, hosted at https://www.eclipse.org/eclipse/.
-
-**Repository Statistics:**
-- Size: ~318MB, 3,856 files, 352 directories
-- Primary Content: 475 HTML files, 32 Markdown files, 8 shell/Perl scripts
-- Languages: Markdown, HTML, JavaScript, CSS, PHP, Bash, Perl
-- No build tools required (static website with dynamic JS rendering)
-
-**GitHub Repository:** https://github.com/eclipse-platform/www.eclipse.org-eclipse
-
-## Critical: Trust These Instructions
-
-**Always trust and follow these instructions first.** Only search the codebase if information here is incomplete or appears incorrect. The instructions below have been validated and will save significant exploration time.
-
-## Repository Structure
-
-### Root Directory Files
-- `README.md` - Basic repository overview and contribution instructions
-- `index.html` - Main Eclipse project landing page
-- `project.js` - JavaScript for dynamic page generation and markdown rendering
-- `project.css`, `default_style.css` - Styling for the website
-- `eclipse.svg` - Eclipse logo
-- `Eclipse-website-local-server.launch` - Eclipse launch configuration for local preview
-
-### Key Directories
-
-**`news/`** - New and Noteworthy content (MOST IMPORTANT for contributions)
-- `news/4.x-template/` - Template for new releases (DO NOT modify directly)
-- `news/4.36/`, `news/4.37/`, `news/4.38/`, `news/4.39/` - Release-specific N&N content
-- `news/instructions.md` - Detailed authoring guidelines for N&N entries
-- `news/scripts/` - Automation scripts for N&N management
-
-Each release folder (e.g., `news/4.37/`) contains:
-- `index.md` - Overview with links to component pages
-- `platform.md` - Platform and Equinox news
-- `jdt.md` - Java Development Tools news
-- `pde.md` - Plug-in Development Environment news
-- `platform_isv.md` - New APIs for Platform/SWT/Equinox
-- `acknowledgements.md` - Contributors list (auto-generated)
-- `images/` - Screenshots and diagrams (PNG format)
-
-**`development/`** - Historical plans, release notes, acknowledgements (20,480 files)
-- Mostly legacy HTML/PHP files for older releases
-- `development/scripts/readme/` - Scripts for generating README files
-
-**`swt/`** - SWT (Standard Widget Toolkit) documentation
-- FAQ, examples, tools, and community pages
-
-**`templates/`** - HTML templates for page generation
-
-**`markdown/`** - Markdown rendering infrastructure
-
-**`.github/workflows/`** - CI/CD automation (see Validation section)
-
-## Content Types and Workflows
-
-### New & Noteworthy (N&N) Entries
-
-**When to Edit:** Adding/modifying features for upcoming Eclipse releases
-
-**Markdown Flavors Supported:**
-- Markdown 1.0
-- CommonMark 0.31
-- GitHub Flavored Markdown 0.29
-
-**File Locations:**
-- Edit files in `news/<version>/` where `<version>` is like `4.37`, `4.38`, etc.
-- **Never edit** `news/4.x-template/` except to update the template itself
-
-**N&N Entry Structure (Template):**
-```markdown
-### Feature Title in Title Case
-<!-- Optional link(s) to issues or PRs as invisible comment -->
-<details>
-<summary>Contributors</summary>
-
-- [Contributor Name](https://github.com/username)
-</details>
-
-Feature description goes here.
-Use active voice ("you" not "the user").
-Use backticks for commands: `Quick Fix`, `Ctrl+1`, `Preferences > General > Keys`.
-
-![Descriptive label](images/feature-image.png)
-```
-
-**Image Requirements:**
-- Format: PNG only
-- Location: `news/<version>/images/`
-- Naming: lowercase, hyphen-separated (e.g., `terminal-console.png`)
-- Size: Crop to focus on feature, avoid excessive size
-- Alt text: Add meaningful description
-
-**Style Guidelines:**
-- Titles: Title Case, no trailing punctuation
-- Descriptions: Complete sentences with punctuation
-- Voice: Active voice, say "you" not "the user"
-- Emphasis: Use `backticks` for UI elements/commands; prefer **bold** over _italics_
-- Line breaks: Start each sentence on new line for easier editing
-
-### Scripts and Automation
-
-**Location:** `news/scripts/`
-
-**1. applyTemplate.sh** - Initialize new release folder
+# Eclipse Project New & Noteworthy (N&N)
+
+## Project Overview
+This repository contains the public-facing website content for the Eclipse Platform, SWT, JDT, PDE, and Equinox projects, hosted at [eclipse.org/eclipse](https://www.eclipse.org/eclipse/). 
+It primarily serves as the home for **New & Noteworthy (N&N)** documentation for each Eclipse release.
+
+The website is a **static site with dynamic client-side rendering**. It uses `project.js` to parse custom HTML attributes and render Markdown content into the common Eclipse website template.
+
+## Key Technologies
+- **Languages:** HTML, CSS, JavaScript, Markdown, Bash
+- **Rendering:** Custom JavaScript (`project.js`) for template injection and Markdown rendering.
+- **Automation:** Bash and Perl scripts for release management and validation.
+- **CI/CD:** GitHub Actions for contributor acknowledgement management.
+
+## Project Structure
+- `news/`: **Main content area.** Contains release-specific folders (e.g., `4.37/`, `4.38/`).
+  - `<version>/index.md`: Release overview.
+  - `<version>/{platform,jdt,pde,platform_isv}.md`: Component-specific N&N entries.
+  - `<version>/images/`: Screenshots (PNG only).
+  - `4.x-template/`: Template used to initialize new release folders.
+  - `scripts/`: Automation for release initialization (`applyTemplate.sh`) and validation.
+- `project.js`: Core logic for dynamic rendering and template consistency.
+- `development/`: Historical plans, release notes, and acknowledgements.
+- `swt/`: SWT-specific documentation and community pages.
+- `templates/`: HTML templates for page generation.
+
+## Workflows
+
+### 1. New & Noteworthy (N&N) Authoring
+N&N entries are authored in **Markdown** (CommonMark or GFM).
+- **Location:** `news/<version>/<component>.md`.
+- **Images:** PNG format only, stored in `news/<version>/images/`.
+- **Template:** Each entry follows a specific structure:
+  ```markdown
+  ### Feature Title in Title Case
+  <details><summary>Contributors</summary>
+  - [Name](https://github.com/username)
+  </details>
+  Feature description using active voice ("you").
+  ![Alt text](images/feature-image.png)
+  ```
+
+### 2. Creating a New Release Folder
+To initialize the folder for a new release (e.g., 4.40):
 ```bash
 cd news/scripts
 ./applyTemplate.sh 4.40 2025-12
 ```
-- Creates `news/4.40/` from template
-- Replaces `4.x` with `4.40` and `YYYY-MM` with `2025-12`
-- **Exits with error if directory already exists**
-
-**2. Validation Scripts** (Legacy - for HTML files)
-- `w3cValidateHtmlFile.sh <file>` - Validates single HTML file via W3C service
-- `validateHtmlNewsRepo.sh <news-dir>` - Validates all N&N HTML files
-- `validateHtmlDocBundle.sh <doc-repo-path>` - Validates doc bundle HTML
-
-**Note:** Current N&N uses Markdown (not HTML), so HTML validation scripts are for legacy content only.
-
-**3. Perl Scripts** (Legacy - for copying to doc bundles)
-- `copyNewsToDocBundle.pl` - Copies HTML news to eclipse.platform.common bundles
-- `parseHtml.pl` - Extracts and copies images
-- **Requires:** Perl with `HTML::TokeParser::Simple` module
-- **Usage:** Only when syncing to separate documentation repositories
-
-## GitHub Actions Workflows
-
-**Location:** `.github/workflows/`
-
-### 1. checkAcknowledgements.yml
-- **Trigger:** Pull requests modifying `news/*/acknowledgements.md`
-- **Purpose:** Validates contributor name consistency
-- **Checks:** Each GitHub profile has only one name variant
-- **Action:** Fails if multiple names found for same profile
-
-### 2. generateAcknowledgements.yml
-- **Trigger:** Manual workflow dispatch
-- **Input:** Eclipse version (e.g., `4.36`)
-- **Purpose:** Auto-generates contributor lists from git history
-- **Process:**
-  1. Queries all Eclipse TLP repositories
-  2. Collects commits between release tags
-  3. Excludes bot accounts
-  4. Creates/updates `acknowledgements.md`
-  5. Opens PR with results
-- **Note:** Reuses existing names from acknowledgements file when available
-
-### 3. updateRelease.yml
-- **Trigger:** New milestone created with "Release" in description
-- **Purpose:** Automatically prepares new release folder
-- **Process:**
-  1. Runs `applyTemplate.sh` with milestone title and date
-  2. Creates PR for review
-- **Example:** Milestone "4.40" due "2025-12-15" → creates `news/4.40/`
-
-## Validation and Testing
-
-**No traditional build or test suite exists.** This is a static website repository with client-side JavaScript rendering.
-
-### Pre-Commit Validation Steps
-
-1. **Markdown Syntax:** Ensure valid Markdown (all flavors supported)
-2. **Image References:** Verify all `![...](images/...)` paths exist
-3. **Contributor Links:** Validate GitHub profile URLs format: `https://github.com/username`
-4. **Backticks for UI:** Use backticks for commands, shortcuts, preference paths
-
-### Local Preview
-
-Use the Eclipse launch configuration:
-1. Open in Eclipse IDE
-2. Run: `Run Configurations > Eclipse Applications > Eclipse-website-local-server`
-3. Requires: Eclipse with Oomph HTTPServer support, Java 21
-4. Opens browser to `localhost` serving website content
-5. Refresh browser (Ctrl+F5) after changes
-
-**Alternative (without Eclipse):**
-- Any HTTP server serving static files works
-- JavaScript in `project.js` handles markdown rendering dynamically
-- No build step required
-
-### CI Validation
-
-Pull requests trigger:
-- `checkAcknowledgements.yml` if modifying acknowledgements
-- No other automated checks currently run on PRs
-
-## Common Tasks and Commands
-
-### Creating New Release Folder
-```bash
-cd news/scripts
-./applyTemplate.sh 4.40 2025-12
-# Creates news/4.40/ with all template files
-# Replaces placeholders automatically
-```
-
-### Adding N&N Entry
-
-1. Navigate to appropriate file:
-   - Platform/Equinox features → `news/<version>/platform.md`
-   - JDT features → `news/<version>/jdt.md`
-   - PDE features → `news/<version>/pde.md`
-   - New APIs → `news/<version>/platform_isv.md`
-
-2. Add entry following template (see N&N Entry Structure above)
-
-3. Add images to `news/<version>/images/` if needed
-
-4. Uncomment section headers if adding to new section
-
-### Validating HTML Files (Legacy)
-```bash
-cd news/scripts
-./w3cValidateHtmlFile.sh ../4.37/index.html
-# Uses W3C validator web service
-# Requires curl and internet connection
-```
-
-### Checking Repository Status
-```bash
-git status
-git diff
-# Always check changes before committing
-```
-
-## File Type Reference
-
-**Markdown Files (`.md`):**
-- Current format for N&N entries (as of 4.36+)
-- Rendered dynamically by `project.js`
-
-**HTML Files (`.html`):**
-- Legacy N&N entries (pre-4.36)
-- Static website pages
-- Generated acknowledgements (some versions)
-
-**JavaScript (`.js`):**
-- `project.js` - Core website functionality, markdown rendering
-
-**CSS (`.css`):**
-- `project.css`, `default_style.css` - Website styling
-
-**Shell Scripts (`.sh`):**
-- Automation for release management and validation
-
-**Perl Scripts (`.pl`):**
-- Legacy HTML content processing
-
-## Environment Setup
-
-**Required Tools:**
-- Git (for version control)
-- Text editor (for Markdown/HTML editing)
-- Web browser (for preview)
-
-**Optional Tools:**
-- Eclipse IDE with Oomph HTTPServer (for launch configuration)
-- Java 21 (for Eclipse launch)
-- curl (for HTML validation scripts)
-- Perl with HTML::TokeParser::Simple (for legacy doc bundle sync)
-
-**No installation/build commands needed** - this is a static content repository.
-
-## Important Constraints
-
-### What NOT to Do
-
-1. **DO NOT modify `news/4.x-template/`** unless updating template itself
-2. **DO NOT commit large images** - optimize PNGs before adding
-3. **DO NOT use absolute paths** - keep relative paths (e.g., `images/file.png`)
-4. **DO NOT add HTML to new N&N entries** - use Markdown (except inline HTML if absolutely necessary)
-5. **DO NOT manually edit `acknowledgements.md`** - auto-generated via workflow (except fixing errors)
-6. **DO NOT link to GitHub issues in N&N entries** - guidelines prohibit external links
-
-### Section Commenting
-
-Many sections in template files are commented out:
-```markdown
-<!--
----
-## Section Name
--->
-```
-**When adding first entry to section:** Remove the `<!-- -->` comment markers surrounding the section header.
-
-## Troubleshooting
-
-### applyTemplate.sh fails with "Directory exists"
-- **Cause:** Release folder already created
-- **Solution:** Choose different version number or manually modify existing folder
-
-### Images not displaying in preview
-- **Check:** Image file exists in `news/<version>/images/`
-- **Check:** Filename matches exactly (case-sensitive)
-- **Check:** Relative path is correct: `images/filename.png`
-
-### Acknowledgements validation fails
-- **Cause:** Same GitHub profile has different name variants
-- **Solution:** Edit `acknowledgements.md` to use single consistent name
-
-### HTML validation errors (legacy)
-- **Check:** W3C validator service is accessible
-- **Note:** Only relevant for old HTML files, not current Markdown content
-
-## Key References
-
-- **N&N Instructions:** `news/instructions.md` (comprehensive authoring guide)
-- **Script Instructions:** `news/scripts/instructions.txt` (detailed script usage)
-- **Contributing Guide:** https://github.com/eclipse-platform/.github/blob/main/CONTRIBUTING.md
-- **Eclipse Website:** https://www.eclipse.org/eclipse/
-- **Published N&N:** https://www.eclipse.org/eclipse/news/
-
-## Summary for Quick Reference
-
-**Repository Purpose:** Eclipse project website and New & Noteworthy documentation
-
-**Most Common Edits:** Adding entries to `news/<version>/*.md` files
-
-**No Build Required:** Static website with JavaScript rendering
-
-**Validation:** Manual review + automated acknowledgements checking
-
-**Preview:** Use Eclipse launch config or any HTTP server
-
-**Key Principle:** Follow N&N template exactly, use Markdown, optimize images, test locally before PR
+This script copies `4.x-template` and replaces placeholders.
+
+### 3. Local Preview
+Since the site is static with JS rendering, any HTTP server works:
+- **Eclipse IDE:** Run `Eclipse-website-local-server` launch configuration.
+- **Command Line:** Use any static server, e.g., `npx serve .` or `python3 -m http.server`.
+- **Important:** Refresh with `Ctrl+F5` to see changes to `project.js` or CSS.
+
+## Development Conventions
+- **N&N Style:** 
+  - Titles: **Title Case**, no trailing punctuation.
+  - Body: Complete sentences, active voice ("you", not "the user").
+  - UI Elements: Use `backticks` for commands, shortcuts, and preference paths (e.g., `Preferences > General > Keys`).
+  - Emphasis: Prefer **bold** over *italics*.
+- **Images:** 
+  - All lowercase, hyphen-separated names (e.g., `new-feature.png`).
+  - PNG format only.
+- **Acknowledgements:** Do not manually edit `acknowledgements.md` unless fixing errors; it is managed by GitHub Actions.
+
+## Key Files
+- `README.md`: Basic project intro.
+- `news/instructions.md`: **Crucial** detailed guide for N&N contributors.
+- `project.js`: The heart of the site's dynamic rendering.
+- `AGENTS.md`: Technical instructions for AI agentss