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.
-
A GitHub account
-
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 FilegithubRepo: 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.
-
Minishift or CDK installed and running.
-
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.
-
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
withdnf
):# 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
withdnf
):
# 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.
|
The command options you use to configure gpg2
or gpg
are the same for both binaries.
-
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 togpg
.$ 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.
-
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. |
. ├── 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.
|
3.2.3. Branches and tags
The following branches and tags are used in the launcher-documentation repository:
Branch | Content |
---|---|
master |
The latest version of the documentation in development. |
Branch | Content |
---|---|
Date in the |
The documentation as released on the particular date. |
Date in the |
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.
|
-
A GitHub account with GPG. For more information, see Accounts (required).
-
The launcher-documentation repository cloned and Git hooks set up.
-
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 themaster.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:
-
Label the pull request appropriately. For more information about labels, see [using-github-labels_contributing].
-
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.
-
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
. -
Navigate to the edited document.
-
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
.
master.adoc
fileinclude::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
-
A text editor for editing AsciiDoc, such as the Atom editor.
-
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:
-
Create a new directory for the guide under
docs/
, for exampledocs/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 theGUIDE_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.
-
Asciidoctor
-
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, andfirefox
with the name of your preferred browser.
-
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.
-
Docker installed.
-
Docker daemon running.
-
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 thedocker
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:
-
Go back to the terminal where the script is running.
-
Press
Ctrl + C
.
-
-
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.
Command | Description |
---|---|
|
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 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. |
|
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:
-
GitHub account with administration privileges to Jenkins builds. For more information, see Additional resources in this chapter.
-
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:
-
Add the contributor’s repository as a new remote and fetch it.
-
Checkout the source branch of the pull request. You can find it below the pull request title in the from field.
-
Run the preview server locally and review the built documentation.
-
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. |
-
GitHub account with merge access to the launcher-documentation repository and GPG configured.
-
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:
-
Navigate to the contributor’s fork on GitHub.
-
Click the Clone or Download button.
-
Select Use SSH.
-
Copy the repository URL beginning with
[email protected]:
. -
Execute the following command, replacing
username
with the user name of the contributor:$ git remote add username [email protected]:username/launcher-documentation.git
-
Use
git remote -v
to verify that the fork is now listed among your remotes. -
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 againstupstream/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:
-
Obtain the commit hash of the last commit on
master
:$ git log -1 HEAD
-
Navigate to the pull request on GitHub.
-
Paste the commit following line into a new comment, replacing <commit-hash> with the SHA-1 of your commit:
merged: <commit-hash>
-
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.
-
Maven installed
-
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.
-
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.
-
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.
-
Synchronize the Thorntail sources. For more information, see Syncing with Thorntail docs.
-
Tag the release:
-
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. -
Push the changes and tags:
$ git push --tags $REMOTE
Replace
$REMOTE
with the name of the upstream remote.
-
-
Request publication:
-
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 themaster
branch. -
Wait for the pull request to be accepted. When that happens, verify that the production build succeeded.
-
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
-
-
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]
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.
-
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.
-
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:
-
Click the Tools button in the top right corner of the page.
-
From the menu, select all
$COUNT
issue(s), where$COUNT
is the number of issues in the view. -
In the next page, select the issues completed in this release and click Next.
-
Select Edit Issues from the list and click Next.
-
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.
-
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:
-
On the page with the release, click Issues done.
-
In the top right corner, click View in Issue Navigator.
-
Click the Tools button in the top right corner of the page.
-
From the menu, select all
$COUNT
issue(s), where$COUNT
is the number of issues in the view. -
In the next page, select all issues by clicking the check box in the header of the table and click Next.
-
Select Transition Issues from the list and click Next.
-
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.
-
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:
- 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.
- 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:
- 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.
-
A GitHub account.
-
You account subscribed to the launcher-documentation repository.
To subscribe to the repository:
-
In your browser, navigate to https://github.com/fabric8-launcher/launcher-documentation.
-
In the upper right corner, click the Watch button. If the button says Unwatch, you are already subscribed.
-
-
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. -
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 revealeddeploy/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. -
If you are a writer, focus mainly on the requirements described in the Requirements section.
-
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.