nebulaflow

Contribution Workflow

This guide outlines the complete workflow for contributing to NebulaFlow, from setting up your environment to merging your changes.

Overview
Step 1: Fork and Clone
Step 2: Set Up Development Environment
Step 3: Create a Feature Branch
Step 4: Make Your Changes
Step 5: Run Checks
Step 6: Update Documentation
Step 7: Commit Messages
Step 8: Push and Create Pull Request
Step 9: Review Process
Step 10: CI/CD Pipeline
Step 11: Merging and Release
Troubleshooting

Overview

Contributing to NebulaFlow follows a standard open-source workflow:

Fork the repository
Create a feature branch
Make changes and run checks
Submit a pull request
Wait for review and address feedback
Merge into main (or dev for pre-release)

Step 1: Fork and Clone

Fork the repository on GitHub.

Clone your fork locally:

git clone https://github.com/your-username/nebulaflow.git
cd nebulaflow

Add the upstream remote to keep your fork in sync:

git remote add upstream https://github.com/PriNova/nebulaflow.git

Step 2: Set Up Development Environment

Follow the Development Setup guide to install dependencies, set environment variables, and build the project.

Quick start:

Install Node.js ≥ 18 and npm ≥ 9
Run npm install
Set AMP_API_KEY and optionally OPENROUTER_API_KEY
Build with npm run build

Step 3: Create a Feature Branch

Create a descriptive branch for your changes:

git checkout -b feature/your-feature-name

Branch naming conventions:

feature/ – new features
fix/ – bug fixes
docs/ – documentation updates
refactor/ – code refactoring
chore/ – maintenance tasks

Step 4: Make Your Changes

Write clear, concise code following the Code Style guidelines.
Keep functions small and pure; side effects at boundaries.
Use explicit type imports and the node: protocol for Node.js built-ins.
Add tests if applicable (currently manual testing only).
Ensure your changes pass type checking and linting.

Step 5: Run Checks

Before committing, run the full check suite:

npm run check

This runs:

TypeScript type checking
Biome linting and formatting

If there are errors, fix them before proceeding.

Step 6: Update Documentation

If you add or modify features, update the relevant documentation:

User guide (docs/user-guide/)
API reference (docs/api-reference/)
Examples (docs/workflows/)
Update mkdocs.yml if adding new files.

Step 7: Commit Messages

Follow Conventional Commits. Format:

<type>(<scope>): <subject>

<body>

<footer>

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style (formatting, linting)
refactor: Code refactoring
test: Adding or updating tests
chore: Build process, tooling, dependencies

Example:

feat(llm-node): add support for custom model parameters

- Extend LLM node data interface with `modelParams` field
- Update UI to allow editing model parameters
- Pass parameters to Amp SDK execution

Closes #123

Step 8: Push and Create Pull Request

Push your branch to your fork:

git push origin feature/your-feature-name

Create a pull request on GitHub:
- Base branch: main (or dev for pre-release features)
- Head branch: your feature branch
- Title: Clear description of the change
- Description:
  - Reference any related issues
  - Summarize changes
  - Include a manual test checklist (if applicable)

Step 9: Review Process

Wait for a maintainer to review your PR.
Address any feedback promptly.
CI checks will run automatically (see below).
Once approved, a maintainer will merge your PR.

Step 10: CI/CD Pipeline

NebulaFlow uses GitHub Actions for continuous integration. The CI pipeline runs on pushes to main and dev branches and includes:

Type checking and linting (npm run check)
Building and packaging the extension (npm run package:vsix)
Deploying documentation to GitHub Pages (when docs change)

You can run the same steps locally to verify your changes before pushing.

Step 11: Merging and Release

Merging: PRs are merged via squash merge (or rebase) into main or dev.
Release: Releases are created by pushing a Git tag (e.g., v1.2.3). The CI workflow automatically builds and packages the extension, then creates a GitHub release with the .vsix file.
Documentation: Documentation changes are automatically deployed to GitHub Pages when merged into main.

For detailed release process, see Deployment.

Troubleshooting

Issue	Solution
Amp SDK not available	Ensure `vendor/amp-sdk/amp-sdk.tgz` exists.
AMP_API_KEY is not set	Set the environment variable before launching VS Code.
Webview assets don’t load	Run `npm run build` or start the webview watcher (`npm run watch:webview`).
Type errors	Run `npm run typecheck` and fix diagnostics.
Lint/format issues	Run `npm run check` or `npm run biome`.
Extension fails to load	Check VS Code version ≥ 1.90.0; reload the window.
CI fails	Run `npm run check` locally and fix any errors.

Last Updated: 2026-01-21

This site is open source. Improve this page.