Skip to content

Latest commit

 

History

History
352 lines (271 loc) · 18.8 KB

CONTRIBUTING.adoc

File metadata and controls

352 lines (271 loc) · 18.8 KB
Raw

Contributing to App Services guides

Prerequisites

The guides toolchain is heavily dependent on AsciiDoc and Node.

  1. Install your favourite tool for editing AsciiDoc (for example, VS Code or IntelliJ).

  2. Install the latest Active long-term support (LTS) version of Node (node) .

  3. Install Node Version Manager (nvm).

  4. After you install node and nvm, run the following commands from your local app-services-guides repository’s top-level directory (for example, Users/myname/mylocalGitRepos/app-services-guides/):

    nvm install && nvm use
    npm --prefix .build install

  5. If you will be generating modular docs, install the following software:

    1. Java 15 or later

    2. Apache Maven 3.x

    3. Asciidoctor 2

Creating a guide

To create a new guide:

  1. Decide on the identifier for your guide. The identifier should be concise and accurately describe the guide. For example the guide for using Streams for Apache Kafka with kafkacat has the identifier kafkacat. The identifier must be written in lowercase kebab case.

  2. Create a new directory, using the identifier as the name.

  3. Use the content from one of README.adoc files in another existing guide folder as a template to modify and add documentation to the new file.

  4. If you need to add attributes, don’t add them directly to the document but put them in _attributes.adoc and then run

  5. When you add section ids (e.g. [id="proc-running-quarkus-example-application-using-operator_{context}"]}) to a guide, the section id must be globally unique within the entire app-services-guides repository - if they conflict with a section id in another guide modular docs generation will fail. The `_{context} is not considered part of the id, and does not provide any form of uniqueness for the id.

    npm --prefix .build run generate:attributes

Repository structure

This repository is designed to be usable for people browsing it on GitHub, as well as reusable (for example, in quick starts) in implementations of services such as Streams for Apache Kafka or Service Registry.

Each guide is contained in a separate directory. The directory must contain:

README.adoc

contains the guide, written using AsciiDoc.

Additionally, the directory may contain:

quickstart.yml

if the guide is also a quick start, then this file defines the quick start. It normally references snippets of content from the guide that allow for the DRY principle to be applied.

pantheon.yml

this repository supports the Pantheon 2.x modular documentation management and publication system built on top of AsciiDoc. This file defines how the quick start snippets can be loaded from Pantheon rather than directly by Asciidoctor.js.

Sample code

Many guides have associated code (and other artifacts such as build files, deployment descriptors and scripts). These are also placed in the directory.

There are a number of additional directories which don’t contain guides. These all start with ..

The app-services-guides repository’s .build directory contains a TypeScript project that is used to provide:

  • a local preview for quick starts

  • a production build

  • targets to lint all guides

The .github directory contains GitHub Actions that are used to validate pull requests.

Attribute injection

AsciiDoc attributes are injected into all files by a code generator. Do not edit the attribtes in the source files, but instead edit the _attributes.adoc file and add them there. Then run:

npm --prefix .build run generate:attributes

The code generator looks for a block that starts with:

////
START GENERATED ATTRIBUTES
WARNING: This content is generated by running npm --prefix .build run generate:attributes
////

And ends with:

////
END GENERATED ATTRIBUTES
////

Anything between the start of the start block and the end of the end block will be replaced by the code generator when attribute generation runs.

A check exists in the continuous integration job that validates that generation is up to date. If generation is not up to date then continuous integration will fail.

The file ./doc/.adocignore contains a list of globs which will be ignored by the attribute injector

Creating a quick start

Many of the guides in this repository are also available as "quick starts". Quick starts are available in the Web UI for the Streams for Apache Kafka and are based on the PatternFly project.

We would always recommend starting with a guide and then adding the quick start metadata. This will allow your content to be accessible both in the Web UI and via GitHub.

Adding support for quickstart.yml to your IDE

A schema for quickstart.yml is provided in quickstart.schema.json. To load this into your IDE:

Previewing the quick starts locally

You can preview the quick start catalog and the quick start pages locally. (Note that the preview shows all of the quick starts in the app-services-guides repository, not just one quick start.)

  1. Verify that you installed Node (node) and Node Version Manager (nvm) as described in the Prerequisites section at the top of this page.

  2. Make sure that your working directory is your local app-services-guides repository’s .build directory, for example:

    cd app-services-guides/.build

  3. Install the project dependencies:

    npm install

  4. Start the web server

    npm run start:dev

    (Optional) You can run the local preview with custom attributes by specifying an attributes file on the command line. The attributes file can be either an AsciiDoc file (only the attributes declared in the document are used) or a YAML file.

    export ATTRIBUTES_FILE=<path to attributes file>
npm run start:dev

Your web browser should open automatically to http://localhost:9001 and show the quick start catalog.

"Hot reload" is enabled, which means that saving a change to any quickstart.yml or *.adoc file will trigger a rebuild and reload the content in the browser automatically.

Converting your guide into a quick start

  1. Add a quickstart.yml file to the same directory as the README.adoc for the guide.

  2. All quick starts must have an apiVersion: console.openshift.io/v1, and a kind: QuickStarts as well as an associate array metadata with a member with key name, which must be given the identifier as a value:

    apiVersion: console.openshift.io/v1
kind: QuickStarts
metadata:
  name: <identifier>

  3. The spec associative array defines the quick start content. Start by defining the content type of the quickstart (Quick start / Documentation), the version of the quick start, the base64 value of an icon to use, and how long the quick start should take to complete.

    spec:
  version: <quick start version>
  type:
    text: Quick start // or Documentation if it has an external link
    color: green // orange for Documentation
  icon: data:image/svg+xml;base64,<base64-string> // you can find the base64 string here: https://base64.guru/converter/encode/image
  durationMinutes: <duration>

  4. The displayName of the quick start is used both in the catalog and as the heading for the quick start drawer.

      displayName: !snippet/title README.adoc#<id>

    The !<tag name> syntax represents a custom data type in YAML. When the quickstart.yml document is deserialized by the YAML parser, the quick start renderer is able to inject content. The quickstart.yml parser makes use of custom data types to inject content from an AsciiDoc file into the quick start. This allows us to better comply with the DRY principle.

    The tag !snippet/title allows us to use a title from an AsciiDoc file. In order to this we provide the relative path to an AsciiDoc source file (in this case the README.adoc that contains the guide content), followed by the # symbol, followed by the id of a block.

    Other tags available are !snippet (which renders the content of the block as HTML) and !snippet/proc (which renders a procedure as a quick start task). All the custom data types described use the same scheme to reference a block.

  5. The description will be rendered in the quick start catalog below the display name.

      description: !snippet README.adoc#description

    The !snippet tag type allows us to use the content of a block; it achieves this by rendering the contents of the referenced block as HTML and then using that HTML. The reference scheme is the same as described earlier.

    Note
    		 In AsciiDoc A block contains the content of any children blocks (e.g. a Level 1 section block contains any Level 2, 3, 4, or 5 section blocks until another Level 1 section block is declared). This can cause a lot of unneeded content to be rendered. A clear understanding of the way blocks work in AsciiDoc is helpful to use the !snippet tag.

  6. The prerequisites of the quick start are rendered in the quick start catalog.

      prerequisites:
    - Requirement 1
    - Requirement 2

  7. The introduction is used as the content for the first page of the quick start.

      introduction: |-
    *Lorem* ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
    Note
    		 A !snippet tag could be used here, but in this case we chose to inline the text into the quickstart.yml as we did not have suitable text to reuse in the guide. Markdown is used to provide formatting for inline text.

  8. The conclusion is used for the content of the final page of the quick start.

      conclusion: |-
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

  9. The nextQuickStart list is rendered at the end of the quick start to provide the user with next steps. The value of each list member should be the identifier of another quick start in this repository.

  10. The bulk of the quick start is the tasks. The task can be fully described using quickstart.yml however we recommend using the !snippet/proc tag to reference an existing procedure.

    When building the quick start from the procedure the parser will use the procedure introduction followed by the procedure body for the body of the task. It will use the procedure verification as the review instructions. The procedure additional resources and prerequisites are ignored as the quick start format does not have equivalent areas.

    Any section of the task can be overridden by providing the relevant entry in the associative array. In this case a member with key proc is used to specify the !snippet/proc tag.

  11. Verify that the quick start is rendering as expected by previewing it locally.

Environment Variable in guides and code

One of the benefits of displaying guides within the Web UI is that allows us to have much greater context on what the user is doing.

In keeping with Kubernetes, we recommend using environment variables as a method of providing configuration to applications.

Highlighting page elements from a quick start

  1. To highlight items from a quick start, first the target item needs to have a data attribute: data-quickstart-id="something"

  2. Then in asciidoc, the trigger element needs to have the data-highlight__something class/role, where the part after data-highlight__ matches the data-quickstart-id of the target Here are some examples:

    • link:[Click me to highlight the logo, role="data-highlight__logo"]

    • link:[Click me to highlight the Home nav item, role="data-highlight__home"]

    • link:[Click here to highlight the Quick starts nav item, role="data-highlight__quickstarts"]

Integrating the quick start with Pantheon

Pantheon 2.x is a modular documentation management and publication system built on top of AsciiDoc.

Note
 Currently, Pantheon is integrated with quick starts during the Webpack build, meaning that to refresh the content you must rebuild the quick starts.

In order to use content published by Pantheon you must map the !snippet and snippet/* tags that need to use Pantheon to a Pantheon UUID and type. Additionally, you must provide the base URL of your Pantheon server.

  1. Create a pantheon.yml file alongside the quickstart.yml file

  2. For each tag that needs to reference Pantheon, add it as a member to the root associative array in the pantheon.yml with the <tag> <tag value> as the key. For example, to map !snippet/title README.adoc#using-quick-starts to a Pantheon instance hosted on pantheon.example.org:

    "!snippet/title README.adoc#using-quick-starts": https://pantheon.example.org/api/assembly/variant.json/53dfb804-2038-4545-b917-2cb01a09ef91
    Note
    		 Any tags not referenced in pantheon.yml will continue to use the AsciiDoc source.

    The simplest form of mapping is to simply copy and paste the API URL in. The !snippet/title tag will use the value of the title key (in either the assembly or the module). The !snippet/proc tag will use the value of the body (in either the assembly or the module) and must reference a module directly. The !snippet tag will use the value of the body (in either the assembly or the module), searching for the id in the html.

    If more control is required the value of the key in the root associative array should be an associative array, with:

    • an uuid member that specifies the uuid of the module or assembly to load (required)

    • a type member that specifies the type (module or assembly to load) (required)

Additionally, you may choose to add:

  • a jsonPathExpression member that overrides the JSON Path to the value in the JSON document returned by the Pantheon API. By default, !snippet uses $.*.body, !snippet/title uses $.\*.title and !snippet/proc uses $.\*.body.

  • a cssSelector member that overrides the CSS selector applied to the body element of the document returned by the Pantheon API. By default, !snippet uses #<id> whilst !snippet/title and !snippet/proc do not use a css selector.

Warning
 When using the local preview with Pantheon the default AsciidoctorJS templates are used rather than the Pantheon templates because the Pantheon template format (Haml) is not supported by Asciidoctor.js
Note
 The schema for pantheon.yml is in pantheon.schema.json and can be used in the same way as the quickstart.schema.json.

Draft quick starts

Draft quick starts are hidden from end users. To set a quick start as draft, add this to the quickstart.yml metadata section:

metadata:
  name: my-quickstart
  annotations:
    draft: true
    ...

Generating modular documentation

We generate Modular Documentation from this repository, using npm scripts.

Every time you submit a pull request a job will run that will verify the generation of modular documentation will succeed.

Every time a pull request is merged to main, the modular documentation for the content in the HEAD of main will be generated to the modular docs branch.

To run the modular documentation generation locally run:

npm --prefix .build run generate:modular-docs

Having run the modular documentation generation, you can then push the changes up to the modular-docs branch on GitHub run:

npm --prefix .build run commitandpush:modular-docs

To run the modular documentation generation locally, and then push the changes up to the modular-docs branch on GitHub all in one go, run:

npm --prefix .build run publish:modular-docs

To run the modular documentation generation locally, and then push the changes up to a different branch and/or repository, run:

npm --prefix .build run publish:modular-docs --repo=<git repo> --branch=<branch>

Submitting a pull request

  1. Before submitting a pull request, make sure the attributes in documents are up to date by running

    npm --prefix .build run generate:attributes
    Note
    		 If you check in out of date attributes the build will fail

  2. Having create the PR, automated tests will run. If they fail, use the error log to determine the problem, and fix it

  3. Once your build is passing ask for review from a Subject Matter Expert (who will check for accuracy), a writer (who will check that the content is up to expected quality for substance, formatting, style, structure and consistency), and a developer who will ensure the steps covered by the quick start are the end to end test suite.

Adding new product to repository

  1. Go to ./docs/.product-mapping.yml file and add new product to the list of products.

  2. Under directories please provide all directories with quickstarts that should be included in the product.

  3. Go to .github/workflows/modular-docs-publish.yaml file and add new product values under "matrix.include" section This will push proper modular documentation to the modular-docs-"product_name" branch on release

Releases

Guides are released by creating tag in format vx.x.x - where x is number representing semver version. Releases should be created at major milestones based on the documented features being already published and available to users.

  1. Use following link to create new release link: https://github.com/redhat-developer/app-services-guides/releases/new

  2. Please provide tag name. For example v0.1.0

  3. Please provide the same value for release title (v0.1.0)

  4. Please click on "Autogenerate Release Notes" to generate release notes

  5. Select Publish release to create release

Note
 CICD process will automatically synchronize changes with downstream on release