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.

1. Clone the guides-template to your own workspace.

2. 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.

3. Before proceeding further, you should review the checklist.

4. Open a new issue in the guides-common 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.

5. Certify the originality of your work by following the Developer Certificate of Origin (DCO) approach and adding a line to the end of the Git commit message to sign your work:

   • Signed-off-by: Jane Williams <jane.williams@gmail.com>

   • The sign-off is just a line at the end of the commit message that certifies that you wrote it or otherwise have the right to pass it on as an open source patch.

   • Use your real name when you sign. Pseudonyms or anonymous contributions cannot be accepted.

   • Many Git UI tools have support for adding the Signed-off-by line to the end of your commit message. This line can be automatically added by the git commit command by using the -s option.

6. 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.

7. Create a branch in the guides-common repository. Name your branch with your guide’s projectid or something similar. This is where you will make your edits to guide_categories.json and guide_tags.json in order to categorize your guide and select tags.

   • Decide which subcategory your guide best fits into. The guide categories and subcategories are defined in the guide_categories.json file and are shown in the table of contents on the /guides page. Your guide will appear under the subcategory you select in the json file. The order that the categories, subcategories and guides appear on the /guides page is based on the order of the json file. For a draft guide there is no need to include 'draft-guide-' in the json file. (I.e. For draft-guide-{projectid}, just add '{projectid}' to the json).

     • If adding your guide to an existing subcategory, simply add the guide’s projectid to the guides array below the desired subcateogry_name.

     • If creating a new subcategory, add a new object to the subcategories array in the desired category. The new subcategory needs to have a subcategory_name string and a guides array. The subcategory_name should be sentence case (capitalize only the first letter of the entire phrase) as this is how it will be shown in the table of contents.

   • Select relevant tags for your guide. These tags can be used to search on the /guides page and will show up on the guide under the table of contents. Please avoid inventing new tags. The tags for all the guides are stored in guide_tags.json. This file contains an array of JSON objects, one for each tag. Each tag object has a "guides" array where you can specify which guides the tag is applied to. Only tags with "visible": "true" will show up on the guides. If the tag does not have the "visible" key defined, the tag will be searchable, but it will not be visible on the guides. Another optional key is additional_search_terms. This is an array where you can specify additional search terms for the tag. These terms will not be visible on the guide. (e.g. 'Jakarta EE' and 'Java EE' are both searchable. Jakarta EE shows up as a visible tag, while Java EE is just a searchable tag).

     • Once you have decided which tags you want to use, add your guide’s projectid to the "guides" array for each of the tags you want to use.

   • Open a pull request with your edits to guide_categories.json and guide_tags.json.

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 open the README.adoc in a text editor or view it in raw form. Follow the direction before the BEGIN line to remove all the instructions prior to commit. Most instruction comments should be removed except the copyright.

// As you start writing your guide, keep everything between BEGIN and END in the README.adoc,
// meaning delete anything else that is above or below the BEGIN and END lines inclusively.
// Also, please delete any instructions that begin with //--** after you read them
// ----------- BEGIN -----------
//--** INSTRUCTION: The copyright statement must appear at the top of the file
// Copyright (c) 2023 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: 2024-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
//--** 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: ../guides-common/
//--** INSTRUCTION: Source the image directory to include any images for the guide.
:imagesdir: /img/guide/{projectid}
//--** 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
// =============================================================================

// If you have an image you want to include in the guide, store the image in the `assets`
// folder in your repo, and add the following syntax
image::image-name.png[Image Caption,width=100%]


///////////////////////////
// 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/twyb-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".

//--** Describe what user should run and expect to see after running the complete version of the application.
Add a brief explanation on how to use the finished application.

[role='command']
link:https://raw.githubusercontent.com/OpenLiberty/guides-common/master/twyb-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.

//--** Add the include adoc for starting the Open Liberty server in development mode,
//--** so that the server automatically picks up any changes that the users make to their application.

//--** You can instruct the user to "Create", "Update", or "Replace" files in their application.

//--** Note: There are classes that depend on each other. If one of the classes is not yet created
//--** in the `start` directory, but it's being referenced in a different class, development mode might exit with a compilation error.
//--** So be aware that you might need to predefine a minimal version of that class so that development mode does not exit with an error.

//--** 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

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

* 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 hide_tags=copyright"]
----
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 hide_tags=copyright"]
----
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 hide_tags=copyright"]
----
link:finish/src/main/java/io/openliberty/guides/todolistSample/managers/samples/SampleTodoManager.java[role=include]
----

* Implemented basic CRUD ([hotspot=create file=1]`Create`, [hotspot=read file=1]`Read`,
[hotspot=update file=1]`Update`, and [hotspot=delete file=1]`Delete`) operations.
* Manager is [hotspot=applicationScoped 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 hide_tags=copyright"]
----
link:finish/src/main/java/io/openliberty/guides/todolistSample/resources/TodoResource.java[role=include]
----

* The resource methods are accessible via HTTP
* Use [hotspot=get]`GET`, [hotspot=post]`POST`, [hotspot=put]`PUT`,
and [hotspot=delete]`DELETE` verbs to handle reading, creating, updating,
and deleting resources
* Validate data models and send appropriate response accordingly
// ======================================================================================================




//////////////////////////////////////////
// Running the application
//////////////////////////////////////////

//--** Use the following include to pull in the adoc saying that development mode was already run,
//--** and the changes were automatically picked up.
[role='command']
link:https://raw.githubusercontent.com/OpenLiberty/guides-common/master/devmode-build.adoc[role=include]
//--** This include adoc will have the subheading "Running the application".
//--** If you are not using this command include statement, you'll need to add it as a subheading,
//--** ie, "== 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


== Testing the application

//--** Show how to test your application.

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

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

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

* Explain what each [hotspot=test1 hotspot=test2]`@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/devmode-test.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.

//--** Include this for info on how to quit development mode
[role='command']
link:https://raw.githubusercontent.com/OpenLiberty/guides-common/master/devmode-quit.adoc[role=include]


== 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
link:https://raw.githubusercontent.com/OpenLiberty/guides-common/master/attribution.adoc[role=include]

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