Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
312 lines (216 loc) · 7.28 KB

CONTRIBUTING.md

File metadata and controls

312 lines (216 loc) · 7.28 KB
Raw

Contributing to Devsy

Thank you for your interest in contributing to Devsy! This guide will help you get started with development.

Contributor License Agreement

Before your first contribution can be merged, you must sign the Contributor License Agreement. When you open a pull request, a bot will check your signing status and, if needed, comment with instructions. You sign by posting a comment on the pull request with the exact text the bot provides.

Development Setup

Prerequisites

CLI Development:

  • Go 1.26+
  • Task (optional, but recommended for running tasks)

Desktop Application Development:

Initial Setup

  1. Clone the repository:

    git clone https://github.com/devsy-org/devsy.git
cd devsy

  2. If you want to change Devsy agent code:

    • Exchange the URL in DefaultAgentDownloadURL with a custom public repository release
    • Build devsy via: task cli:build:dev
    • Upload dist/devsy-dev_linux_amd64_v1/devsy-linux-amd64 and ARM64 variant to your public repository release assets

Building from Source

CLI

Using Task (recommended):

# Build CLI for development
task cli:build:dev

# Build CLI for production
task cli:build

# Build with Pro features
task cli:build:dev:pro

Using Go directly:

CGO_ENABLED=0 go build -ldflags "-s -w" -o devsy

The binary will be output as devsy in the current directory.

Desktop Application

Using Task (recommended):

# Setup Electron environment (first time only)
task desktop:setup

# Run in development mode
task desktop:dev

# Build the application
task desktop:build

Manual build:

cd desktop
npm ci
npm run build

The packaged application will be in desktop/release/

Development Workflow

CLI Development

# Tidy dependencies
task cli:tidy

# Run linters
task cli:lint

# Run unit tests
task cli:test

# Build for development
task cli:build:dev

Desktop Development

In renderer code, use $lib/... for imports across renderer library modules and $shared/... for shared modules. Apply this to type imports, re-exports, and dynamic imports as well. Keep ./... for sibling files and relative paths for renderer entry points without an existing alias. Avoid parent-directory imports (../...) when one of these aliases addresses the module.

Main-process, preload, and shared code use relative imports: the renderer aliases are not configured in the main/preload bundlers. Preserve the existing .js extension on TypeScript module specifiers and .svelte on component imports.

# Install dependencies
cd desktop
npm ci

# Check code quality (type check + svelte-check)
task desktop:check

# Run unit tests
task desktop:test

# Run e2e tests
task desktop:test:e2e

E2E Testing

# Build for e2e tests
task cli:test:e2e:build

# Run all e2e tests
task cli:test:e2e

# Run specific test suite
task cli:test:e2e:suite -- "suite-name"

# Run focused tests
task cli:test:e2e:focus -- "test-pattern"

# Setup kind cluster for testing
task cli:test:e2e:kind:setup

# Teardown kind cluster
task cli:test:e2e:kind:teardown

gRPC Development

If you need to modify the gRPC tunnel code:

task cli:build:grpc

This requires:

  • protobuf-compiler (install via sudo apt install protobuf-compiler)
  • Go protobuf plugins (installed automatically by the task)

Testing Your Changes

Quick Start

  1. Build Devsy:

    task cli:build:dev

  2. Add a provider:

    ./dist/devsy-dev_linux_amd64_v1/devsy-linux-amd64 provider add docker

  3. Configure the provider:

    ./dist/devsy-dev_linux_amd64_v1/devsy-linux-amd64 provider use docker

  4. Start a workspace:

    ./dist/devsy-dev_linux_amd64_v1/devsy-linux-amd64 workspace up github.com/microsoft/vscode-remote-try-node

Using Act for Local CI Testing

# Build UI using act
task desktop:act:build:ui

# Build desktop app using act
task desktop:act:build:app

# Build flatpak using act
task desktop:act:build:flatpak

# Run e2e tests with focus
task cli:test:e2e:act:focus -- "test-pattern"

Developing Providers

Read the docs for an introduction to developing your own providers.

Publishing Your Provider

Once your provider is ready:

  1. Update community.yaml with your provider information
  2. Update sites/docs-devsy-sh/content/docs/managing-providers/manage-providers.mdx with documentation

This will feature your provider in both the documentation and the UI.

Desktop Deep Links

Devsy Desktop can handle deep links to perform various actions.

URL Scheme:

devsy://command?param1=value1&param2=value2

Open Workspace

Open a workspace based on a source (similar to devsy workspace up, but shareable):

devsy://open?source=<url-encoded-source>&workspace=<name>&provider=<provider>&ide=<ide>

Parameters:

  • source (required): URL-encoded workspace source
  • workspace (optional): Workspace name
  • provider (optional): Provider to use
  • ide (optional): IDE to open

Example:

devsy://open?source=https%3A%2F%2Fgithub.com%2Fuser%2Frepo&workspace=my-workspace&provider=docker&ide=vscode

Import Workspace

Import a remote Devsy.Pro workspace into your local client:

devsy://import?workspace_id=<id>&workspace_uid=<uid>&devsy_pro_host=<host>&options=<options>

Parameters:

  • workspace_id (required): Workspace ID
  • workspace_uid (required): Workspace UID
  • devsy_pro_host (required): Devsy Pro host URL
  • options (optional): Additional options

Useful Task Commands

# View all available tasks
task --list

# CLI tasks
task cli:build              # Build CLI for production
task cli:build:dev          # Build CLI for development
task cli:lint               # Run linters
task cli:test               # Run unit tests
task cli:tidy               # Tidy go.mod and go.sum

# Desktop tasks
task desktop:build          # Build desktop application
task desktop:check          # Check code quality
task desktop:dev            # Run in development mode
task desktop:setup          # Setup Electron environment
task desktop:test           # Run unit tests
task desktop:test:e2e       # Run e2e tests

# E2E testing
task cli:test:e2e           # Run all e2e tests
task cli:test:e2e:suite     # Run specific test suite
task cli:test:e2e:focus     # Run focused tests

Repository Structure

  • /cmd - CLI command implementations
  • /pkg - Core packages and libraries
  • /desktop - Desktop application (Electron + Svelte)
  • /e2e - End-to-end tests
  • /providers - Built-in provider definitions
  • /sites - Documentation and download websites
  • /hack - Build and development scripts

Getting Help

Code of Conduct

Please be respectful and constructive in all interactions with the community.