Contributing Guide

This guide explains how to contribute to both the OpenShift Agent Install Helper project and its documentation website.

Table of Contents

Getting Started

Prerequisites

Quick Start

# Clone the repository
git clone https://github.com/your-org/openshift-agent-install.git
cd openshift-agent-install

# Set up documentation website locally
./scripts/install-jekyll.sh
./scripts/serve-site.sh

Repository Structure

openshift-agent-install/
├── docs/                    # Documentation website
│   ├── _config.yml         # Jekyll configuration
│   ├── adr/                # Architecture Decision Records
│   ├── assets/             # Images and other assets
│   └── *.md               # Documentation pages
├── examples/               # Example configurations
├── playbooks/             # Ansible playbooks
├── scripts/               # Utility scripts
├── e2e-tests/             # End-to-end tests
├── hack/                  # Development scripts
└── site-config/           # Site configuration files

Setting Up Development Environment

For Documentation Website

  1. Install Ruby and Bundler: 
    # On RHEL/CentOS
sudo dnf install ruby ruby-devel
gem install bundler

# On Ubuntu/Debian
sudo apt-get install ruby ruby-dev
gem install bundler
  2. Install Jekyll and dependencies: 
    ./scripts/install-jekyll.sh
  3. Start local server: 
    ./scripts/serve-site.sh
  4. Visit http://localhost:4000/openshift-agent-install/

For Project Development

  1. Set up Python environment (if needed)
  2. Install Ansible
  3. Configure development tools

Documentation Website

Adding New Pages

  1. Create a new Markdown file in docs/: 
    ---
layout: default
title: Your Page Title
description: Brief description of the page
---

# Your Page Title
Content goes here...
  2. Add to navigation:
    • Update relevant section in docs/index.md
    • Link from related pages

Adding ADRs

  1. Copy template from existing ADR
  2. Number sequentially
  3. Add front matter: 
    ---
layout: default
title: "ADR-XXXX: Your ADR Title"
description: "Architecture Decision Record for..."
---
  4. Update docs/adr/index.md

Local Testing

cd docs
bundle exec jekyll serve --host 0.0.0.0 --port 4000 --baseurl /openshift-agent-install

Making Contributions

Branch Strategy

Commit Messages

type(scope): Brief description

Detailed description of changes

Types:

Documentation Changes

  1. Make changes in docs/ directory
  2. Test locally
  3. Commit with docs: prefix
  4. Create pull request

Code Changes

  1. Create feature branch
  2. Make changes
  3. Add tests
  4. Update documentation
  5. Create pull request

Pull Request Process

  1. Before Creating PR
    • Test changes locally
    • Update documentation
    • Add tests if needed
    • Ensure CI passes
  2. PR Description 
    ## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Other (specify)

## Testing Done
Describe testing performed

## Documentation
- [ ] Documentation updated
- [ ] No documentation needed
  3. Review Process
    • Automated checks must pass
    • At least one maintainer review
    • Documentation review if needed
  4. After Merge
    • Delete feature branch
    • Update related issues
    • Monitor deployment

Style Guides

Documentation Style

Markdown Guidelines

Code Style

GitHub Pages

The documentation is automatically deployed to GitHub Pages when changes are merged to main. The deployment process:

  1. GitHub Action builds site
  2. Deploys to GitHub Pages
  3. Available at project URL

Troubleshooting Deployments

Getting Help

Additional Resources