Contributing to Container Kit

​

Getting Started

​

Prerequisites

• macOS 26.0+ with Apple Silicon (M1/M2/M3/M4) - Intel Macs not supported
• Xcode Command Line Tools: xcode-select --install
• Node.js 20+ and pnpm: npm install -g pnpm
• Git for version control
• Apple Container CLI (optional, for container features)

​

Quick Start

​

Development Workflow

​

Branch Strategy

• main - Stable release branch
• develop - Integration branch for new features
• feature/feature-name - Feature development
• fix/issue-description - Bug fixes
• docs/documentation-update - Documentation improvements

​

Standard Workflow

git checkout -b feature/your-feature-name

npm run check
npm run format
npm run lint
npm run tauri:build

git add .
git commit -m "feat: add your feature description"

git push origin feature/your-feature-name

​

Code Standards

​

TypeScript

• Strict typing required - No any types without justification
• Types over interfaces - Use Types for object shapes
• Explicit return types - For all public functions

// ✅ Good
type UserConfig = {
    theme: 'light' | 'dark';
    autoUpdate: boolean;
};

export function updateConfig(config: UserConfig): Promise<void> {
    // implementation
}

// ❌ Avoid
function updateConfig(config: any) {
    // implementation
}

​

Svelte Components

• Component-scoped styles - Use <style> blocks in components
• TypeScript in script blocks - Always use <script lang="ts">
• Props with types - Explicitly type all props

<!-- ✅ Good -->
<script lang="ts">
    interface Props {
        title: string;
        isActive?: boolean;
    }

    let { title, isActive = false }: Props = $props();
</script>

<h1 class={[isActive ? 'active' : 'inactive', 'another-class']}>{title}</h1>

<style>
    .active {
        color: var(--primary);
    }
    .inactive {
        color: var(--muted);
    }
</style>

​

Rust (Tauri Backend)

• Follow Rust conventions - Use cargo fmt and cargo clippy
• Error handling - Proper error types with context
• Documentation - Doc comments for public APIs
• Testing - Unit tests for complex logic

use tauri::Result;
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
pub struct ContainerInfo {
    pub id: String,
    pub name: String,
    pub status: ContainerStatus,
}

/// Retrieves container information by ID
#[tauri::command]
pub async fn get_container_info(id: String) -> Result<ContainerInfo> {
    container_service::get_info(&id)
        .await
        .map_err(|e| format!("Failed to get container info: {}", e))
}

​

Database Schema (Drizzle)

• Descriptive table names - Clear, singular nouns
• Consistent field naming - camelCase for TypeScript compatibility
• Proper relationships - Use foreign keys appropriately
• Migration versioning - Sequential, descriptive migration names

export const container = sqliteTable('container', {
    id: text('id').primaryKey(),
    name: text('name').notNull(),
    status: text('status').$type<ContainerStatus>().notNull(),
    createdAt: integer('created_at', { mode: 'timestamp' }).notNull(),
    updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull()
});

​

Testing Guidelines

​

Frontend Testing

• Component tests - Test component behavior and rendering (Storybook with tauri need to integrate it)
• Integration tests - Test workflows
• Type tests - Ensure TypeScript types are correct

​

Backend Testing

• Unit tests - Test individual functions and modules
• Integration tests - Test Tauri commands end-to-end
• Database tests - Test schema and queries

​

Documentation Standards

​

Code Documentation

• TypeScript - JSDoc comments for public APIs
• Svelte - Component prop documentation
• Rust - Doc comments (///) for public functions

​

README and Guides

• Clear headings - Use consistent markdown structure
• Code examples - Include working examples
• Step-by-step guides - Break down complex processes
• Links and references - Cross-reference related documentation

​

Commit Message Guidelines

​

Format

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

​

Types

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, semicolons, etc.)
• refactor: Code refactoring without feature changes
• test: Adding or updating tests
• chore: Build process or auxiliary tool changes

​

Examples

feat: add container status monitoring
feat(ui): add container status monitoring
fix: resolve memory leak in container list
docs: update API documentation for container commands
style: format TypeScript files with prettier
refactor: extract container service logic
test: add unit tests for container operations
chore: update build scripts for release automation

​

Areas for Contribution

​

Bug Fixes

• UI inconsistencies - Visual bugs and layout issues
• Performance issues - Memory leaks, slow operations
• Compatibility problems - Issues with different macOS versions (26.0+)
• Edge cases - Handling of unusual input or states

​

New Features

• Container management - New container operations and workflows
• UI improvements - Better user experience and accessibility
• Apple integration - Enhanced macOS container and sandbox features
• Developer tools - CLI improvements and automation scripts
• Performance optimizations - Faster operations and better resource usage

​

Documentation

• API documentation - Document Tauri commands and TypeScript APIs
• User guides - Step-by-step tutorials and how-to guides
• Developer guides - Architecture documentation and contribution guides
• Code examples - Real-world usage examples and best practices

​

UI/UX Improvements

• Accessibility - Better keyboard navigation, screen reader support
• Design consistency - Follow Apple Human Interface Guidelines
• Dark mode - Improvements to dark theme implementation
• Responsive design - Better support for different screen sizes

​

Pull Request Guidelines

​

Before Submitting

• Code follows project style guidelines
• Self-review of code completed
• Tests added/updated for changes
• Documentation updated if needed
• No merge conflicts with main branch

​

PR Description Template

## Summary

Brief description of changes made.

## Type of Change

- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update

## Testing

Describe the tests that you ran to verify your changes:

- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing completed

## Screenshots (if applicable)

Add screenshots to help explain your changes.

## Checklist

- [ ] My code follows the style guidelines of this project
- [ ] I have performed a self-review of my own code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes

​

Bug Reports

​

Before Reporting

1. Search existing issues - Check if the bug is already reported
2. Try latest version - Ensure you’re using the most recent build
3. Minimal reproduction - Create the smallest possible reproduction case

​

Bug Report Template

## Bug Description

A clear description of what the bug is.

## Steps to Reproduce

1. Go to '...'
2. Click on '...'
3. See error

## Expected Behavior

What you expected to happen.

## Actual Behavior

What actually happened.

## Environment

- macOS Version:
- App Version:
- Architecture: (Apple Silicon/Intel)

## Additional Context

Any other context, screenshots, or logs.

​

Feature Requests

​

Feature Request Template

## Feature Description

A clear description of the feature you'd like to see.

## Problem Statement

What problem does this feature solve?

## Proposed Solution

How would you like this feature to work?

## Alternative Solutions

Any alternative solutions you've considered.

## Additional Context

Any other context, mockups, or examples.

​

Security

​

Reporting Security Issues

• Description of the vulnerability
• Steps to reproduce
• Potential impact
• Any suggested fixes

​

Security Best Practices

• Input validation - Sanitize all user inputs
• Secure storage - Encrypt sensitive data
• Authentication - Proper session management
• Dependencies - Keep dependencies updated

​

Recognition

• README.md - Contributors section
• Release notes - Acknowledgment in release announcements
• GitHub - Contributor badge and statistics

​

Getting Help

• GitHub Discussions - Project Discussions
• Email - [email protected]

​

Additional Resources

• Tauri Documentation
• Svelte 5 Documentation
• Rust Book
• TypeScript Handbook
• Tailwind CSS Documentation
• Shadcn-Svelte Documentation