Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
855 lines (617 loc) · 32 KB

CONTRIBUTING.md

File metadata and controls

855 lines (617 loc) · 32 KB
Raw

Contributing to KubeStellar Docs

Thank you for helping improve the KubeStellar documentation site. This repository powers kubestellar.io and has its own contribution workflow, separate from the main kubestellar/kubestellar repository.

Use this guide for documentation, navigation, theme, and site changes in kubestellar/docs. Only use the main repo's contributing guide when your work also changes product code outside this repository.

What lives in this repository

  • docs/content/ — documentation source files (.md and .mdx)
  • docs/content/<project>/nav.yaml — sidebar navigation for each project (and docs/content/{contributing,community,news}/nav.yaml for the shared sections)
  • src/ — site code, theme customizations, and shared components
  • public/ — static assets used by the docs site

If you are fixing a typo, adding a guide, moving pages in the navigation, or adjusting the docs site itself, you are in the right place.

Choose the right contribution path

Small page edits in the browser

For simple fixes on a single page, you can often use the Edit this page link on kubestellar.io and submit a pull request directly from GitHub.

Local workflow for multi-file or site changes

Use a local clone when you need to:

  • update multiple pages at once
  • add images or other assets
  • change navigation in a nav.yaml file under docs/content/
  • edit components, styling, or site behavior under src/
  • validate a more complex docs change before opening a PR

Local development setup

Prerequisites

Before contributing, ensure you have:

  • Node.js 20.x (recommended to match CI)
  • npm
  • A GitHub account
  • Basic familiarity with Markdown, Git, and pull requests

Clone and install

  1. Fork this repository.
  2. Clone your fork and install dependencies:
git clone https://github.com/<your-user>/docs.git
cd docs
npm install

Start a local preview

Run the docs site locally with hot reload:

npm run dev

Then open http://localhost:3000 in your browser.

Making changes

Content changes

Most documentation edits happen in docs/content/.

  • Keep the existing tone, heading structure, and terminology consistent.
  • Use repository-relative paths for assets that belong in this repo.
  • When adding a new page, place it in the correct docs/content/ directory.

Navigation changes

The docs navigation is not generated automatically from the filesystem. Each project's sidebar is defined in a nav.yaml next to its content — docs/content/nav.yaml for KubeStellar, docs/content/<project>/nav.yaml for every other project — and the shared Contributing / Community / News sections live in docs/content/<section>/nav.yaml. When you add, remove, rename, or move a page in the site navigation, also update the matching nav.yaml:

- title: Getting Started
  items:
    - Quick Start: getting-started/quick-start.md
    - Advanced:
        - Custom Setup: getting-started/advanced/custom-setup.md

Paths are relative to the directory that holds the nav.yaml. A page that is not listed does not appear in the sidebar; a malformed nav.yaml fails npm run build (and npm test) with the file and location of the problem.

Version-aware changes

  • Use main for the in-development docs shown as the dev version on the site.
  • Use the appropriate release docs branch only when you are updating already released documentation.
  • If your change should land in both dev and a release branch, open or request separate PRs.

Recommended local verification

Before opening a PR, preview the affected pages and run the checks that match what you changed.

For page/content-only changes

npm run lint:md

Also confirm that:

  • the page renders correctly in npm run dev
  • links, code fences, and images work
  • any new page appears in the expected place in the site

For navigation, theme, or site-code changes

Run the content check above and also run:

npm run type-check
npm run lint
npm run build

These checks match the CI workflows used for site code and configuration changes.

Commit and pull request conventions

Branching

Create a focused branch for your change:

git checkout -b my-docs-change

Commits

All commits must be signed off for DCO compliance:

git add .
git commit -s -m "📖 Describe your docs change"

The -s flag adds the required Signed-off-by: trailer.

Opening the PR

Open a pull request against the correct branch (main unless you are updating a release docs branch).

In the PR body:

  • put Fixes #123 on the first line when the PR closes an issue
  • briefly explain what changed and why
  • mention any follow-up work or known limitations
  • include screenshots for layout, navigation, or theme changes when helpful

Keep docs PRs focused. Avoid mixing unrelated documentation and site changes in one pull request.

Review and merge process

