Contribution Guide

1. Fabric8 Launcher development

This chapter contains information about developing your own runtimes or example application, contributing changes to existing ones, and improving Fabric8 Launcher.

1.1. Updating Examples Catalog for local Minishift or CDK testing

One of important life cycle stages of an example application is testing it in an Examples Catalog. Create a custom Examples Catalog that links to the repository with your example application on GitHub, and test your example application by following the instructions below:

1.1.1. Creating a custom Examples Catalog

By default, the Fabric8 Launcher tool uses an examples catalog from the openshiftio/booster-catalog repository. If you do not want to use the default catalog, you can create one from scratch, or fork the default catalog and make changes to it. This chapter describes the procedure for modifying the default catalog.

Prerequisites

A GitHub account

Creating a Custom Examples Catalog

Navigate to the openshiftio/booster-catalog repository, which hosts the default catalog.
Fork the repository by clicking Fork in the top right corner of the page.
Clone the forked repository locally to your hard drive.
Make changes to the catalog, for example:
- Modify the existing example application listing by modifying the YAML files in the directories for each application or runtime.
- Create a new listing by creating a new YAML file with the following structure in one of the runtime directories:
  Example 1. Catalog YAML File
  githubRepo: USER/REPO gitRef: BRANCH
  
  In the example above, USER is the GitHub user name or organization name and REPO is the name of the repository where the example application is located. BRANCH is the branch in the repository you want to make available in the catalog.
- Modify the metadata.yaml file where additional information about the example applications is stored.
Commit and push your changes to your forked repository.

1.1.2. Installing Fabric8 Launcher tool manually

Install a local customized instance of the Fabric8 Launcher tool, which allows you to test the functionality or make modifications to the service using a web interface.

Prerequisites

Minishift or CDK installed and running.
A GitHub personal access token.

Procedure

Open the Minishift or CDK Web console and log in.
Click New Project to create a new OpenShift project to house the Fabric8 Launcher tool.
Name the project and optionally provide a description. This example uses my-launcher for the project’s name.
Click Create to complete the project creation.
Click Import YAML/JSON to add services to your new project from a template.
Copy the contents of the current Fabric8 Launcher template from the GitHub repository and paste it into the text box provided.
Click Create, ensure that only the Process the template option is selected, and click Continue.
Fill out the following fields.
- Your GitHub username.
- Your GitHub Mission Control access token is your personal access token for GitHub.
- The Target OpenShift Console URL is the OpenShift Console URL from your Minishift or CDK. This should be the same base URL you are currently using to complete the form, for example https://192.168.42.152:8443.
- OpenShift username and password from your Minishift or CDK, for example developer for the username and password.
- KeyCloak URL and KeyCloak Realm MUST be cleared out.
  
  You must clear these fields out for the Fabric8 Launcher tool on your Minishift or CDK to be configured correctly.
- Set Catalog Git Repository to the repository with the catalog that you are testing. Set Catalog Git Reference to the branch in that repository you are testing.
Before proceeding to the next steps, confirm all the fields are correct. Also confirm that KeyCloak URL and KeyCloak Realm have been cleared out.
Click Create to complete the setup. You will see a screen confirming that the service has been created. Click Continue to overview.
On the overview page, wait and confirm that the four pods for the Fabric8 Launcher tool have completed starting up.
When all pods are running, click the link at the top of all pods, which typically ends in nip.io.

A new browser tab opens with the Fabric8 Launcher tool. This is the same service as https://developers.redhat.com/launch but running in a Minishift or CDK.
Start using your Fabric8 Launcher tool to launch example applications.

Additional resources

See the Getting Started with Application Development on OpenShift for a walk-through of running an example application.
Read the runtime guides for an overview of the runtimes and their example applications:

You can preview the latest state of Fabric8 Launcher by navigating to the stage build of Fabric8 Launcher.

2. Filing a code issue

TBD

3. Documentation

This chapter contains information about contributing and releasing the launcher.fabric8.io documentation. You can also contribute to the documentation by filing an issue in our Jira project with corrections or feedback.

3.1. Before you start

To contribute to the Fabric8 Launcher documentation, you need to configure the following tools and accounts:

3.1.1. Tools (required)

You must install the following tools on your system:

Asciidoctor

A quick and light tool for local builds that allows you to check factual correctness or flow of information.

To install Asciidoctor on Fedora, CentOS, or RHEL, run the following command (in Fedora, replace yum with dnf):

# yum install asciidoctor

On Windows, Mac OS X, and other Linux distributions, follow the instructions in the official Asciidoctor documentation.

Meld (optional)

A graphical tool for comparing files. This tool is useful for comparing Git revisions and resolving merge conflicts.

