Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
88 lines (64 loc) · 4.82 KB

CONTRIBUTING.md

File metadata and controls

88 lines (64 loc) · 4.82 KB

Contributing to BubuStack Examples

Thank you for helping improve BubuStack examples. These examples are the first thing new users see, so clarity and correctness matter.

Adding a New Example

  1. Pick a pattern. Decide whether your example is batch/ (runs to completion) or realtime/. Place it in the appropriate directory.

  2. Follow the existing structure. Every example directory must contain:

    • README.md - follows the standard format (see below)
    • bootstrap.yaml - namespace and any shared setup resources
    • engrams.yaml - Engram definitions
    • story.yaml - the Story (workflow DAG)
    • storyrun.yaml or impulse.yaml - trigger mechanism
    • secrets.yaml.example - if API keys are needed (never commit real keys)

  3. README format. All READMEs follow the same structure:

    • Title + one-line description
    • Demo asset section or preview that matches the example type
    • ## What it demonstrates - bullet list with bold key concepts
    • ## Architecture - mermaid flowchart
    • ## Prerequisites - EngramTemplates, ImpulseTemplates, API keys
    • ## Quick start - numbered kubectl apply commands
    • ## Verify + ## Cleanup
    • ## Under the Hood - numbered CRD-level explanation, ends with CRDs involved line

  4. Provide demo assets.

    • Batch examples normally use demo.gif, recorded with VHS.
    • Shared batch tape sources live under utils/tapes/ and should be run from the examples/ repo root.
    • If a batch example keeps a local demo.tape, treat it as maintainer scratch only. The shared tape under utils/tapes/ is the published source of truth.
    • Realtime examples are video-first and should follow the shared asset convention documented in realtime/DEMO-SCRIPT.md.

  5. Update the catalog. Add your example to the tables in the root README.md.

  6. Prefer managed runner identities for namespaced access only. If an example needs extra namespaced RBAC, use the built-in controller-managed runner identity plus Engram.spec.overrides.rbac.rules or Impulse.spec.execution.rbac.rules.

    If an Engram loads prompt, stdio, or other runtime config through $bubuConfigMapRef, add an explicit named configmaps/get rule in Engram.spec.overrides.rbac.rules. Runner pods do not get blanket ConfigMap read access by default.

  7. Do not extend implicit managed runner names with external bindings. If an example needs an out-of-band ClusterRoleBinding, cluster-scoped watch, or any other external RBAC object, switch that example to an explicit ServiceAccount and bind it directly. Do not rely on hidden naming conventions like <impulse-name>-impulse-runner or <storyrun-name>-engram-runner in published examples.

Improving an Existing Example

  • Fix bugs in manifests or READMEs directly.
  • Keep changes focused - one example per PR unless the change is cross-cutting (e.g., fixing a consistent naming issue across all examples).

Pull Requests

  1. Fork the repository and branch from main.
  2. Test your manifests against a real cluster (Kind is fine).
  3. If you added or changed an example, include updated demo assets that match the example type.
  4. Submit the pull request with a description of what changed and why.

Design Principles

BubuStack follows the Unix philosophy - do one thing and do it well and write programs to work together. Examples should reinforce this:

  • One Engram, one job. An Engram fetches HTTP, summarizes text, or sends a notification - never all three. If your step does two things, split it into two Engrams.
  • Compose via Stories. The Story wires Engrams together through the DAG. Each step reads inputs and writes output; the next step consumes it. Just like a Unix pipeline.
  • Swap, don't rewrite. Want Slack instead of Discord? Change the Engram ref, not the Story. If replacing one component forces changes elsewhere, the boundary is wrong.

What Not to Do

  • Never commit real API keys or secrets. secrets.yaml.example and any tracked secrets.yaml files must contain placeholders only.
  • Don't add examples that require proprietary infrastructure. Examples should run on any Kubernetes cluster with BubuStack installed.
  • Don't over-complicate. Each example should demonstrate one or two patterns clearly. If you need more, split into multiple examples.

Commit Style

Follow Conventional Commits:

  • feat(examples): add Redis caching pipeline example
  • fix(examples): correct storyRef in livekit-chat story.yaml
  • docs(examples): update hello-world README architecture diagram

Code of Conduct

Participation is governed by the Contributor Covenant Code of Conduct. Report unacceptable behaviour to conduct@bubustack.com.