Maintainers review docs PRs for clarity, technical accuracy, structure, and correct placement in the site.

What reviewers typically look for:

  • whether the change belongs in this repository
  • whether navigation updates were included when needed
  • whether links, examples, and screenshots are still accurate
  • whether the target branch matches the intended docs version

PRs that change files under docs/content/ receive an automated preview comment with links to the rendered pages, plus a full preview deployment for the branch. Use that preview to verify the final rendering and to help reviewers.

Address review feedback by pushing follow-up commits to the same branch unless a maintainer asks for a different workflow.

Code Review Requirements

All pull requests to the main branch require at least one approving review before merge.

This mandatory review policy ensures:

  • Code quality and documentation accuracy
  • Adherence to project standards and conventions
  • Detection of potential issues before they reach production
  • Knowledge sharing across the team
  • Compliance with OpenSSF Scorecard best practices

What Reviewers Should Check

When reviewing a PR, pay attention to:

  1. Content Quality

    • Clarity and accuracy of documentation changes
    • Correct Markdown/MDX syntax and formatting
    • Proper navigation structure updates in the relevant docs/content/**/nav.yaml
    • Working links and valid examples

  2. Security-Sensitive Changes

    Extra scrutiny required for changes to:

    • Dockerfiles (/Dockerfile*) — verify base images, avoid running as root
    • Kubernetes manifests (/cluster-objects/) — check RBAC, secrets handling
    • CI/CD workflows (.github/workflows/) — inspect for command injection risks
    • Dependency files (package.json, package-lock.json, .npmrc) — validate new dependencies
    • Security configs (.github/dependabot.yml, .github/codeql-config.yml)

    These paths are protected by CODEOWNERS and require explicit approval from maintainers.

  3. Technical Correctness

    • Commands that actually work
    • Screenshots that match current UI
    • Version-specific information in the right docs branch

  4. Site Integration

    • Use Netlify preview to verify rendering
    • Check responsive layout on different screen sizes
    • Verify internal navigation links work correctly

Getting Your PR Approved

  1. Self-review first — use the PR template checklist
  2. Request reviews from relevant maintainers (auto-assigned via CODEOWNERS for sensitive paths)
  3. Address feedback by pushing follow-up commits
  4. Wait for CI checks — all automated checks must pass before merge
  5. Obtain approval — at least one approving review required

Branch Protection and Status Checks

This repository enforces:

  • Required approving reviews: Minimum 1 approval required
  • Required status checks: CI validations must pass, including:
    • Link checker (broken link detection)
    • Markdown linting
    • Build and deployment validation
    • Security scanning (if configured)
  • Up-to-date branches: PRs should be current with base branch before merge

See OpenSSF Scorecard for the security rationale behind these requirements.

Contribution guidelines

  • Write clearly: Use concise, task-oriented language.
  • Stay consistent: Follow the existing structure, terminology, and style.
  • Keep examples current: Update commands, paths, and screenshots when they change.
  • Be respectful: Review and follow the project's Code of Conduct.

Note on E2E Test Context Workaround

The E2E test suite includes a temporary workaround for a known kubeflex context-selection issue.

Under certain conditions, kflex create can select an unintended hosting cluster when multiple kubeconfig contexts are present and kubeflex-related context extensions are configured. This can cause E2E tests to fail even when the current context correctly accesses the intended hosting cluster.

To ensure consistent and reliable test execution, the E2E test setup removes kubeflex-specific extensions from the kubeconfig before running tests. This forces kflex create to rely solely on the current kubeconfig context during E2E runs.

This workaround is limited to the E2E test infrastructure and does not affect normal user workflows. It is intended to be temporary and will be removed once the underlying context-handling issue is resolved.

Caution With AI-Generated Code

AI tools (like GitHub Copilot or ChatGPT) are helpful but not always context-aware.
Please DO NOT blindly copy-paste AI-generated code.

Before committing:

  • Double-check if the code aligns with our project’s architecture.
  • Test thoroughly to ensure it doesn’t break existing functionality.
  • Refactor and adapt it as per the codebase standards.

CI Workflow Notes

OSSF Scorecard

The OSSF Scorecard workflow requires permissions to be defined at the job level. Workflow-level permissions are not supported and may cause CI failures due to OSSF Scorecard web application requirements.