To install Meld on Fedora, CentOS, or RHEL, run the following command (in Fedora, replace yum with dnf):

# yum install meld

3.1.2. Accounts (required)

To contribute, you must have a GitHub account with GPG configured. To configure GPG:

On RHEL, CentOS, or Fedora, use the gpg2 binary instead of gpg. On MacOS, use the gpg binary.

Configuring GPG

The command options you use to configure gpg2 or gpg are the same for both binaries.

Generate a new GPG key.
Add the GPG key to your GitHub account.
Tell git about the signing key on your machine.
In the launcher-documentation repository, set automatic signing with your GPG key:
$ git config commit.gpgsign true
For more information, see Signing commits using GPG.
On RHEL, CentOS, or Fedora, set the commit signing program to gpg2. On MacOS, set the commit signing program to gpg.
```
$ git config --global gpg.program gpg2
```

3.1.3. Setting up Git hooks (recommended)

To make a contribution to the launcher-documentation repository, you need to set up the Git hooks directory. These hooks automatically make sure at commit time that your contribution does not break important parts of the repository.

Setting up Git Hooks in launcher-documentation Repository

In a terminal application, navigate to the directory with the launcher-documentation repository.
Set the Git hook directory to $REPO_HOME/.githooks:
```
$ git config core.hooksPath .githooks
```

3.2. Repository

3.2.1. Repository location

The repository for the example applications, the Launchpad front page, and this contributor guide is hosted on GitHub in the launcher-documentation repository.

The runtime documentation repositories are hosted on the following locations:

Thorntail: thorntail/thorntail (community) and wildfly-swarm-prod/wildfly-swarm (product, private), both in the docs subdirectory.
Spring Boot: spring-projects/spring-boot in the spring-boot-docs subdirectory.
Eclipse Vert.x: eclipse/vert.x in the src/main/asciidoc subdirectory.

3.2.2. Repository filesystem layout

The following diagram describes the filesystem layout of the launcher-documentation repository:

The triple-dot indicates there are more files or directories in the particular directory.

Filesystem Layout

.
├── docs/ (1)
│   ├── topics/ (2)
│   │   ├── images/ (3)
│   │   ├── styles/ (4)
│   │   ├── templates/ (5)
│   │   │   ├── document-attributes.adoc (6)
│   │   │   ├── document-attributes-launcher.adoc (7)
│   │   │   ├── document-attributes-portal.adoc (8)
│   │   │   ├── environment.adoc (9)
│   │   │   ├── ...
│   │   │   └── thorntail (10)
│   │   ├── con_circuit-breaker-design-tradeoffs.adoc
│   │   └── ...
│   ├── $GUIDE_NAME/ (11)
│   │   ├── master.adoc (12)
│   │   ├── build_guide.sh (13)
│   │   └── topics/ -> ../topics (14)
│   └── ...
├── scripts/ (15)
│   ├── build_guides.sh (16)
│   ├── validate_guides.sh (17)
│   └── ...
├── cico_build_deploy (18)
├── CHANGELOG.adoc (19)
└── README.adoc

1	The directory with the sources of all the launcher.fabric8.io guides, the launchpad.openshift.io page, and the contributor guide.
2	The directory with the actual sources in AsciiDoc files. This directory is shared among all guides.
3	The directory with all the images used in the sources.
4	The directory with all the stylesheets used in the sources.
5	The directory with all the templates used in the sources.
6	The file where all the common document attributes are defined.
7	The file where Fabric8 Launcher–specific document attributes are defined.
8	The file where Red Hat Customer Portal–specific document attributes are defined.
9	The file that sets whether the documentation is built on the Fabric8 Launcher or on the Red Hat Customer Portal.
10	The directory with sources synchronized from the Thorntail repository.
11	The directory with the sources of a guide. Each guide has exactly one directory like this.
12	The main AsciiDoc file of the guide. The files from the `topics` directory are included from this file.
13	The script for building the particular guide.
14	A symbolic link to the shared `$REPO_HOME/docs/topics/` directory.
15	The directory with scripts used for manipulating files in the directory, building, and more.
16	The script for building all guides at once. This script does not validate the guides.
17	The script for validating all guides at once.
18	The script to start local server and to publish to production. For more information, see Starting preview server.
19	The file with changes made in each release.

Do not edit files in the $REPO_HOME/docs/topics/thorntail directory, always submit a pull request to the Thorntail repository and synchronize the files afterwards.

Additional resources

Syncing with Thorntail docs

3.2.3. Branches and tags

The following branches and tags are used in the launcher-documentation repository:

Table 1. Branch Names and Contents
Branch	Content
master	The latest version of the documentation in development.

