Contributing a guide

Welcome to Open Liberty! In order to contribute a guide for Open Liberty, follow the steps in this README.

Step 1: Set up your computer.

Install Git and become familiar with the Git triangular workflow.
Install and know the basics of Maven or Gradle.
Install a text editor with the AsciiDoc compiler plugin and learn the syntax of AsciiDoc.

Step 2 (Optional): Try some existing guides.

Use the guides on openliberty.io as examples.

If you’re not sure where to start, try the Creating a RESTful web service guide followed by the Injecting dependencies into microservices guide.

Step 3: Know the structure and style.

Know your audience!
- If the guide is introductory, explain the basic concepts of the technology. At the same time, try to avoid overwhelming the reader with too much information. If you’re not sure if you’ve included the correct amount of info, consider asking a new user to try your guide.
Know the guide structure and the writing styles!
- Take a look at the Guidelines for Structure and Styles.

Step 4: Create a new guide.

Clone the guides-template to your own workspace.
Develop your guide in your own workspace.
- Develop code and write tests that are based on the project structure in the guides-template. To start, create your project in the finish directory. Make a simple application that demonstrates how to use your topic.
- Copy the code from the finish directory to the start directory. Then, from the copy in the start directory, remove the code that you want the user to focus on.
- Write a guide that follows the README.adoc template (APPENDIX A) in the guides-template repository. Introduce and explain the parts of code that you removed during the last step and tell the users where to copy and paste the code. Walk through how to build the finish directory, run the tests, and perform any other steps that users need to run your project on their own.
Before proceeding further, you should review the checklist.
Open a new issue in the guides-commons repository. Describe the topic you wrote, add a link to the repository that contains the complete draft of your guide, and the Open Liberty team will be notified.
You must sign the Individual Contributor License Agreement (CLA) in order to contribute. If you are writing the guide as part of your job, you might also want your employer to sign a Corporate Contributor License Agreement (CCLA). Instructions for how to sign and submit these agreements are provided in each document. You should send your signed CLA document (in PDF) to the email address cla@openliberty.io before you move on to the next step.
After the Open Liberty team approves your guide and obtains your signed CLA, they will create a draft guide repository in the Open Liberty Project on GitHub for you. Your new repository will be named as draft-guide-{projectid}. Then, you can open a pull request that contains your commits for the guide, and the team will be notified for review.

Step 5: The Open Liberty team will review your guide.

You can see your feedback from the Issues section in your draft-guide-{projectid} repository when it’s ready.
Follow up with the team’s review discussions.

APPENDIX A: A template README.adoc

Please remove all the instructions before APPENDIX A prior to commit. Most comments should be removed, although not the copyright.

// INSTRUCTION: The copyright statement must appear at the top of the file
//
// Copyright (c) 2019 IBM Corporation and others.
// Licensed under Creative Commons Attribution-NoDerivatives
// 4.0 International (CC BY-ND 4.0)
//   https://creativecommons.org/licenses/by-nd/4.0/
//
// Contributors:
//     IBM Corporation
//
:page-layout: guide-multipane
// INSTRUCTION: The project id is the part of the git repository after the guide- and must be specified
// :projectid: github repo name without the `guide-` prefix
:projectid: template
// INSTRUCTION: Provide an estimate of how long the guide will take to go through.
:page-duration: 15 minutes
// INSTRUCTION: Provide the date when the guide is published.  Format is YYYY-MM-DD.
:page-releasedate: 2019-03-11
// INSTRUCTION: Provide a description for the guide index page.
:page-description: Learn how to create a todo list API as a REST service using JAX-RS, and Open Liberty.
:guide-author: Open Liberty
// INSTUCTION: Please provide relevant tags, try to avoid inventing new ones.
// Use some of "MicroProfile, Maven, Docker, Kubernetes, Gradle, Java EE, Security".
:page-tags: ['Java EE']
// INSTRUCTION: Specify the unique name of the guide that is used in the permalink.
:page-related-guides: ['cdi-intro', 'rest-intro']
// INSTRUCTION: Set 'basic', 'microprofile', 'none'
:page-guide-category: microprofile
// INSTRUCTION: Places the guide into the essentials section of a category
// Requirement: Must define :page-guide-category:
:page-essential: false
// INSTRUCTION: Number is used to sort guide from left (lowest number) to right (highest number) in
// the essentials section of a category
// Requirement: Must have :page-essential: true
:page-essential-order: 3
// INSTRUCTION: Specify the slug in the website. This must be unique.
:page-permalink: /guides/{projectid}
// INSTRUCTION: Source the common page elements, clone `git@github.com:OpenLiberty/guides-common.git`.
:common-includes: https://raw.githubusercontent.com/OpenLiberty/guides-common/master
// INSTRUCTION: Update the SEO title for the guide
:page-seo-title: Creating a REST service
// INSTRUCTION: Update the SEO description for the guide
:page-seo-description: Find out how to create a REST service on Open Liberty
// INSTRUCTION: You can't have a new line between the attributes and the title.
= Title of guide, starting with a gerund (Creating, Administering, and so on)
// EXAMPLE: Creating a REST API for a todo list application

