Last revised 2025-05-08.
As of 4.36, New and Noteworthy is authored in markdown.
A launch configuration is provided, named
Run > Run Configurations > Eclipse Applications > Eclipse-website-local-server
that you can run in order to serve the content of the Eclipse website project's contents via localhost.
It will open a page in your default browser where the first link is to the root of the Eclipse website.
This allows you to preview all the changes that you make to the website locally before you commit them.
Sometimes it's necessary to do a deep refresh,
e.g., Ctrl-F5.
The New and Noteworthy content is contained in 4 pages
and is grouped based on the component to which they belong.
The pages are platform.md,jdt.md, platform_isv.md, and pde.md.
The platform_isv.md page contains the entries for new APIs in Platform, SWT and Equinox.
The index.md page describes the release and contains links to the component news pages.
Add a new entry to the appropriate section in the corresponding markdown document.
General standard sections are initially commented out in the markdown template.
When adding an entry to a commented out section,
remove the comment markers <-- --> surrounding the section.
If required, you can add a new section to the document to highlight a feature, but best to add a subsection. Keep an eye on the automatically-rendered Table of Contents.
The whole entry should be a blurb pitched to the Eclipse end-user community, not just to members of the Eclipse Platform development team
The title should be short and snappy,
written in title case.
The title should not use trailing punctuation.
As markdown,
the title defines the anchor,
which is generally the lowercase equivalent with all non-alphanumberic characters replaced by -.
Please test your links.
In the news description, tell users about changes they'll see in the UI. Tell component writers about changes they'll see at the client- and server-side APIs. Try to generate some excitement, save the boring details for the manual, be short, and don't repeat yourself. The description should be complete sentences, with trailing punctuation.
Make the entry self-contained and mention API classes. Do not link to issues and don't promote individuals or third-party products.
Use active voice, i.e., say "you", not "the user", and follow other advice in Eclipse Doc Style Guide.
Use backtics,
i.e., ``,
for command names Quick Fix,
keyboard shortcuts Ctrl+1,
and preference page paths Preferences > General > Keys,
Avoid other emphasis markup,
but prefer bold over emphasis if you must use one.
To ease editing, start each sentence a new line and break long sentences into phrases on separate lines.
See entries in published news documents for correct examples. These published news entries have been already reviewed, while entries in the evolving document may still contain errors.
If a small image sheds light, place it below the description, in a separate paragraph, i.e., with a blank line before and after the image in the markdown.
Crop out any extraneous stuff to focus the reader's attention on your new feature.
Use *.png and avoid really large images
because images will be scaled down to fit.
Name the file in a way that is appropriate and specific to the item,
e.g., key-bindings.png,
rather than something generic like image.png.
Use all lowercase letters in the image file name,
including the .png file extension.
As a separator,
use hyphen - rather than underscore or space.
Put all the images in a sibling directory named images.
This yields markdown like this:
Include a suitable descriptive label.
Only use the label to add information that is not accessible if the page is rendered without images.
Don't write [Screenshot of the XY dialog].
Visually impaired users shouldn't have to skip useless repetitions,
but the label can be interesting unless it's already part of the description.
Use regular markdown for the image so it can be appropriately rendered and styled.
To create the directory and all the related content for a new release,
use the 4.x-template directory.
Replace 4.x in the markdown files with the Eclipse project's release version
and replace YYYY-MM with the corresponding SimRel release name.