Contributing Guide

Contributing Guide

Thank you for your interest in contributing to the Surkyl Platform! This guide will help you get started.

Getting Started

1. Fork the repository
2. Clone your fork
3. Install dependencies: pnpm install
4. Create a branch for your changes

Development Workflow

Build Commands

# Build a project
nx build <project-name>

# Examples
nx build playground
nx build gate
nx build pixel

Testing

# Run tests for a project
nx test <project-name>

# Run specific test
nx test <project-name> --testNamePattern="test name"

# E2E tests
nx e2e <project-name>-e2e

Linting & Formatting

# Lint a project
nx lint <project-name>

# Format all files
nx format:write

# Check formatting
nx format:check

Running Applications

# Serve an application in development mode
nx serve <project-name>

# Examples
nx serve playground
nx serve docs
nx serve muesync-com

Code Style Guidelines

TypeScript/JavaScript

• Formatting: Single quotes, 2-space indentation
• TypeScript: Enable strict mode, use explicit types for public APIs
• Target: ES2015+
• Imports: Order: Angular core → third-party → local
• Naming:
  • PascalCase for classes and components
  • camelCase for methods and variables
  • kebab-case for files

Angular

• Use standalone components (no NgModules)
• Component prefix: app-
• Use signals and modern patterns (Angular 20+)
• Co-locate tests with source files

Rust

• Follow standard Rust conventions
• Run cargo fmt before committing
• Run cargo clippy to catch common mistakes
• Use workspace dependencies in Cargo.toml

Commit Message Format

Follow this format for commit messages:

#<issue_id> [<uri>] <conventional_tag>: (optional_tag) <summary>

Examples

# Feature
#123 [apps::playground] feat: add user profile component

# Fix
#456 [libs::pixel:::theme] fix: correct dark mode colors

# Documentation
#789 [docs] docs: update quick start guide

# Refactor
#101 [apps::gate::config] refactor: (cleanup) simplify configuration loading

Conventional Tags

• feat: New feature
• fix: Bug fix
• chore: Maintenance task
• refactor: Code refactoring
• perf: Performance improvement
• test: Adding or updating tests
• build: Build system changes
• ci: CI/CD changes
• docs: Documentation changes
• style: Code style changes (formatting)
• lint: Linting changes
• format: Code formatting

Optional Tags

• (wip): Work in progress
• (housekeeping): Code cleanup
• (cleanup): Removing unused code

URI Format

• Use :: for path separators: [apps::playground::components]
• Use ::: for functions: [libs::core::utils:::calculate]

Pull Requests

1. Create a feature branch from main
2. Make your changes following the code style guidelines
3. Write tests for new functionality
4. Update documentation if needed
5. Run tests and linting: nx affected --target=test && nx affected --target=lint
6. Commit your changes with proper commit messages
7. Push to your fork
8. Create a Pull Request

PR Guidelines

• Provide a clear description of the changes
• Reference any related issues
• Include screenshots for UI changes
• Ensure all tests pass
• Update documentation as needed

Testing

Unit Tests

• Use Vitest for TypeScript/JavaScript tests
• Use Cargo test for Rust tests
• Co-locate tests with source files
• Aim for high test coverage

E2E Tests

• Use Playwright for end-to-end tests
• Test critical user flows
• Keep E2E tests stable and maintainable

Documentation

All documentation should be written in apps/docs:

• Guides: apps/docs/src/content/docs/guides/
• API Reference: apps/docs/src/content/docs/reference/
• App Docs: apps/docs/src/content/docs/apps/
• Library Docs: apps/docs/src/content/docs/libraries/

Use Markdown with Starlight frontmatter:

---
title: Page Title
description: Brief description for SEO
---

# Page Title

Content here...

Getting Help

• Check the documentation
• Review existing issues on GitHub
• Ask questions in pull request discussions
• Join our community channels

Code of Conduct

• Be respectful and inclusive
• Provide constructive feedback
• Help others learn and grow
• Follow the project guidelines

License

By contributing, you agree that your contributions will be licensed under the same license as the project.

Thank you for contributing to the Surkyl Platform!