Image Scanning

The image scanning workflow supports repositories with multiple Dockerfiles using a matrix strategy. Dockerfile paths must be correctly configured to ensure all container images are scanned successfully.

Contribution Commands Guide

This guide helps contributors manage issue assignments and request helpful labels via GitHub comments. These commands are supported through GitHub Actions or bots configured in the repository.

Issue Assignment

  • To assign yourself to an issue, comment:

    /assign

  • To remove yourself from an issue, comment:

    /unassign

Label Requests via Comments

You can also request labels to be automatically added to issues using the following commands:

  • To request the help wanted label, comment:

    /help-wanted

  • To request the good first issue label, comment:

    /good-first-issue

These commands help maintainers manage community contributions effectively and allow newcomers to find suitable issues to work on.

Understanding the Documentation Architecture

Overview

This documentation website is a separate repository from the main KubeStellar codebase. All the active documentation is now located in this repository. For safety reasons, copies of the docs source may remain in a to-be-deleted folder in the component repositories during a transition period

┌─────────────────────────────────────────────────────────────┐
│  Main KubeStellar Repository                                │
│  github.com/kubestellar/kubestellar                         │
│  🗄️kubestellar/                                             │
│   ├📁 docs/   ← NOT THE ACTIVE DOCS                         |
|     ├──README.md                                            |
|     └──content/to-be-deleted                                │
│           ├── readme.md                                     │
│           ├── architecture.md                               │
│           ├── direct/                                       │
│           ├── binding.md                                    │
│           ├── wds.md                                        │
│           └── ... (all previous documentation content)      │
│    └── ...(all the active components of the component repo) |
└─────────────────────────────────────────────────────────────┘
                         
┌────────────────────────────────────────────────────────────────|
│  Docs Website Repository (THIS REPO)                           │
│  github.com/kubestellar/docs                                   |
|                                                                │  
│  🗄️docs/ ← this repository root folder                        │
|   ├ 📁 docs/ ← raw MD content source moved from repos         |
|   |   📁content/                                              |
|   |     📁 a2a/                                               |
|   |     📁 common-subs/                                       |
|   |     📁 Community/                                         |
|   |     📁 console/                                           |
|   |     📁 contribution-guidelines/                           |
|   |     📁 icons/                                             |
|   |     📁 images/                                            |
|   |     📁 kubeflex/                                          |
|   |     📁 kubestellar/                                       |
|   |     📁 kubestellar-mcp/                                   |
|   |     📁 multi-plugin/                                      |
|   |     📁 ui-docs/                                           |
|   |   📁images/ ← image folder for some of the MD files       |
|   |  📁overrides/ ← master mkdocs layouts (legacy ref only)   |
|   ├📁 messages      ← alternate language files for NEW pages  | 
|   ├📁 src/  ← Source for NEW pages, site nav and layout       |    
|   | ├📁 app/                                                  |
|   | |  ├📁 docs/  ← layouts to apply to component docs pages  |
|   | |  ├── 📄page-map.ts     ← Builds sidebar from nav.yaml   │
│   | |  ├── 📄layout.tsx      ← Nextra theme integration       │
|   | |  └── 📄page.mdx      ← Nextra page master               │
|   | ├📁 components/                                           │
|   | ├📁 config/                                               │
|   | ├📁 hooks/                                                │
|   | ├📁 i18n/ ← configures language support                   |
|   | ├📁 lib/                                                  │
|   ├📄CONTRIBUTING.md    <----- this file                      |
|   ├📄GOVERNANCE.md                                            |
|   ├📄 next.config.ts      ← Nextra configuration              │
|   ├📄 mdx-components.js   ← MDX component mappings            |
|   └── ... (various node.js and next.js etc files)              │
└────────────────────────────────────────────────────────────────┘
                          ↓
                    (Built & Deployed)
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  Live Documentation Website                                  │
│  https://kubestellar.io                                      │
└─────────────────────────────────────────────────────────────┘

Important Concepts:

  • ✅ Content lives in the docs/content folder of this kubestellar/docs repo (docs/content/)
  • ✅ The website structure is defined in the src folder of this repo
  • ✅ This repo also contains the website framework (Next.js + Nextra)
  • ✅ Navigation is defined in nav.yaml files under docs/content/ (not auto-generated from files)

