Contributing

This page covers how to contribute to the Showroom platform — the Ansible collection, Helm charts, container images, and the Nookbag UI.

Repository Map

Repository What to contribute

agnosticd/showroom

Ansible roles, collection packaging, and this documentation.

rhpds/showroom-deployer

Helm charts (showroom-single-pod, showroom, zerotouch).

rhpds/showroom-images

Container image Dockerfiles and build pipelines.

rhpds/nookbag

The zero-touch UI bundle (JavaScript/CSS).

rhpds/showroom_template_nookbag

The content repository template.

Collection Versioning

The collection follows semantic versioning. Tags are in the format v{major}.{minor}.{patch} (e.g. v1.5.2).

  • Patch — bug fixes, documentation updates, image version bumps.

  • Minor — new features, new role variables, new tab service support.

  • Major — breaking changes to role interfaces or behaviour.

To create a release:

git tag v1.5.0
git push origin v1.5.0

Catalog items reference the collection version in requirements_content:

requirements_content:
  collections:
    - name: https://github.com/agnosticd/showroom.git
      type: git
      version: v1.5.0

Testing with Test Catalog Items

The tests/ directory in agnosticv contains test catalog items specifically for validating Showroom changes:

Catalog item What it tests

tests/showroom-ocp4

OCP4 deployment with Wetty terminal, OCP console embed, and the ocp-example branch.

tests/showroom-vm

VM deployment with two terminals and the vm-example branch.

These test items expose the showroom_collection_version as a catalog parameter, so you can test a specific branch or tag without modifying the config:

  1. Push your changes to a branch on the collection repo.

  2. Order the test catalog item from demo.redhat.com.

  3. Set Showroom Collection Version to your branch name (e.g. my-feature-branch).

  4. Verify the deployment works as expected.

Development Workflow

Collection changes

  1. Fork and clone agnosticd/showroom.

  2. Make changes to roles, defaults, tasks, or templates.

  3. Test locally using a standalone playbook if possible (see OCP4 examples or VM examples).

  4. Test on the platform using the test catalog items.

  5. Open a pull request.

Content template changes

  1. Fork and clone showroom_template_nookbag.

  2. Create a new branch (the test catalog items can point to any branch).

  3. Test locally with Podman (see Creating a Content Repository).

  4. Test on the platform by updating the test catalog item’s content ref.

Helm chart changes

  1. Fork and clone showroom-deployer.

  2. Edit charts under charts/.

  3. Test with helm template and oc apply -f -.

  4. PRs are automatically linted and tested by CI.

Image changes

  1. Fork and clone showroom-images.

  2. Edit the Dockerfile for the image you are changing.

  3. Build and test locally:

    cd content/
podman build -t showroom-content:dev .

  4. Tag and push to trigger the CI pipeline:

    git tag showroom-content-v1.5.0
git push origin showroom-content-v1.5.0

Documentation

This documentation site is built with Antora from the docs/ directory in the collection repo.

To preview locally:

cd docs/
podman run --rm -v $PWD:/antora -p 8080:8080 -i -t ghcr.io/juliaaano/antora-viewer

Documentation changes go through the same PR process as collection changes.

Getting Help