Table 2. Tag Format and Contents
Branch	Content
Date in the `YYYY-MM-DD` format	The documentation as released on the particular date.
Date in the `YYYY-MM-DD_$NUMBER` format	A subsequent release of the documentation on that date.

3.3. Contributing

3.3.1. Git workflow for making changes

When making contributions, follow the standard GitHub flow. Below, you will find more details about the steps that are required in the launcher-documentation repository.

Do not edit files in the $REPO_HOME/docs/topics/thorntail directory, always submit a pull request to the Thorntail repository and synchronize the files afterwards.

Prerequisites

A GitHub account with GPG. For more information, see Accounts (required).
The launcher-documentation repository cloned and Git hooks set up.

Contributor Workflow

Create a topic branch in your personal fork of the launcher-documentation repository. If you want to resolve a particular issue with your changes, name the branch issue-$ID, where $ID is the numerical ID of the issue.
Commit and push your changes to the topic branch. Verify your changes:
- Preview the build locally. For more information, see Building locally.
- Optionally validate the books. This step is done automatically by a commit hook at commit time, but you can validate the books manually at any time. Execute the following script:
  $ ./scripts/validate_guides.sh
  
  If there are errors in validation, open the master.xml file in the directory of the book that failed to validate. The validation output should tell you where the issue is. Modify the master.adoc or another included *.adoc file accordingly.
  
  If you are unsure, ask someone from the team for help.
Create a pull request against the branch you based your contribution off. Ensure you also:
1. Label the pull request appropriately. For more information about labels, see [using-github-labels_contributing].
2. Reference the issue that your pull request resolves in the description, using the formulation resolves $ID, where $ID is the numerical ID of the issue. Doing this automatically closes the issue when the pull request is accepted.
After your pull request is created, include a link to the edited document in a comment.
1. Preview the rendered documentation with the changes from the pull request by navigating to the Conversation tab of the pull request, clicking Show All Checks, and Details next to deploy/netlify.
2. Navigate to the edited document.
3. Copy the URL and paste it in a new comment on the pull request.
A team member (a reviewer) will review your changes for factual and stylistic correctness. If the changes are acceptable, the reviewer merges them and closes the pull request. The reviewer may ask you to make further modifications if necessary, or file a pull request against your branch with their suggested modifications.

Do not worry that your pull request was closed, the changes are merged manually as opposed to the GitHub web UI.

3.3.2. Modifying existing content

To modify an existing guide, you must understand how it is structured as well as the basic workflow for modifying it.

Guide structure

Each guide is stored in a separate directory. The main file for the guide is $REPO_HOME/docs/GUIDE_NAME/master.adoc.

Example master.adoc file

include::topics/templates/document-attributes.adoc[] (1)
//var for front-end topics, if below is defined in topic, its used in docs, if not its used in the front end (2)
:docs-topic: (3)

= {name-guide-contrib} (4)


== {name-launcher} Development

This chapter contains information about developing your own runtimes or example applications, contributing changes to existing ones, and improving {name-launcher}.

include::topics/assembly_updating-examples-catalog-for-local-openshiftlocal-testing.adoc[leveloffset=+2] (5)

You can preview the latest state of {name-launcher} by navigating to the link:{launcher-stage}[stage build] of {name-launcher}.

== Filing a code issue
...

1	Includes a file that sets common attributes across all guides.
2	A comment that will not be rendered in the final output.
3	Defines a new attribute called `docs-topic`
4	Sets the document title, in this case it uses the existing attribute `contrib-guide-name`. This attribute is defined in `$REPO_HOME/docs/topics/templates/document-attributes.adoc`.
5	Adds the content from `$REPO_HOME/docs/topics/assembly-updating-examples-catalog-for-local-minishift-testing.adoc` and adds a level offset of two, which means heading levels are offset by two. For example, first-level headings in `$REPO_HOME/docs/topics/assembly-updating-examples-catalog-for-local-minishift-testing.adoc` are rendered as third-level headings.

There are a few important concepts that are heavily used that you need to learn:

document-attributes file: $REPO_HOME/docs/topics/templates/document-attributes.adoc sets common variables that are used across all the guides. Every guide includes this file.
partitioning content: Sections of content in each guide are separated into smaller files. This allows for content to be easily refactored within a guide as well as reused across different guides. The include directive is used to include these files in a piece of content.
modular documentation: An individual piece of content, called a module, is formatted in a specific way, which allows for better reuse across guides.
common topics directory: All of the smaller content files and modules are located in the $REPO_HOME/docs/topics/ directory. This is a common directory that contains all shared files across all guides. To help the build process, the $REPO_HOME/docs/topics/ directory is symlinked in each guide’s directory.

Basic workflow for modifying existing guides

Prerequisites

