Skip to content

Latest commit

 

History

History
350 lines (237 loc) · 21.6 KB

CONTRIBUTING.md

File metadata and controls

350 lines (237 loc) · 21.6 KB
Raw

Contributing to the documentation

This short guide will help you if you want to make a contribution to the Eclipse OpenJ9™ user documentation.

Note: There is a short video presentation explaining the process for contributing to the OpenJ9 documentation. (Save and open the .zip file in the /process directory to view the .mp4 video.) You can also view the PowerPoint presentation used in that video. (Either save the file to view locally, or click "View raw".)

Setting up a local MkDocs environment

Basic prerequisites:

  • Git
  • Python 3
  • Pip 9.0.1
  • a Markdown editor (Atom, for example)

Use pip to install the other components, reusing the requirements.txt file in the /buildenv directory of the repository to ensure that you are mirroring build levels:

pip install -r requirements.txt

Next:

If you are working on a Windows™ system, set the following Git configuration, which allows you to edit with Windows line endings (CRLF), but converts to Unix-style endings (LF) when you push changes:

git config --global core.autocrlf true

Editing the documentation

The source files are written in GitHub-flavoured Markdown format. We recommend using Atom for editing, which includes a markdown preview package so that you can check your changes as you write. Here is a 3 minute read on Mastering markdown.

For improved structure and styling options, a Markdown extension for definition lists is also included. This simple extension allows you to create a title and indented definition by using a semi-colon (:). For example:

Title
: definition

Documentation structure

All files in the ROOT folder of this repository are concerned with the structure, build, and automation of the documentation hosting solution.

MkDocs .yml file

The key configuration file for the documentation is the /mkdocs.yml file, which controls the following aspects:

  • website and repository addresses
  • MKdocs theme and customization values
  • structure and content, under the pages: section

Under pages: in the .yml file, topics are added and indented to reflect their position in the table of contents. Care must be taken to preserve the indentation when making changes to this file.

If you want to add a new file, see Document files about file naming, and follow the existing structure and layout when you add a reference to it in the .yml file. Insert new options in the appropriate position in the list, which is typically arranged in alphabetical order within a section.

Note: From version 1.0 of MkDocs, the pages: section is renamed to nav:.

Document files

Documentation content is contained in the following directories:

  • All Markdown files are in the /docs folder.
  • All diagrams that are used in the content are in the /docs/cr folder.

New file names should follow the existing naming convention. They must be in lowercase. They typically omit punctuation and other symbols present in the full option title. Topics that form part of a group might have a distinguishing prefix.

Some examples:

Topic / option name File name
-Dcom.ibm.lang.management.verbose dcomibmlangmanagementverbose.md
Java stack (jstack) tool tool_jstack.md
-Xconcurrentbackground xconcurrentbackground.md
-XX:[+|-]ShareAnonymousClasses xxshareanonymousclasses.md

Style guidelines

For consistency across the user documentation, there are a few style guidelines that you should follow. These are not set in stone, so if you have any suggestions or concerns, open up a discussion in the Slack channel. If you haven't done so already, join the channel.

