Contributing Guidelines

Thank you for your interest in contributing to Gõ Nhanh! This guide will help you get started.

Getting Started

Before diving in, familiarize yourself with the project:

Fork and clone

Fork the repository on GitHub
Clone your fork:

git clone https://github.com/YOUR_USERNAME/gonhanh.org
cd gonhanh.org

Set up development environment

Run the setup script:

make setup

See the Getting Started guide for detailed setup instructions.

Create a feature branch

git checkout -b feature/my-feature

Use descriptive branch names:

feat/add-tone-shortcut
fix/chrome-autocomplete
docs/update-architecture

Make your changes

Edit the code, add tests, and ensure everything works.

Development Workflow

For Rust Core Changes

When modifying the input method engine:

cd core

# Make your changes to src/
vim src/engine/mod.rs

# Run tests frequently
cargo test

# Check formatting
cargo fmt --check

# Run linter
cargo clippy -- -D warnings

# Build for verification
cargo build --release

All Rust changes must pass cargo clippy with zero warnings.

For macOS UI Changes

When working on the Swift interface:

Open in Xcode

open platforms/macos/GoNhanh.xcodeproj

Make changes

Edit Swift files in Xcode or your preferred editor.

Test changes

Build and run in Xcode to verify your changes work.

Format code

make format

This runs swiftformat on all Swift files.

Testing Requirements

All contributions must include appropriate tests.

Writing Tests

Gõ Nhanh has 160+ integration tests organized by category:

Category	File	Purpose
Basic	`basic_test.rs`	Single keystroke tests
Words	`word_test.rs`	Full Vietnamese words
Sentences	`sentence_test.rs`	Multi-word sequences
Behavior	`behavior_test.rs`	User interactions
Issues	`common_issues_test.rs`	Real bug reproductions
Edge Cases	`edge_cases_test.rs`	Boundary conditions

Test Example

#[cfg(test)]
mod tests {
    use super::*;
    use rstest::rstest;

    #[test]
    fn test_telex_basic_tone() {
        let result = type_text("as", Method::Telex);
        assert_eq!(result, "á");
    }

    #[rstest]
    #[case("a1", "á")]  // VNI sắc
    #[case("a2", "à")]  // VNI huyền
    #[case("a3", "ả")]  // VNI hỏi
    fn test_vni_tones(#[case] input: &str, #[case] expected: &str) {
        let result = type_text(input, Method::Vni);
        assert_eq!(result, expected);
    }
}

Running Tests

# Run all tests
make test

# Run with verbose output
cd core && cargo test -- --nocapture

# Run specific test file
cargo test --test word_test

# Run specific test
cargo test test_telex_basic_tone

# Run heavy tests (22k words)
make test-22k

All tests must pass before submitting a pull request.

Code Quality

Before committing, ensure your code meets our standards:

Format your code

make format

This runs:

cargo fmt for Rust
swiftformat for Swift

Run linters

make lint

This checks:

cargo clippy -- -D warnings (zero warnings policy)
swiftformat --lint

Run tests

make test

Verify all tests pass.

Commit Message Format

We follow Conventional Commits specification:

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

<body>

<footer>

Types

Type	Purpose	Example
`feat`	New feature	`feat(engine): add shortcut expansion`
`fix`	Bug fix	`fix(transform): correct ư placement`
`docs`	Documentation	`docs(api): clarify FFI ownership`
`test`	Tests	`test(validation): add edge cases`
`refactor`	Code reorganization	`refactor(buffer): optimize lookup`
`style`	Formatting	`style(rust): apply cargo fmt`
`chore`	Build/CI	`chore(ci): update workflow`

Examples

Good commit messages:

feat(engine): add user shortcut table support

Implement ShortcutTable struct to store user-defined abbreviations.
Allows users to define transforms like "vn" → "Việt Nam".

Closes #45

fix(transform): handle ư vowel in compound patterns

The ư vowel was not correctly recognized in sequences like "ưu" and
"ươ" due to missing pattern validation. Add explicit check for horn
modifier on u vowel.