[.hidden]
NOTE: This repository contains the guide documentation source. To view the guide in published form,
view it on the https://openliberty.io/guides/{projectid}.html[Open Liberty website].

// Start the introduction with "You'll explore how to..." or something similarly catchy.
// Write no more than two sentences, with meaningful information on what the user can accomplish
// with this guide.
// Do not start the introduction with "This guide...".
// EXAMPLE: Learn how to create a todo list API as a REST service using JAX-RS, CDI, and Open Liberty.




== What you'll learn

// Write about what the user will learn in a meaningful intro paragraph.
// Follow the intro paragraph with more details of what the user will learn, but still keep it brief.
// See the REST guide at as an exemplar guide.
// https://openliberty.io/guides/rest-intro.html
// https://github.com/OpenLiberty/guide-rest-intro

// EXAMPLE:
// =============================================================================
You'll learn how to create a todo list microservice using JAX-RS, CDI and Open Liberty.
You will use Maven throughout the guide to build the microservice and deploy it
to run on the Open Liberty application server.

=== What is JAX-RS
* Add a brief description of JAX-RS

=== What is CDI
* Add a brief description of CDI

=== What is Open Liberty
* Add brief description of Open Liberty, where applicable

Brief description of the todo list micrioservice
// =============================================================================



///////////////////////////
// Getting started
///////////////////////////

// Add this getting started section to your guide if it is applicable.
// Use the following include to pull in the git clone instructions from the guides-common repo.

[role='command']
link:https://raw.githubusercontent.com/OpenLiberty/guides-common/master/gitclone.adoc[role=include]
// This include adoc will have the heading "Getting started".
// If you are not using this command include statement, you'll need to add it as a subheading,
// ie, "== Getting started".




///////////////////////////
// Try what you’ll build
///////////////////////////

// This is a subsection of the "Getting started" section above. It should briefly walk the user
// through how to setup everything in the "finish" directory and try out the finished version of
// what they will be building.

[role='command']
link:https://raw.githubusercontent.com/OpenLiberty/guides-common/master/trywhatyoubuild-intro.adoc[role=include]
// This include adoc will have the subheading "Try what you'll build".
// If you are not using this command include statement, you'll need to add it as a subheading,
// ie, "=== Try what you'll build".

// Brief explanation on how to use the finished application.
// Describe what user expects to see after running the complete version of the application.

[role='command']
link:https://raw.githubusercontent.com/OpenLiberty/guides-common/master/trywhatyoubuild-end.adoc[role=include]




== Section title for this section, starting with a gerund like Creating, Building, etc

// Add the various sections that are needed for a particular guide.

// Start each additional section title with a meaningful gerund such as Creating, Building, Testing.
// Follow the gerund with a meaningful noun phrase. For example: Creating a JAX-RS application
// Have as many sections and section titles as needed.
// EXAMPLES:

* Building a todo list model

* Creating an application manager

* Creating the JAX-RS Resource


// Write a sentence with the context like "Navigate to the `start` directory to begin." in the section
// where user starts working with the implementation.


// What to add for each section:
// Start each section with a meaningful description about what the user is doing in the section.
// Include code snippets.
// Avoid making all the documentation a series of steps and tasks, bullets, or numbered lists.
// Use tick marks around directories, files, values, class names, method names, and so on.
// Example: `this-is-a-file`, `this/is/a/path`, `thisIsAMethod`.



// EXAMPLE: The following block demonstrates how different sections look like for a todo application.
// ======================================================================================================
== EXAMPLE: Building a todo list model

* Navigate to the `start` directory
* Represent an entry in a todo list

[role="code_command hotspot", subs="quotes"]
----
#Create the `TodoModel` class.#
`src/main/java/io/openliberty/guides/todolistSample/models/TodoModel.java`
----

TodoModel.java
[source, Java, linenums, indent=0, role="code_column"]
----
link:finish/src/main/java/io/openliberty/guides/todolistSample/models/TodoModel.java[role=include]
----

* Getters, setters, and default constructor such that the model can be serialized/deserialized easily