A text editor for editing AsciiDoc, such as the Atom editor.

Procedure

Find the guide you want to modify and open the master.adoc file in the director of the guide.
Find the section that you want to modify and open the appropriate file.

Many text editors have a way to quickly open a file by name. For example, the Atom editor has a nice Find File command that allows you to quickly search by filename and path.
Make the changes.
Verify the changes by doing a local build and previewing the result.
Submit your changes according to the instructions in Git workflow for making changes.

3.3.3. Adding new guide

To add a new guide to the existing documentation set, perform the following steps:

Adding New Guide

Create a new directory for the guide under docs/, for example docs/my-new-guide.
Create basic infrastructure in the directory of the new guide:
- Create a master.adoc file.
- Create a symbolic link called topics that points to ../topics:
  $ ln -s ../topics topics
- Copy the build_guide.sh script from another guide’s folder. Modify the script so that the GUIDE_HTML_NAME variable is set to the directory name of the new book, for example:
  GUIDE_HTML_NAME=my-new-guide

Add the default content to the master.adoc file:

include::topics/templates/document-attributes.adoc[]

:my-new-guide:

= {my-new-guide-guide-name}

Add the new guide name to the docs/topics/templates/document-attributes.adoc file:
```
:my-new-guide-guide-name: My New Guide
```
Ensure the new guide builds correctly by executing the scripts/build_guides.sh script.
Open the generated HTML file to ensure everything is rendered correctly:
$ firefox html/my-new-guide.html
In the command above, replace firefox with the browser of your choice.
Write the content of the guide. When you are ready for some initial review and feedback, file a pull request to the master branch in the launcher-documentation repository.

3.3.4. Building locally

When you are making a contribution, you should preview your changes before you commit or push them. This section describes the most typical procedure of doing so.

Prerequisites

Asciidoctor

Building a Single Guide

In a console application, navigate to the directory of the book you want to build.
Example:
$ cd $REPO_HOME/docs/contribution-guide/
Replace $REPO_HOME with the real path to the repository.
Execute the build_guide.sh script:
```
$ ./build_guide.sh
```
View the resulting document in the $REPO_HOME/html directory.
Example:
$ firefox $REPO_HOME/html/docs/contribution-guide.html
Replace $REPO_HOME with the real path to the repository, and firefox with the name of your preferred browser.

Building All Guides