How Nextra Integration Works

This documentation site is built using Nextra, a powerful Next.js-based documentation framework that provides:

  • Static Site Generation (SSG) for fast loading
  • MDX Support for rich, interactive documentation
  • Built-in Search functionality
  • Theme Customization with dark/light modes
  • Automatic Navigation generation

Key Files and Their Roles

  1. next.config.ts - Main configuration file that:

    • Imports and configures Nextra with nextra() function
    • Enables LaTeX support for mathematical expressions
    • Configures search settings
    • Integrates with next-intl for internationalization
    • Sets up redirects for various KubeStellar links

  2. src/app/docs/layout.tsx - Docs layout component that:

    • Imports Layout from nextra-theme-docs
    • Imports the Nextra theme styles
    • Configures custom navbar, footer, and banner components
    • Sets up the sidebar with page map and repository links
    • Enables dark mode and collapsible sidebar sections

  3. src/app/docs/page-map.ts - Navigation structure builder that:

    • Loads each project's navigation from its nav.yaml (PROJECTS[project].navPath in src/config/versions/lookup.ts) plus the shared contributing, community and news sections, validating the schema at build time (src/lib/nav.ts)
    • Reads documentation files from the local /docs/content/ directory
    • Constructs hierarchical navigation from the defined structure
    • Generates routes for each documentation page
    • Creates a mapping between file paths and URL routes
    • Note: The file tree structure in /docs/content roughly parallels the navigation created in pagemap.ts but is not identical. As the new site matures many of the differences will be smoothed out
    • Using explicit nav.yaml files rather than the file structure to generate the navigation simplifies changing menus for different locales (languages)

  4. src/app/docs/[...slug]/page.tsx - Dynamic page renderer that:

    • Reads MDX content from the local /docs/content/ directory
    • Compiles and evaluates MDX with custom components
    • Processes Jekyll-style includes and template variables
    • Supports Mermaid diagrams and custom components
    • Handles image path resolution and markdown transformations

  5. mdx-components.js - Component mapping file that:

    • Exports MDX components from Nextra theme
    • Allows customization of how markdown elements render
    • Enables adding custom React components to MDX files

Working Effectively on the KubeStellar Docs

How to Modify An Existing Page in the site

The Easy Way

For edits to a single page, we have enabled a suggest edits function in the site itself:

  1. Sign into GitHub in your browser.
  2. Open a second tab and visit the page in the website you wish to modify.
    (Make sure you have selected the appropriate version of the docs with the dropdown in the masthead) The site defaults to showing "latest"; the main branch of kubestellar/docs corresponds to "dev"
  3. Find and click on the Edit This Page (Pencil) icon near the upper right page
  4. A GitHub editor session will open for you and when you commit your changes, you will be presented with the option to create a corresponding PR.
  5. You may have to make some adjustments to the PR title, etc to fulfill some requirements for a PR.
  6. When your PR is created, it will automatically generate a site preview via Netlify to make reviewing the proposed changes easier

The Complicated Way

For less simple edits, for edits across multiple files, or for editing the docs site structure/navigation, you will have to go the more traditional GitHub route of:

  1. creating a fork of the docs repository
  2. configuring your editing system properly with node.js and Nextra
  3. editing the files
  4. committing changes to the branch be sure to both sign off (-s option) for DCO and sign (-S option) your commits
  5. pushing those changes up to your fork
  6. and then doing a standard Pull Request. The PR will create a website preview via Netlify for reviewers

Some of the most common tasks are detailed below.

Common Tasks for modifying the KubeStellar Site

How to Add Documentation

The documentation content is stored directly in this repository in the /docs/content/ directory.

Content Location

All documentation content lives in this repository:

Navigation Structure

The navigation is defined in nav.yaml data files that live next to the content they describe:

File Sidebar it defines
docs/content/nav.yaml KubeStellar (paths relative to docs/content/)
docs/content/<project>/nav.yaml Each other project, e.g. console, kubeflex
docs/content/{contributing,community,news}/nav.yaml Shared sections appended to every project's sidebar