Generally, follow the style and structure of existing topics. If you are creating a new topic, you might find it helpful to copy a similar existing topic and modify it. (Don't forget to modify the file name in the footer!)

When you document HotSpot options in the OpenJ9 documents, use similar text to the previous HotSpot option additions in the What's New in version <release number> and option topics. Also, update the table in the Switching to Eclipse OpenJ9 topic.

However you create a new topic, you must ensure that the header comment with copyright and license information is copied exactly as it is from an existing topic. Do not change either of the copyright dates, even for a new topic; the dates refer to the complete documentation set, not to individual files and so should be the same in all topics.

Writing tips

Make your contributions valuable to all users, including those users who have English as a second language. Ensure that you write clearly and precisely. For example:

  • Use simple language.
  • Avoid needless words.
  • Use short sentences but avoid using too many sentence fragments.
  • Be direct: use active voice and present tense.
  • Avoid ambiguity: what exactly does the "this" you wrote refer to?
  • Use second person ("you" and "your") to better engage the audience.
  • Don't overuse punctuation for effect, especially avoid making everything either a question or an exclamation!!
  • Make humor universal and timeless, but in technical documentation, humor is best avoided.

Which platform?

Although OpenJ9 supports a number of platforms and architectures, there might be different configuration and tuning options, or different default behavior. When adding content to the user documentation that does not apply to all environments, call it out. For example:

  **(Linux&reg; only)**

If content is not marked, it should apply to any platform.

See Trademarks for information about marking trade names appropriately.

Which OpenJDK version?

The user documentation supports the configuration, tuning, and diagnosis of the OpenJ9 VM in various versions of the OpenJDK runtime. However, due to differences between the Java™ SE class libraries, specific options might apply only to one environment. The following icons are available to indicate where differences apply:

  • Java 8 (LTS) - For content that applies only to an OpenJDK version 8.
  • Java 8 (LTS) and later - For content that applies to an OpenJDK version 8 or later version.
  • Java 11 (LTS) - For content that applies only to an OpenJDK version 11.
  • Java 11 (LTS) and later - For content that applies to an OpenJDK version 11 or later version.
  • Java 15 - For content that applies only to an OpenJDK version 15.
  • Java 15 and later - For content that applies to an OpenJDK version 15 or later version.
  • Java 16 - For content that applies only to an OpenJDK version 16.
  • Java 16 and later - For content that applies to an OpenJDK version 16 or later version.
  • Java 17 (LTS) - For content that applies only to an OpenJDK version 17.
  • Java 17 (LTS) and later - For content that applies to an OpenJDK version 17 or later version.
  • Java 18 - For content that applies only to an OpenJDK version 18.
  • Java 18 and later - For content that applies to an OpenJDK version 18 or later version.
  • Java 19 - For content that applies only to an OpenJDK version 19.
  • Java 19 and later - For content that applies to an OpenJDK version 19 or later version.
  • Java 20 - For content that applies only to an OpenJDK version 20.
  • Java 20 and later - For content that applies to an OpenJDK version 20 or later version.
  • Java 21 - For content that applies only to an OpenJDK version 21.
  • Java 21 and later - For content that applies to an OpenJDK version 21 or later version.

Different colors are used for the icons to differentiate long term service (LTS) releases from feature releases. For accessibility reasons it is important to use alternative text with these icons that differentiates an LTS release.

Follow these guidelines:

  • If a topic is exclusive to a particular version, use the icon near the top of the topic.
  • If the content applies to a cell or row in a table, use the icon within the table.
  • If the content applies to a sentence within a topic, encapsulate the content by using an end tag end tag for LTS releases for LTS releases or end tag for feature releases for feature releases.

Here are some examples:

![Start of content that applies only to Java 8 (LTS)](cr/java8.png) This sentence applies only to Java 8 runtime environments that include the OpenJ9 VM. ![End of content that applies only to Java 8 (LTS)](cr/java_close_lts.png)

![Start of content that applies only to Java 16 and later](cr/java16plus.png) This sentence applies only to Java 16 or later runtime environments that include the OpenJ9 VM. ![End of content that applies only to Java 16 and later](cr/java_close.png)

The icons are created by using the GIMP editor, from the _version.xcf file in the same /docs/cr folder as the icons.

Creating icons by using the GIMP editor

To create a new version icon:

  1. In the GIMP editor, from the /docs/cr folder, open the _version.xcf file. The file opens with the last image that was saved. In the lower-right panel, you can see the different layers of the existing icon. You can use an existing icon to create a new icon.
  2. In the lower-right panel, Layers tab, right-click the most recent version number layer and then click Duplicate Layer. A new layer is added with the suffix #1.
  3. To rename the layer, double-click the name of the new layer and specify the new name.
  4. Zoom in to the image in the canvas for ease of editing. You can either use the menu option (View -> Zoom -> zoom percentage) or use the Zoom tool in the upper-left panel.
  5. In the Layer panel, click the eye icon next to the last version icon layer to make it invisible.
  6. In the canvas, double-click the number in the icon image and delete the number.
  7. Type the new number (the font size should be 14 with bold formatting).
  8. Move the number to position it in the middle of the color background. To move the number, press the Alt key (the option key in Mac) and click and drag the number.
  9. In the Layers tab, use the eye icon next to the different layers to change the color and other attributes of the image. For example, use the eye icon next to the Plus layer to make that visible.
  10. To generate the new icon, click File -> Export As and export the image as .png file with the required name.

Trademarks

In each topic, the first occurrence only of trademarked terms should be marked appropriately. Avoid including trademark symbols in titles and headings, unless the term appears nowhere else in the topic.

Here are some examples that you might come across:

AIX®, IBM®, IBM z15®, Java™, Linux®, Linux on IBM Z®, Linux on Power Systems™, macOS®, MVS™, OpenJ9 VM Language Environment®, Oracle®, Windows™, z/OS®.

Mark trademarks™ with &trade; (as in Java&trade;) and registered trademarks® with &reg; (as in Linux&reg;).

The first reference to OpenJ9 in a topic should be Eclipse OpenJ9™.

Using images

If you believe that a diagram can be used to enhance the content, add the .gif or .png file to the docs/cr folder and reference it in the markdown file using the following syntax:

![Add alternative text here to describe the image for users who are using a screen reader](cr/<my_image>.png)

Font-awesome icons can also be used to highlight user "notes" and "restrictions". The following examples show how to embed these icons:

:fontawesome-solid-pencil:{: .note aria-hidden="true"} **Note:** Here is something you should be aware of...

:fontawesome-solid-triangle-exclamation:{: .warn aria-hidden="true"} **Restrictions:** Here is some limitations...

Font-awesome icons are also used in option tables to indicate defaults. The following examples show how to embed these "ticks" and "crosses".

:fontawesome-solid-check:{: .yes aria-hidden="true"}<span class="sr-only">yes</span>

:fontawesome-solid-xmark:{: .no aria-hidden="true"}<span class="sr-only">no</span>

Note that these require an extra <span>, which is used by screen readers.

For examples that embed Java version icons such as Java 8 icon and Java 14 and later icon, see Which OpenJDK version?.

Referencing non-Markdown pages

The user documentation pulls in API documentation, which is pre-built as HTML files. These files have to be referenced in a specific way for the build process. The documentation has two builds, one for use in the website and a special build for offline use. The offline build uses the Mkdocs use_directory_urls: false configuration setting, which alters the layout of the site and automatically adjusts relative urls between Markdown files. However, relative urls to non-Markdown pages, which are copied as-is into the /site directory, are not adjusted.

If you need to reference a specific API page from a Markdown file use the variable config.use_directory_urls provided by mkdocs-macros plug-in. For example in the OpenJ9 JDK 11 API documentation, the iframe element uses this technique in the src attribute:

{% if config.use_directory_urls %}../{% endif %}api/jdk11/index.html?view=embed

To ensure that the contribution process is as simple as possible, the mkdocs-macros plug-in should not be used for any other purpose than referencing pre-built API documentation.

You must request the regeneration of API documentation for OpenJ9 (for example, in the Slack channel, #committers-public) for each release.

Accessibility

The accessibility of the documentation to users with disabilities is important to this project. Here are some things to consider:

  • Don't use terms that convey "position". For example, do not write "the example below", "the above table", "the right column".
  • Don't use color on its own to differentiate text. For example, "the string shown in green" or "the code element in blue".
  • If you embed a diagram, use alternative text (ALT-TEXT) to describe the image for screen readers. See Using images.
  • If you use icons to indicate content for a specific OpenJDK version, or for "notes" and "restrictions", add the correct attributes for screen readers. See Using images.

Testing your changes locally

When you've made the changes that you want to contribute, build and preview the website. If you have set up an MkDocs environment locally, follow these steps:

  • Run mkdocs serve.
  • Open a browser and view the following URL: http://127.0.0.1:8008 (specifically, the URL set in the dev_addr: section of the mkdocs.yml file).

Submitting a contribution

When you are happy with your changes, create a pull request, following the guidelines for submitting a contribution to OpenJ9 here.

In particular, if your changes address an issue, quote the issue number in the commit message.

If work is ongoing, or if there is further work to be done after you create your pull request, (either in the docs or in the code) add a "WIP" (Work In Progress) prefix to the title.

Create milestones for the OpenJ9 document issues in the openj9-docs repository for tracking purposes. To create milestones, in the "Issues" or "Pull requests" tab, click the "Milestones" button next to the "New issue" (or "New pull request") button. In the "Milestones" tab, click the "New milestone" button and then specify the details to create a new milestone. The New milestone button is available only if you have the permissions to do so. You can otherwise contact the repository owners or administrators who have the permission to create milestones.

You can also create labels to categorize issues and pull requests. To create labels, you must be added as a Contributor in the repository by the repository owner or administrator. You can see the list of contributors at https://projects.eclipse.org/projects/technology.openj9.

If you are not marked as a Contributor, issues can be assigned to you only if you have interacted with the issue (for example, added a comment on it).

Previewing pull requests

Pull requests must be previewed before merging. Stage your pull request (that is, create a temporary draft of your changes) by triggering a Jenkins-ci job. To run the job, add the following trigger comment into a pull request:

Jenkins doc stage

Pull request builds are staged at the gh-pages branch of the https://github.com/eclipse-openj9/openj9-docs-staging repository. To view the staged draft of your documentation, visit the following URL, substituting <PR> with the number of your pull request:

https://eclipse-openj9.github.io/openj9-docs-staging/<PR>

Accepting contributions

(approved users only)

Project committers are responsible for checking pull requests and merging changes.

Documentation pull requests must not be merged before code pull requests are merged in case subsequent code changes alter the documented behavior.

Before merging, check with the developers involved and make sure that there is not any work still to be done. This is usually indicated by a "WIP" prefix on the pull request title.

When pull requests are merged, the documentation is published to the gh-pages branch of the https://github.com/eclipse-openj9/openj9-docs repository as part of the "current working draft" at the following URL:

https://eclipse-openj9.github.io/openj9-docs

You can publish the OpenJ9 documents when the release is created. You need not wait for the build binaries to be available.

When released, the latest version of Eclipse OpenJ9 is published at:

https://www.eclipse.org/openj9/docs

For more information about the documentation release process, build process, and publication process, see the wiki section of this repository.