In a console application, navigate to the $REPO_HOME/scripts directory.
Build all books by executing the build_guides.sh script:
```
$ ./build_guides.sh
```
View the resulting documents in the $REPO_HOME/html directory:
$ firefox $REPO_HOME/html/docs/*.html
Replace $REPO_HOME with the real path to the repository.

3.3.5. Starting preview server

You can preview the documentation site locally by building and deploying the Docker containers with the documentation site on your machine.

Prerequisites

Docker installed.
Docker daemon running.

Running Preview Server Locally

Execute the scripts/preview_server.sh script. If you execute it as a regular user, you will be asked for administrator privileges because they are required for operating the docker binary.
```
$ scripts/preview_server.sh
```
We do not recommend adding the regular user to the docker group. For more information, see the Related Information section below.
Navigate to http://localhost in your browser.
When you are done, stop the Docker container with the server:
1. Go back to the terminal where the script is running.
2. Press Ctrl + C.

Additional resources

Official Docker installation documentation.
Docker group security:
- Project Atomic: Why we don’t let non-root users run Docker in CentOS, Fedora, or RHEL.
- On Docker Security: Docker group considered harmful.

3.3.6. Validating guides

To ensure that all books can be built, validate them using the automatic script provided in the repository.

Validating all guides

The validation is performed on DocBook XML files generated from the AsciiDoc sources because it is very dificult to perform validations on AsciiDoc sources.

To perform the validation, execute the scripts/validate_guides.sh script:

$ scripts/validate_guides.sh

Excluding individual books from validation

In case a failed validation is an expected behavior—for example if there is a bug in the XML generation—you can remove the book from validation by adding a file named .ci-ignore to the main directory of the book, for example:

$ touch docs/thorntail-runtime/.ci-ignore

To remove the book from validation permanently, commit this file to Git, for example:

$ git add docs/thorntail-runtime/.ci-ignore
$ git commit docs/thorntail-runtime/.ci-ignore -m "Removed Thorntail Guide from validation"

To re-enable validation of the book, remove the .ci-ignore file, for example:

$ rm docs/thorntail-runtime/.ci-ignore

Disabling validation

To disable validation of all books at the same time, create an empty .validation-disabled file in the root directory of the repository:

$ touch .validation-disabled

3.4. Requirements

This chapter contains the requirements your contributions must meet in order to be accepted.

3.4.1. Writing style

Follow the rules of technical writing as described in the following guides; your pull requests will be evaluated against the requirements described in them. If you do not have access to some of them, use the guides that are available to you:

IBM Style Guide: A general guide to writing technical documentation. Available only in print or in commercial digital copies.
Modularization Guidelines: A freely-available guide to writing in the modular style. It includes easy-to-use templates.
Red Hat AsciiDoc Conventions Samples Guide: A freely-available guide about writing particular elements in the AsciiDoc source code, for example GUI buttons, external links, or command blocks. It is important you follow these rules for consistency with other parts of the documentation.
Minimalism in Red Hat Documentation: A Red Hat internal document about applying minimalism to documentation.

Writing rules specific to this repository

When writing new content, adhere to the following rules:

When using the en dash, use the {ndash} attribute.
Do not use:
- – because it breaks validation.
- – even though {ndash} is currently set to it, because the attribute can change in the future.

3.4.2. Writing the modular way

When authoring new content, do not write a monolithic piece of text, but write the information in smaller, self-contained pieces called modules. The modules used in this documentation use the templates described in the Red Hat Modular Documentation Reference Guide.

You will be asked to modify new content that you submit if it does not follow the correct templates.

3.5. Administration

3.5.1. Jenkins CI commands

As a team member, you can operate the Jenkins continuous integration (CI) system from the comment section of every pull request. By default, only pull requests from trusted collaborators are built automatically. You can enable building a particular pull request from an untrusted collaborator or add the pull request author to the list of trusted collaborators.

To issue a command, write it into a comment in a pull request in the {repo-docs-name} repository. Do not write anything else in the comment.

Table 3. List of Jenkins commands
Command	Description
`[test]` or `ok to test`	Enable building for the particular pull request and start a build. Any future pull requests from the author will still need to be approved by team members.
`add to whitelist`	Add the pull request author to the list of trusted collaborators and start a build. Any future pull requests from the author will be built automatically.
`retest this please`	Rebuild the pull request. Use this command when a job failed or there is another error.

3.5.2. Reviewing changes

Ensure you perform all the following actions when reviewing a pull request:

Prerequisites

GitHub account with administration privileges to Jenkins builds. For more information, see Additional resources in this chapter.

Reviewing Pull Request

If there is a comment from the centos-ci user asking Can one of the admins verify this patch?, the pull request comes from an external contributor.

Approve the build or add the author to the list of trusted contributors. For more information, see Jenkins CI commands.

Check if the build passed.

If it failed, review the build log by clicking Show all checks → Details in the box at the bottom of the comment section. In the page that opens, click Console Output. Search for the string Running tests… and diagnose the problem.
Click the Files Changed tab and review the changes. Pay special attention to the following matters:
- Correct use of attributes.
- Correct file placement in the repository layout.
- Correct naming of products.
If you are unsure if the changes render correctly, build the contribution locally:
1. Add the contributor’s repository as a new remote and fetch it.
2. Checkout the source branch of the pull request. You can find it below the pull request title in the from field.
3. Run the preview server locally and review the built documentation.

Additional resources

The Jenkins build configuration file is in the devtools-ci-index.adoc file in the almighty/almighty-jobs repository.

You can find the list of administrators under the admin_list_defaults → admin-list element.
Repository filesystem layout
Starting preview server

3.5.3. Merging contributions

When you or someone else has reviewed the changes in a pull request, you can merge them into upstream/master.

Do not merge your own pull requests unless absolutely necessary. You are accountable for any errors, merge conflicts, or bugs resulting from incorrect merging. Let another contributor with the appropriate repository access privileges do it.

Prerequisites

GitHub account with merge access to the launcher-documentation repository and GPG configured.

Merging a Pull Request

Ensure that you have the contributor’s fork of the launcher-documentation repository in your list of remotes:
```
$ git remote -v
```
To add a remote fork for to you Git directory:
1. Navigate to the contributor’s fork on GitHub.
2. Click the Clone or Download button.
3. Select Use SSH.
4. Copy the repository URL beginning with [email protected]:.
5. Execute the following command, replacing username with the user name of the contributor:
  $ git remote add username [email protected]:username/launcher-documentation.git
6. Use git remote -v to verify that the fork is now listed among your remotes.
7. Execute git remote update to fetch the latest state of the remotes to your working directory.

Create a new branch and set it to track the remote branch that introduces the changes in the pull request:

$ git checkout -b pr-to-merge username/featurebranch

You should see the following message:

Branch pr-to-merge set up to track remote branch <topic_branch> from <username> by rebasing.
Switched to a new branch 'pr-to-merge'

Fetch the latest state of upstream and rebase your topic branch:
$ git fetch upstream $ git rebase upstream/master
If you have multiple commits on your feature branch, squash them into a single commit before merging.
Test if all the books build correctly with your changes by executing the $REPO_HOME/scripts/build_guides.sh script. If the output contains no errors, the guides build correctly.
Checkout your local master branch:
```
$ git checkout master
```
Rebase your local master branch against upstream/master:
```
$ git rebase upstream/master
```
Merge your topic branch into master:
```
$ git merge pr-to-merge
```
Execute $REPO_HOME/scripts/build_guides.sh to test whether the guides build correctly with the changes introduced by your merge.
Push the latest changes into upstream:
$ git push upstream master
The changes are now merged into upstream/master.
Close the pull request for the changes you just merged:
1. Obtain the commit hash of the last commit on master:
  $ git log -1 HEAD
2. Navigate to the pull request on GitHub.
3. Paste the commit following line into a new comment, replacing <commit-hash> with the SHA-1 of your commit:
  merged: <commit-hash>
4. Click Close and comment.

3.5.4. Syncing with Thorntail docs

Some documentation files for the Thorntail runtime are sourced directly from the Thorntail repository. These files are stored in the $REPO_HOME/docs/topics/thorntail directory. Do not edit these files directly; always submit a pull request to the Thorntail repository. When the pull request is accepted and synchronized to the Thorntail product repository, follow the procedure below.

The synchronization script deletes the existing $REPO_HOME/docs/topics/thorntail directory and replaces it with the latest version of the master branch from the upstream repository. Edit the variables in the $REPO_HOME/scripts/sync-with-thorntail/sync.sh script to customize it. The variables are documented in the script.

Some files are not present in the upstream repository because they are generated. The script automatically builds the upstream project with Maven, ensuring these files are not missing.

The hash of the synced upstream commit is stored in the docs/topics/thorntail/docs/commit.hash file.

Prerequisites

Maven installed

Procedure

Execute the $REPO_HOME/scripts/sync-with-thorntail/sync.sh script:
```
$ ./scripts/sync-with-thorntail/sync.sh
```

3.6. Documentation release life cycle

The documentation releases occur periodically, and the work is tracked in JIRA. The person responsible is typically the Documentation Product Manager (DPM), but any member of the team with sufficient privileges can perform the respective tasks. The prerequisites are included separately with each task.

The release tasks are tracked in clones of RHOARDOC-1627.

3.6.1. Creating a RHOARDOC JIRA release

The JIRA Release mechanism is used to track work between two consecutive versions of the published documentation.

Prerequisites

The Project Lead role for the RHOARDOC project in JIRA.

If you are not the Project Lead at the moment, ask the current Project Lead to pass ownership to you.
You are logged in to JIRA.

Procedure

Open the RHOARDOC Versions page in your web browser.
Enter the name for the new release in the Name field on the top of the release list.

The name must correspond to the tag of the new release, that is the expected date of the Fabric8 Launcher documentation publishing in the ISO format, for example 2018-12-07 for December 7, 2018.

If the publishing date changes, rename the release. Do not rename the release for re-tags, for example 2018-12-07_2.
Enter a suitable description in the Description field:
- For scheduled releases, use Scheduled release.
- For runtime or unscheduled releases, describe what is being released, for example Eclipse Vert.x 3.6.
Enter the expected release date in the Release date field.
Click Add to create the release.

3.6.2. Releasing launcher.fabric8.io docs

This section contains all information you need to release a new version of the documentation set to production. This update can happen anytime after the catalog has been updated, including after the release train has been completed.

Releasing New Version to Production

Synchronize the Thorntail sources. For more information, see Syncing with Thorntail docs.
Tag the release:
1. Execute the tag_release.sh script in the $REPO_HOME/scripts directory:
  $ ./tag_release.sh
  
  The script automatically tags the commit with the current date in the YYYY-MM-DD format. If you want to tag with a different date or manually, execute the following command:
  
  $ git tag 2017-04-21
  
  If you are re-releasing the same day, a suffix _2, _3, etc. is appended.
2. Push the changes and tags:
  $ git push --tags $REMOTE
  
  Replace $REMOTE with the name of the upstream remote.
Request publication:
1. File a pull request in the openshiftio/saas-launchpad repository, where you change the hash value to the hash of the commit you want to publish from the launcher-documentation repository. Usually, this will be the latest commit in the master branch.
2. Wait for the pull request to be accepted. When that happens, verify that the production build succeeded.
3. Once your changes have been merged and the build succeeds, delete the topic branch you used to introduce the update.
  $ git branch -d $TOPIC_BRANCH_NAME

Next steps

Synchronize the sources to the Customer Portal stage.
Announce the publication.

3.6.3. Releasing Customer Portal docs

To release Customer Portal docs, follow the instructions in the RHOAR docs repository (VPN required).

3.6.4. Documentation publication announcement

When the documentation is updated, send an e-mail containing a link to the new version and the diff from the live version to the following mailing lists:

Send the e-mail also to the following mailing lists if the publication concerns the respective runtime specifically:

Node.js: [email protected]
Spring Boot: [email protected]
Thorntail: [email protected]
Vert.x: [email protected]

Example 2. Sample e-mail content

You can use the following template for the e-mail:

Replace the placeholders with real data before sending.

Hello,

We have released the Fabric8 Launcher documentation today:

Docs link: https://launcher.fabric8.io/docs/
Tag: https://github.com/fabric8-launcher/launcher-documentation/releases/tag/$NEW_TAG
Diff: https://github.com/fabric8-launcher/launcher-documentation/compare/$PREVIOUS_TAG...$NEW_TAG

We have also synced the documentation to the Customer Portal stage:

Docs link: https://access.redhat.com/documentation/red-hat-openshift-application-runtimes/
Tag: $LINK_TO_THE_TAG
Diff: $LINK_TO_THE_COMPARISON

The following issues were fixed:

https://issues.jboss.org/projects/RHOARDOC/versions/$RELEASE_ID

Please reach out to [email protected] if you have any questions.

3.6.5. Concluding a RHOARDOC JIRA release

When the work is done and the documentation is published, the JIRA release must be concluded.

Prerequisites

The Project Lead role for the RHOARDOC project in JIRA.

If you are not the Project Lead at the moment, ask the current Project Lead to pass ownership to you.
The release to be concluded.
You are logged in to JIRA.

Procedure

Open the RHOARDOC Releases page in your web browser.
Click on the name of the release to be concluded.
Check the following to ensure that the release is correct:
- All issues from the last sprints are present in the release.
  
  Use the RHOARDOC issues without Release filter to view completed issues that do not have the Fix Version/s field set, and so they do not appear in this release.
  
  Assign the Fix Version/s field to these issues:
  1. Click the Tools button in the top right corner of the page.
  2. From the menu, select all $COUNT issue(s), where $COUNT is the number of issues in the view.
  3. In the next page, select the issues completed in this release and click Next.
  4. Select Edit Issues from the list and click Next.
  5. Check Change Fix Version/s, select Add to existing in the menu on the side if it is not selected already, and select the appropriate release from the empty menu. Your release is listed under Unreleased Versions.
    
    At the bottom of the page, uncheck Send mail for this update and click Next.
  6. When JIRA finishes making the changes, click Acknowledge.
- All issues in the release are in the Resolved or Verified state.
  
  If they are not, work with the assignees to ensure the issues are resolved and verified by the QE team if applicable.
Close all issues when the documentation is published:
1. On the page with the release, click Issues done.
2. In the top right corner, click View in Issue Navigator.
3. Click the Tools button in the top right corner of the page.
4. From the menu, select all $COUNT issue(s), where $COUNT is the number of issues in the view.
5. In the next page, select all issues by clicking the check box in the header of the table and click Next.
6. Select Transition Issues from the list and click Next.
7. Select Close Issue from the list and click Next. If there are multiple Close Issue options available, select the one that moves all statuses to CLOSED.
8. When JIRA finishes making the changes, click Acknowledge.
On the page with the release, click Release in the top right corner to conclude the release.

3.7. Issues

3.7.1. RHOARDOC JIRA workflow

The issues in the RHOARDOC JIRA project have the following lifecycle:

Standard RHOARDOC JIRA lifecycle

NEW

The issue is new.

When the Assignee is set to Unassigned or the DPM, it can denote an issue that might not have been triaged yet.

OPEN

The assignee accepts ownership of the issue.

CODING IN PROGRESS

The assignee is actively working on addressing the issue.

PULL REQUEST SENT

The assignee has submitted a draft of the new or updated content for review in a pull request.

RESOLVED

Specify the current release in the Fix Version/s field when setting the issue to RESOLVED.

The issue is fixed from the documentation team’s perspective.

If the issue has only Fabric8 Launcher impact, this is the final status of the issue before it is closed.

READY FOR QA

The issue is ready for review by the QE team on the Customer Portal stage.

If the issue affects the Customer Portal in addition to the Fabric8 Launcher, set the issue to this status by clicking the Hand Over to QA button.

QA IN PROGRESS

The QE team is in the process of testing the new or updated content.

VERIFIED

The new or updated content has passed QE.

CLOSED

The issue has been addressed.

Other statuses

REOPENED: The issue was closed, but further updates or changes are required.

3.7.2. RHOARDOC JIRA fields

The following fields are used in the RHOARDOC JIRA project:

RHOARDOC JIRA fields

Summary

A brief description of the issue.

This is the displayed name of the issue. Include important information about the issue like its nature and where it occurs, but be brief.

Issue Type

The type of the issue.

The following types are used:

Bug: An error in the documentation.
Enhancement: An improvement or a missing part of the documentation.
Epic: A large requirement. Multiple JIRAs that track individual work items are linked to it.
Task: A task to be done.

Priority

The importance of the issue.

The following priorities are used:

Blocker: The release of the documentation can not proceed until the issue is fixed.
Critical: The issue must be resolved quickly, but is not blocking.
Major: The default importance of an issue.
Minor: The issue is of low importance can be deferred to a later date.

Epic Link

The epic that the issue is part of.

Only valid for Bugs, Enhancements and Tasks.

Sprint

Which sprint the issue belongs to.

Only put an issue in a sprint if you are reasonably confident you can finish it within the sprint.

Story Points

The estimated amount of effort the issue requires.

Numbers from the Fibonacci sequence are used, each denoting an increasing workload: 1, 2, 3, 5, 8, 13. If you believe an issue requires more than 13 points, it is likely an Epic and should be separated into sub-tasks.

The recommended number of story points per person per sprint is 13 in total.

Description

A complete description of the issue.

Status

The current status of the issue. For more information, see [rhoardoc-jira-workflow].

Resolution

How the issue was resolved.

By default, it is set to Unresolved.

Fix Version/s

The release when the resolution of the issue was—or will be—published.

Assignee

The person selected to address the issue.

The issue is unassigned if set to Unassigned, or if it is assigned to the DPM and has the NEW status.

Due Date

A specific date before which the issue should be resolved.

If not set, check the linked epic or parent issue if any. They might have a Due Date set.

3.8. Quality control

3.8.1. Quality control requirements for documentation

To ensure good quality of the documentation, the following requirements must be met:

Each pull request must be reviewed by at least:
- One member of the documentation team (different from the submitter).
- One member of either the engineering team or the QE team.
When a new version of the documentation is pushed to the Customer Portal stage, a member of the QE team must review the diff between the live version and the new version.

3.8.2. Verifying pull requests

Technical writers and members of the QE team must verify pull requests in the launcher-documentation repository before they are merged to ensure high quality of the documentation. Reviews from other stakeholders and the community are welcome.

Prerequisites

A GitHub account.
You account subscribed to the launcher-documentation repository.
To subscribe to the repository:
1. In your browser, navigate to https://github.com/fabric8-launcher/launcher-documentation.
2. In the upper right corner, click the Watch button. If the button says Unwatch, you are already subscribed.

Procedure

When you see a notification of a new pull request, navigate to it and review the contents according to the description in the pull request and the issue it resolves.

If there is no reference to an open issue and the change is not trivial, request that an issue be created.
1. Preview the rendered documentation with the changes from the pull request by navigating to the Conversation tab of the pull request, clicking Show All Checks, and Details next to the revealed deploy/netlify.
  
  Even though the page says Prepare to launch… you are in the right place. Click Docs in the top bar to navigate to the edited documentation.
2. If you are a writer, focus mainly on the requirements described in the Requirements section.
3. If you are a member of the QE team, focus mainly on the technical accuracy of the document. You can also check the writing style or errors, but it is not required.
Request changes if the document is not correct by doing one of the following:
- Open the Files changed tab in the pull request and click Review changes → Request changes.
  
  Fill in the general description of the changes you require. Comment on individual problems directly in the code using the comment functionality in GitHub.
- Open a separate pull request against the private branch of the original submitter.
Repeat the process as necessary.
When your requested changes are addressed, approve the pull request.

Appendix A: Upstream runtime project development resources

TBD

Appendix B: Glossary

B.1. Product and project names

developers.redhat.com/launch: developers.redhat.com/launch is a stand-alone getting started experience offered by Red Hat for jumpstarting cloud-native application development on OpenShift. It provides a way of creating functional example applications as well as an easy way to build and deploy these example applications on OpenShift.
Fabric8 Launcher: The Fabric8 Launcher is the upstream project on which developers.redhat.com/launch is based.
Minishift or CDK: An OpenShift cluster running on your machine using Minishift.

B.2. Terms specific to Fabric8 Launcher

Example: An application specification, for example a web service with a REST API.

Examples generally do not specify which language or platform they should run on; the description only contains the intended functionality.

Example application: A language-specific implementation of a particular example on a particular runtime. Example applications are listed in an examples catalog.

For example, an example application is a web service with a REST API implemented using the Thorntail runtime.

Examples Catalog: A Git repository that contains information about example applications.

Runtime: A platform that executes an example application. For example, Thorntail or Eclipse Vert.x.