Each file is a list of sections; each section has a title and a list of items. An item is either Page Title: relative/path.md or Folder Title: followed by a nested list. src/app/docs/page-map.ts loads these files (via PROJECTS[project].navPath, see src/config/versions/lookup.ts) and validates them at build time — a missing or malformed nav.yaml fails npm run build and npm test with the file and location of the problem.

Adding New Content

To add new documentation pages:

  1. Create Your Documentation File:

    • Add your .md file to the appropriate subdirectory in /docs/content/
    • Use standard Markdown syntax
    • You can use Jekyll-style includes: {% include "path/to/file.md" %}
    • You can use template variables: {{ config.variable_name }}

  2. Update the Navigation:

    • Edit the nav.yaml for the project (docs/content/nav.yaml for KubeStellar, docs/content/<project>/nav.yaml otherwise)

    • Find the appropriate section

    • Add an entry for your new file:

      - Page Title: path/to/your-file.md

    • The file path is relative to the directory that holds the nav.yaml

  3. Preview Your Changes:

    npm run dev

    Navigate to http://localhost:3000/docs/your-route to see your page

Example: Adding a New Getting Started Guide

# In docs/content/nav.yaml
- title: User Guide
  items:
    - Quick Start: kubestellar/get-started.md
    - Your New Guide: kubestellar/new-guide.md   # Add this line
    # ... rest of the entries

Adding Nested Sections

For hierarchical navigation:

- Parent Section:
    - Subsection 1: path/to/file1.md
    - Subsection 2: path/to/file2.md
    - Nested Section:
        - Deep Page: path/to/deep/file.md

External Links

You can also add external documentation links:

- API Reference (new tab): https://pkg.go.dev/github.com/kubestellar/kubestellar/api/control/v1alpha1

Version Management

The documentation supports multiple versions through the versions.ts config:

  • Default Version: Set in getDefaultVersion()
  • Branch Mapping: Map versions to Git branches in getBranchForVersion()
  • Version Switching: Users can switch versions via query parameter: ?version=0.23.0

The site supports multiple versions of the docs for the assorted components of KubeStellar via branches of the kubestellar/docs repository.

The site when first loaded shows the latest tagged version of the KubeStellar docs. The main branch of a repository corresponds to the dev version on the site. Edits to the main branch referring to a code repository will not show unless the dev version is selected.

Versioning Strategy:

  • Each project has its own version scheme
  • Branch naming convention:
    • KubeStellar: main (latest), docs/{version} (e.g., docs/0.28.0)
    • a2a: main (latest), docs/a2a/{version} (e.g., docs/a2a/0.1.0)
    • kubeflex: main (latest), docs/kubeflex/{version} (e.g., docs/kubeflex/0.8.0)
  • The main branch always displays the version tagged latest of the content files for all projects when rendered

Testing Your Changes

  1. Local Development:

    npm run dev
    • Test navigation and page rendering
    • Verify new pages appear in the correct location
    • Check that links work properly

  2. Build Test:

    npm run build
    • Ensure no build errors
    • Verify static generation works
    • Check that all pages are accessible

  3. Content Verification:

    • Ensure the content file exists in the docs repository
    • Verify the file path in the project's nav.yaml matches exactly
    • Check that the category structure makes logical sense

Common Issues

  1. Page Not Appearing:

    • Verify file exists in docs repository
    • Check file path spelling and case sensitivity
    • Ensure file has .md or .mdx extension
    • Rebuild the page map

  2. Navigation Issues:

    • Check the nav.yaml syntax — the build error names the file, section and item
    • Ensure proper indentation of nested lists
    • Verify route generation logic

  3. Content Not Updating:

    • Clear Next.js cache: npm run clean
    • Rebuild: npm run build
    • Check GitHub API rate limits
    • Verify GITHUB_TOKEN environment variable if needed

Working with MDX

MDX allows you to use React components in Markdown:

# My Documentation

<Callout type="info">This is an info callout!</Callout>

<Tabs items={["npm", "yarn", "pnpm"]}>
  <Tabs.Tab>npm install kubestellar</Tabs.Tab>
  <Tabs.Tab>yarn add kubestellar</Tabs.Tab>
  <Tabs.Tab>pnpm add kubestellar</Tabs.Tab>
</Tabs>

