Contributing to Hikari

Thank you for your interest in contributing to Hikari! This document provides guidelines and instructions for contributing to the project.

Table of Contents

Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment for all contributors. Please be respectful, constructive, and professional in all interactions.

Standards

Getting Started

Prerequisites

Before contributing, ensure you have:

Fork and Clone

  1. 1
    Fork the repository on GitHub
  2. 2
    Clone your fork locally:
bash
1
2
git clone https://github.com/YOUR_USERNAME/hikari.git
cd hikari
  1. 1
    Add upstream remote:
bash
1
git remote add upstream https://github.com/celestia-island/hikari.git

Development Setup

Install Dependencies

bash
1
2
3
4
5
6
7
8
# Install Rust toolchain
rustup update

# Install Just
cargo install just

# Install Python dependencies (for tooling)
pip install -r requirements-dev.txt  # if available

Build the Project

bash
1
2
3
4
5
# Build all packages
just build

# Or use cargo directly
cargo build --workspace

Run Examples

bash
1
2
3
4
5
6
7
# Run the website
cd examples/website
cargo run

# Run SSR demo
cd examples/ssr-demo
cargo run

Development Mode

bash
1
2
# Start development server (if configured)
just dev

Code Style Guidelines

Rust Code Style

We follow standard Rust conventions:

  1. 1
    Formatting: Use rustfmt
bash
1
2
3
just fmt
# or
cargo fmt --all
  1. 1
    Linting: Use clippy
bash
1
2
3
just lint
# or
cargo clippy --all -- -D warnings
  1. 1
    Naming Conventions:
rust
1
2
3
4
5
6
7
pub struct ButtonProps { }  // PascalCase

pub fn render_button() { }  // snake_case

pub const MAX_SIZE: usize = 100;  // SCREAMING_SNAKE_CASE

pub const 石青: Color = Color { };  // Chinese (for palette)

Tairitsu Component Style

Components should follow these patterns:

rust
1
2
3
4
5
6
7
8
9
10
11
12
13
14
#[component]  // Always use component attribute
pub fn Button(props: ButtonProps) -> Element {  // PascalCase for components
    rsx! {  // Use rsx! macro
        button {
            class: "{props.class}",  // Use string formatting for classes
            onclick: move |e| {  // Use move closures for event handlers
                if let Some(handler) = props.onclick.as_ref() {
                    handler.call(e);
                }
            },
            {props.children}  // Always include children
        }
    }
}

SCSS Style

Follow SCSS best practices:

scss
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// Use variables for all values
.my-component {
    background-color: var(--hi-color-surface);
    padding: var(--hi-spacing-md);
    border-radius: var(--hi-radius-lg);
}

// Use nesting for related styles
.my-component {
    &.modifier {
        // Modifier styles
    }

    &:hover {
        // Hover styles
    }

    .child-element {
        // Child styles
    }
}

Documentation Style

All public items must be documented:

rust
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
/// Button component with multiple variants.
///
/// # Examples
///
/// ```rust
/// use hikari_components::Button;
///
/// rsx! {
///     Button { variant: ButtonVariant::Primary, "Click Me" }
/// }
/// ```
///
/// # Props
///
/// - `variant`: Button style variant
/// - `size`: Button size (Small, Medium, Large)
/// - `disabled`: Whether the button is disabled
/// - `loading`: Show loading spinner
#[component]
pub fn Button(props: ButtonProps) -> Element {
    // ...
}

Git Workflow

Branch Naming

Use descriptive branch names:

Commit Messages

Follow the emoji + one-liner format (as defined in PLAN.md):

text
1
emoji one-sentence english description

Examples:

Common emojis:

Commit Workflow

  1. 1
    Create a feature branch:
bash
1
git checkout -b feature/your-feature-name
  1. 1
    Make changes and commit:
bash
1
2
git add .
git commit -m "feat: Add your feature description"
  1. 1
    Push to your fork:
