Contributing to Dev.java

Dev.java is the official website for the Java platform and language maintained by the Java Platform Group at Oracle. We accept contributions from community members through this repository. Click here for examples of contributed content.

This repository contains the contribution guidelines as well as a lightweight JavaScript toolchain to build the site into static HTML.

Here are the sections of this document:

• Read This First
• Contributing
  • Content Lifecycle
  • Content Proposal
  • GitHub Workflow
  • Content License
• Building the Site
• Working with Content

Read This First

Thank you for showing interest in contributing to Dev.java. Getting your content featured and seen by hundreds of thousands of developers worldwide, and the endorsement of the Java Platform Group, is very exciting but will require some effort.

This document will outline the steps to get there. Please read and understand the complete document and any supporting documents as well.

When referring to the editors, the document is referring directly to the Java Developer Relations team on the Java Platform Group at Oracle.

Contributing Overview

Note: the editors reserve the right to accept, or reject, any contributions. Like contributing to Java itself, the bar is high, but the outcome is your contribution and attribution on the official Java developer site.

The process at a high level is as follows:

1. We use GitHub issues to track a contribution through its lifecycle, and pull requests to review the content itself. For more details about each stage, see the Content Lifecycle section below.
2. Most contributions will come directly from requested content issues.
3. All content must start in the proposed stage and will use the Issue Template "Content Proposal". This is detailed in the Proposal section below.
4. Once proposals move to approved, you will begin working on your contribution.
5. Reviews of your content will take place as GitHub pull requests, and once accepted, will move to the scheduled and published phases.

Content Lifecycle

We use GitHub issues to track articles from conception to publication. An article will go through the following stages, which are marked with labels:

• requested - Content that is needed and requested, a great place to start
• proposed - Proposed for work but not approved
• approved - Approved for work but not started
• in progress - Under active development
• scheduled - Completed and waiting for deployment
• published - Published content

Content Proposal

All content must start with a Content Proposal. This will be in the form of a GitHub issue using the Content Proposal issue template. Basic steps:

1. Look through the requested issues and find something that you feel uniquely capable of writing
2. Create a new issue with issue template Content Proposal. Please make sure the proposal thoroughly describes what you intend to contribute. An outline format detailing the sections and a sentence that describes what will be covered in each section, is preferred.
3. Fill out the fields to the best of your ability
4. Submit the issue.
5. The editors will now review your proposal and follow up with any other information needed. The status of the issue will eventually move to either approved or rejected.

GitHub Workflow

Once your proposal has been moved to the approved stage, you can begin working on your content. Here are the steps to do this:

1. Fork this repo
2. Create a branch off of main for each piece of content
3. Build the site. Please see the building the site section below.
4. Create your content (see the Working with Content section below)
5. Submit a pull request back to this repo

Content License

Contributors must sign the Oracle Contributor Agreement which will be verified once there is a pull request created. Contributed content is made available under the UPL license. You can find examples here.

Building the Site

There is some basic JavaScript infrastructure to help build the static site. There are two options:

Option 1: Build locally

1. install node and npm. easiest way is nvm and nvm use in this directory.
2. npm install
3. npm install gulp -g
4. gulp

A browser should launch viewing https://localhost:3000

Option 2: Use Docker

1. docker build --tag devjava .
2. docker run --publish 3000:3000 --init -it --rm devjava

You should then be able to open a browser and visit https://localhost:3000

(For a more dynamic development experience avoiding a Docker build after every change, you can mount the local /app folder to the container by adding option -v $PWD/app:/app/app to your docker run command. Note: $PWD may not work in Windows.)

Working with Content

See working with content guide