== EXAMPLE: Creating an application manager

* Create a manager that is injected into the JAX-RS resource

[role="code_command hotspot file=0", subs="quotes"]
----
#Create the `TodoManager` interface.#
`src/main/java/io/openliberty/guides/todo/managers/TodoManager.java`
----

TodoManager.java
[source, Java, linenums, indent=0, role="code_column"]
----
link:finish/src/main/java/io/openliberty/guides/todolistSample/managers/TodoManager.java[role=include]
----

* Next, create the sample todo manager class

[role="code_command hotspot file=1", subs="quotes"]
----
#Create the `SampleTodoManager` class.#
`src/main/java/io/openliberty/guides/todolistSample/managers/samples/SampleTodoManager.java`
----

SampleTodoManager.java
[source, Java, linenums, indent=0, role="code_column"]
----
link:finish/src/main/java/io/openliberty/guides/todolistSample/managers/samples/SampleTodoManager.java[role=include]
----

* Implemented basic CRUD ([hotspot=32-36 file=1]`Create`, [hotspot=39-44 file=1]`Read`,
[hotspot=47-57 file=1]`Update`, and [hotspot=60-68 file=1]`Delete`) operations.
* Manager is [hotspot=14 file=1]`ApplicationScoped`, which essentially means that it is a singleton.

== EXAMPLE: Creating the JAX-RS resource

* Description of the technology, possibly with a link to learn more.
* Use CDI to inject the todo manager into the resource

[role="code_command hotspot", subs="quotes"]
----
#Create the `TodoResource` class.#
`src/main/java/io/openliberty/guides/todolistSample/resources/TodoResource.java`
----

TodoResource.java
[source, Java, linenums, indent=0, role="code_column"]
----
link:finish/src/main/java/io/openliberty/guides/todolistSample/resources/TodoResource.java[role=include]
----

* The resource methods are accessible via HTTP
* Use [hotspot=27-43]`GET`, [hotspot=45-54]`POST`, [hotspot=56-71]`PUT`,
and [hotspot=73-83]`DELETE` verbs to handle reading, creating, updating,
and deleting resources
* Validate data models and send appropriate response accordingly
// ======================================================================================================




//////////////////////////////////////////
// Building and running the application
//////////////////////////////////////////

// Use the following include to pull in the Maven build instructions from the guides-common repo.
[role='command']
link:https://raw.githubusercontent.com/OpenLiberty/guides-common/master/mvnbuild.adoc[role=include]
// This include adoc will have the subheading "Building and running the application".
// If you are not using this command include statement, you'll need to add it as a subheading,
// ie, "== Building and running the application".

// In between here, you should state where you application can be found now that its running. ie. urls
// Sample usage of the application
// Suggestions for what changes the reader can make to explore the code

// Use the following include to pull in the Maven rebuild instructions from the
// guides-common repo.
[role='command']
link:https://raw.githubusercontent.com/OpenLiberty/guides-common/master/mvncompile.adoc[role=include]




== Testing the application

// Show how to test your application.

// EXAMPLE:
// ======================================================================================================

[role="code_command hotspot", subs="quotes"]
----
#Create the `TodoTest` class.#
`finish/src/test/java/it/io/openliberty/guides/todo/TodoTest.java`
----

TodoTest.java
[source, Java, linenums, indent=0, role="code_column"]
----
link:finish/src/test/java/it/io/openliberty/guides/todolistSample/TodoTest.java[role=include]
----

* Explain what each [hotspot=13-20]`@Test` test case is testing
* Explain key methods
// ======================================================================================================

// Include this for info on how to run the tests
[role='command']
link:https://raw.githubusercontent.com/OpenLiberty/guides-common/master/mvnverify.adoc[role=include]

// Including a listing block with test results here
// Show console output of the test results

// OPTIONAL: after listing the test results, mention a simple change a user can make/introduce that
// will cause the tests to fail. Be brief and don't give the users all of the instructions.
// At this point, they should be comfortable enough to figure it out on their own.




== Great work! You're done!

// Briefly summarize what the user achieved in this guide (1-2 sentences).
EXAMPLE: You have just completed building a simple todo list application using JAXRS and CDI services in Open Liberty.

// OPTIONAL: briefly state what the user could do next now that they've learned the
// technologies in this guide.

// Include the below from the guides-common repo to tell users how they can contribute to the guide
 include::{common-includes}/attribution.adoc[subs="attributes"]

// DO NO CREATE ANYMORE SECTIONS AT THIS POINT
// Related guides will be added in automatically here if you included them in ":page-related-guides"

justineechen / draft-guides-template