Available components:

  • Callout - For notes, warnings, and tips
  • Tabs - For tabbed content
  • Mermaid - For diagrams (custom component)

Quick Reference: Common Workflows

Workflow 1: Adding a New Documentation Page

# Step 1: Add content to docs repo
cd /path/to/docs
echo "# My New Page" > docs/content/my-new-page.md
git add docs/content/my-new-page.md
git commit -m "Add new documentation page"

# Step 2: Update navigation in nav.yaml
# Edit docs/content/nav.yaml to add your page
# Add: "- My New Page: my-new-page.md" under the appropriate section

# Step 3: Test locally
npm run dev
# Visit http://localhost:3000/docs to verify

# Step 4: Commit and push
git add docs/content/nav.yaml
git commit -m "Add my-new-page to navigation"
git push

Workflow 2: Reorganizing Navigation

# Edit the project's docs/content/**/nav.yaml
# Example: Move a page to a different section
npm run dev  # Test changes
npm run build  # Verify build succeeds
git commit -am "Reorganize documentation navigation"

Workflow 3: Updating Nextra Configuration

# Edit next.config.ts for Nextra settings
# Example: Enable/disable features
npm run dev  # Test configuration
npm run build  # Verify no errors
git commit -am "Update Nextra configuration"

Workflow 4: Adding Custom MDX Components

# Step 1: Create your component
echo 'export function MyComponent() { return <div>Hello</div> }' > src/components/MyComponent.tsx

# Step 2: Export from mdx-components.js
# Add: import { MyComponent } from './src/components/MyComponent'
# Add to export: MyComponent

# Step 3: Use in documentation (main repo)
# In any .mdx file: <MyComponent />

npm run dev  # Test component

Environment Variables

For development and production, you may need these environment variables:

# .env.local (optional)
GITHUB_TOKEN=ghp_your_token_here  # For higher GitHub API rate limits
GH_TOKEN=ghp_your_token_here      # Alternative name
GITHUB_PAT=ghp_your_token_here    # Alternative name

When is GITHUB_TOKEN needed?

  • When fetching content frequently during development
  • To avoid GitHub API rate limiting (60 requests/hour without token, 5000 with token)
  • Not required for basic local development

Key Files Summary

File Purpose When to Edit
docs/content/**/nav.yaml Navigation structure Adding/removing/reorganizing pages
src/app/docs/page-map.ts Sidebar/route builder Changing how nav.yaml becomes routes
next.config.ts Nextra & Next.js config Changing Nextra settings, redirects
src/app/docs/layout.tsx Docs page layout Modifying sidebar, theme, or layout
mdx-components.js MDX component mappings Adding custom React components to MDX
src/config/versions.ts Version management Adding new documentation versions
src/middleware.ts Route handling Changing i18n behavior, route matching
package.json Dependencies & scripts Adding new packages or commands

Debugging Tips

Problem: Page not showing up

# Set the docs file path you want to inspect
DOCS_FILE_PATH="docs/content/your-file.md"
GITHUB_CONTENTS_API="https://api.github.com/repos/kubestellar/docs/contents"
curl "${GITHUB_CONTENTS_API}/${DOCS_FILE_PATH}"

# Verify nav.yaml entry
grep -r "your-file.md" docs/content --include=nav.yaml

# Clear Next.js cache
npm run clean
npm run dev

Problem: Build fails

# Check TypeScript errors
npm run type-check

# Check linting
npm run lint

# View detailed build output
npm run build 2>&1 | tee build.log

Problem: Styling issues

# Check Tailwind classes
npm run build

# Inspect global CSS
cat src/app/globals.css

# Check theme styles
cat node_modules/nextra-theme-docs/style.css

Contributing Checklist

Before submitting your PR, ensure:

  • Code follows existing style and conventions
  • All links work correctly
  • Navigation structure is logical
  • Local build succeeds (npm run build)
  • No TypeScript errors (npm run type-check)
  • No linting errors (npm run lint)
  • Changes are documented in PR description
  • Related issue is referenced (if applicable)
  • Screenshots included for UI changes (if applicable)

Need Help?

If you have questions, open an issue or ask in the community channels:

Additional Resources

Thank you for contributing to our documentation! 🚀