Fixes #78

Subject Line Guidelines

Use imperative mood: “add” not “adds” or “added”
Lowercase first letter
No period at the end
Maximum 50 characters
Complete this sentence: “If applied, this commit will…”

Pull Request Process

Before Submitting

PR Template

Use this template for your pull request:

## Description

Brief description of what this PR does and why.

## Type of Change

- [ ] Bug fix (non-breaking change fixing an issue)
- [ ] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to break)
- [ ] Documentation update

## Testing

Describe how you tested this:
- What test cases did you add?
- What manual testing did you perform?
- What edge cases did you consider?

## Related Issues

Closes #123
Related to #456

## Checklist

- [ ] Tests pass locally
- [ ] Code is formatted and linted
- [ ] Documentation updated (if applicable)
- [ ] No breaking changes (or clearly documented)

Review Process

Submit PR

Push your branch and create a pull request on GitHub.

CI checks

Wait for automated checks to complete:

Code formatting
Linting
Test suite
Build verification

Code review

A maintainer will review your code and may request changes.

Approval and merge

Once approved, a maintainer will merge your PR.

Code Review Guidelines

When reviewing or receiving reviews:

For Reviewers

Be respectful and constructive
Focus on the code, not the person
Suggest improvements rather than demanding changes
Explain the reasoning behind your comments
Approve when ready, even if you have minor suggestions

For Authors

Don’t take feedback personally
Ask for clarification if needed
Be open to suggestions
Respond to all comments
Make requested changes or explain why you disagree

Types of Contributions

There are many ways to contribute:

Code Contributions

Bug fixes: Fix reported issues
New features: Add requested functionality
Performance: Optimize slow code paths
Refactoring: Improve code quality

Non-Code Contributions

Documentation: Improve guides and API docs
Testing: Add test cases for edge cases
Bug reports: Report issues with reproduction steps
Feature requests: Suggest improvements
Community support: Help other users

Coding Standards

Follow our detailed Code Standards guide:

Rust Standards

Format with cargo fmt (enforced)
Zero clippy warnings
Add rustdoc comments for public APIs
Use snake_case for functions/variables
Use CamelCase for types

Swift Standards

Follow Google Swift Style Guide
Use camelCase for variables/functions
Use PascalCase for types/enums
Add comments for complex logic

FFI Conventions

Use #[repr(C)] for all shared structs
Fixed-size types only (u8, u16, u32)
Match byte layout exactly between Rust and Swift
Document memory ownership clearly

Need Help?

If you have questions:

Check the documentation
Search existing GitHub issues
Open a new issue or discussion

Don’t hesitate to ask questions! We’re here to help.

Recognition

All contributors are recognized in:

CONTRIBUTORS.md
README.md contributor section
GitHub contributors page

Thank you for making Gõ Nhanh better!

Documentation Index

​Getting Started

​Development Workflow

​For Rust Core Changes

​For macOS UI Changes

​Testing Requirements

​Writing Tests

​Test Example

​Running Tests

​Code Quality

​Commit Message Format

​Types

​Examples

​Subject Line Guidelines

​Pull Request Process

​Before Submitting

​PR Template

​Review Process

​Code Review Guidelines

​For Reviewers

​For Authors

​Types of Contributions

​Code Contributions

​Non-Code Contributions

​Coding Standards

​Rust Standards

​Swift Standards

​FFI Conventions

​Need Help?

​Recognition

Getting Started

Development Workflow

For Rust Core Changes

For macOS UI Changes

Testing Requirements

Writing Tests

Test Example

Running Tests

Code Quality

Commit Message Format

Types

Examples

Subject Line Guidelines

Pull Request Process

Before Submitting

PR Template

Review Process

Code Review Guidelines

For Reviewers

For Authors

Types of Contributions

Code Contributions

Non-Code Contributions

Coding Standards

Rust Standards

Swift Standards

FFI Conventions

Need Help?

Recognition