Contribution Guide

Navigate to the openshiftio/booster-catalog repository, which hosts the default booster 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:

Commit and push your changes to your forked repository.

Open the Single-node OpenShift Cluster 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.

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.

Start using your Fabric8 Launcher tool to launch booster applications.

Generate a new GPG key.

Add the GPG key to your GitHub account.

Configure GPG with git on your machine.

In the launcher-documentation repository, set automatic signing with your GPG key:

$ git config commit.gpgsign true

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

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

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:

Create a pull request against the branch you based your contribution off. Ensure you also:

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:

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

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.

In a console application, navigate to the directory of the book you want to build.

$ cd $REPO_HOME/docs/contribution-guide/

Execute the build_guide.sh script:

$ ./build_guide.sh

View the resulting document in the $REPO_HOME/html directory.

$ firefox $REPO_HOME/html/docs/contribution-guide.html

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

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

Navigate to http://localhost in your browser.

When you are done, stop the Docker container with the server:

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.

Check if the build passed.

Click the Files Changed tab and review the changes. Pay special attention to the following matters:

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:

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

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

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

Close the pull request for the changes you just merged:

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

$ ./scripts/sync-with-thorntail/sync.sh

Synchronize the Thorntail sources. For more information, see Syncing with Thorntail docs.

Tag the release:

Request publication:

Announce the publication:

Hello,

We have released the upstream 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

The following issues were fixed:

...

We plan to do a downstream docs sync on $RELEASE_DATE.

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

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.

Request changes if the document is not correct by doing one of the following:

When your requested changes are addressed, approve the pull request.