Skip to content

AGENTS.md

Latest commit

 

History

History
330 lines (244 loc) · 11.5 KB

AGENTS.md

File metadata and controls

330 lines (244 loc) · 11.5 KB

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):

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

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

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)

cd news/scripts
./w3cValidateHtmlFile.sh ../4.37/index.html
# Uses W3C validator web service
# Requires curl and internet connection

Checking Repository Status

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:

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

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