bash
1
git push origin feature/your-feature-name
  1. 1
    Create Pull Request: Go to GitHub and create a PR

Keeping Your Fork Updated

bash
1
2
3
git fetch upstream
git rebase upstream/master
git push origin feature/your-feature-name --force-with-lease

Testing Guidelines

Write Tests

All new features must include tests:

rust
1
2
3
4
5
6
7
8
9
10
11
12
13
14
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_button_renders() {
        // Test implementation
    }

    #[test]
    fn test_button_disabled_state() {
        // Test implementation
    }
}

Run Tests

bash
1
2
3
4
5
6
7
8
9
10
# Run all tests
just test
# or
cargo test --workspace

# Run tests for specific package
cargo test -p hikari-components

# Run tests with output
cargo test --workspace -- --nocapture

Test Coverage

Documentation Standards

Code Documentation

README Documentation

Each package should have a README with:

  1. 1
    Overview: What the package does
  2. 2
    Installation: How to add as dependency
  3. 3
    Quick Start: Basic usage example
  4. 4
    API Reference: Detailed API docs
  5. 5
    Examples: Advanced usage patterns

Example Applications

Examples should be:

Pull Request Process

Before Submitting

  1. 1
    Code Quality:
  1. 1
    Commits:
  1. 1
    Documentation:

Creating a Pull Request

  1. 1
    Go to the Hikari repository on GitHub
  2. 2
    Click "New Pull Request"
  3. 3
    Select your feature branch
  4. 4
    Fill in the PR template:
markdown
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Tests added/updated
- [ ] All tests pass

## Checklist
- [ ] Code follows style guidelines
- [ ] Documentation updated
- [ ] No merge conflicts

Review Process

  1. 1
    Automated Checks: CI will run tests and linters
  2. 2
    Code Review: Maintainers will review your code
  3. 3
    Feedback: Address review comments
  4. 4
    Approval: Once approved, your PR will be merged

After Merge

Project Structure Guidelines

Adding a New Component

When adding a new component:

  1. 1
    Location: Place in appropriate module (basic, feedback, navigation, data)
  2. 2
    File Structure:
text
1
2
3
4
   packages/hikari-components/src/
   ├── category/
   │   ├── mod.rs       # Export the component
   │   └── component.rs # Component implementation
  1. 1
    Exports: Add to mod.rs and lib.rs
  1. 1
    Documentation: Document in package README
  1. 1
    Example: Add to website or create dedicated example

Adding a New Package

When adding a new package:

  1. 1
    Update Workspace: Add to Cargo.toml
  2. 2
    Create Structure: Follow existing package structure
  3. 3
    Documentation: Create comprehensive README
  4. 4
    Examples: Provide usage examples
  5. 5
    Tests: Include thorough tests

Community Guidelines

Communication Channels

Getting Help

  1. 1
    Check existing documentation
  2. 2
    Search existing issues
  3. 3
    Ask in GitHub Discussions
  4. 4
    Join community chat (if available)

Reporting Issues

When reporting bugs:

  1. 1
    Use Issue Template: Fill out all required fields
  2. 2
    Minimal Reproduction: Provide code that reproduces the issue
  3. 3
    Environment: Include Rust version, OS, etc.
  4. 4
    Expected vs Actual: Describe what you expected vs what happened

Feature Requests

When requesting features:

  1. 1
    Use Case: Describe the problem you're solving
  2. 2
    Proposed Solution: How you envision it working
  3. 3
    Alternatives: Other approaches you considered
  4. 4
    Willingness to Contribute: Indicate if you can implement it

Recognition

Contributors will be:

License

By contributing, you agree that your contributions will be licensed under the Synthetic Source License (SySL), Version 1.0.

Questions?

If you have questions:

  1. 1
    Check this document
  2. 2
    Review existing issues and PRs
  3. 3
    Start a GitHub Discussion
  4. 4
    Contact maintainers

Thank you for contributing to Hikari! Your contributions help make Hikari better for everyone.