Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
291 lines (216 loc) · 8.07 KB

CONTRIBUTING.md

File metadata and controls

291 lines (216 loc) · 8.07 KB

Contributing to Git Alias Generator

Thank you for your interest in contributing to Git Alias Generator! This document provides guidelines and information for contributors.

Table of Contents

Code of Conduct

This project and everyone participating in it is governed by a commitment to creating a welcoming and inclusive environment. Be respectful and constructive in all interactions.

Getting Started

Prerequisites

Before contributing, ensure you have:

  • Node.js (v16 or higher)
  • Rust (latest stable version)
  • Git (obviously!)
  • A code editor (VS Code recommended)

Development Setup

  1. Fork and clone the repository

    git clone https://github.com/your-username/git-alias-generator.git
cd git-alias-generator

  2. Install JavaScript dependencies

    npm install

  3. Install Tauri CLI (if not already installed)

    npm install -g @tauri-apps/cli

  4. Run the development server

    npm run tauri dev

The application should open automatically. The frontend will hot-reload on changes, but Rust changes require a restart.

Project Structure

git-alias-generator/
├── src/                    # React frontend
│   ├── App.tsx            # Main React component
│   ├── main.tsx           # React entry point
│   └── styles.css         # Application styles
├── src-tauri/             # Rust backend
│   ├── src/
│   │   └── main.rs        # Main Rust application and Tauri commands
│   ├── Cargo.toml         # Rust dependencies
│   └── tauri.conf.json    # Tauri configuration
├── index.html             # HTML entry point
├── package.json           # Node.js dependencies and scripts
├── vite.config.ts         # Vite build configuration
└── tsconfig.json          # TypeScript configuration

Key Components

Frontend (React/TypeScript)

  • App.tsx: Main UI component with all application logic
  • State management for commands, validation, settings
  • Integration with Tauri backend via invoke() calls

Backend (Rust/Tauri)

  • main.rs: Contains all Tauri commands for Git operations
  • Git configuration management
  • OpenAI API integration for commit message generation
  • Cross-platform command execution

How to Contribute

Types of Contributions

  • Bug fixes: Help us squash bugs and improve reliability
  • Feature enhancements: Add new functionality or improve existing features
  • Documentation: Improve README, code comments, or create tutorials
  • Testing: Add test coverage or improve testing infrastructure
  • Platform support: Help test and improve cross-platform compatibility
  • UI/UX improvements: Enhance the user interface and experience

Areas That Need Help

  • Testing framework: Unit and integration tests
  • Error handling: Better error messages and edge case handling
  • Performance: Optimize Git command execution
  • Accessibility: Improve keyboard navigation and screen reader support
  • Internationalization: Multi-language support
  • Custom commands: Support for user-defined Git commands
  • Templates: Pre-built alias templates for common workflows

Pull Request Process

  1. Create a new branch for your feature or fix:

    git checkout -b feature/your-feature-name
# or
git checkout -b fix/issue-description

  2. Make your changes following our coding standards

  3. Test your changes thoroughly:

    • Test on your target platform
    • Verify existing functionality still works
    • Test edge cases and error conditions

  4. Commit your changes with descriptive messages:

    git commit -m "feat: add support for custom Git commands"
git commit -m "fix: handle empty git repository edge case"

  5. Push to your fork and create a pull request:

    git push origin feature/your-feature-name

  6. Create a pull request with:

    • Clear title describing the change
    • Detailed description of what was changed and why
    • Screenshots for UI changes
    • Testing instructions
    • Reference to any related issues

Pull Request Guidelines

  • Keep changes focused and atomic
  • Update documentation if needed
  • Add comments for complex logic
  • Ensure cross-platform compatibility
  • Test on Windows, macOS, and Linux when possible

Coding Standards

TypeScript/React

  • Use TypeScript strict mode
  • Prefer functional components with hooks
  • Use descriptive variable and function names
  • Keep components focused and single-purpose
  • Add type definitions for all props and state
// Good
interface CommandProps {
  command: GitCommand;
  onUpdate: (command: GitCommand) => void;
}

// Bad
function handleClick(data: any) {
  // unclear what data contains
}

Rust

  • Follow standard Rust conventions (cargo fmt)
  • Use descriptive error types
  • Add documentation comments for public functions
  • Prefer Result<T, E> over panics
  • Use serde for serialization consistently
// Good
#[tauri::command]
async fn validate_alias_name(alias_name: String) -> Result<ValidationResponse, String> {
    // Implementation
}

// Add documentation
/// Validates a Git alias name and checks if it already exists
/// Returns validation status and helpful messages for the user

CSS

  • Use semantic class names
  • Follow mobile-first responsive design
  • Use CSS custom properties for theming
  • Keep specificity low
  • Group related styles together

Testing

Manual Testing

When testing changes:

  1. Basic functionality: Create, preview, and delete aliases
  2. Edge cases: Empty inputs, invalid Git repos, network failures
  3. Cross-platform: Test on different operating systems
  4. AI features: Test OpenAI integration with valid/invalid keys
  5. Error handling: Verify graceful error handling

Automated Testing

We're working on adding automated tests. Future areas:

  • Unit tests for Rust commands
  • Integration tests for Git operations
  • Frontend component testing
  • End-to-end testing with Playwright

Bug Reports

When reporting bugs, please include:

  1. Environment information:

    • Operating system and version
    • Node.js version
    • Rust version
    • Git version

  2. Steps to reproduce:

    • Clear, numbered steps
    • Expected behavior
    • Actual behavior

  3. Additional context:

    • Screenshots or screen recordings
    • Error messages or logs
    • Relevant configuration

Use the bug report template when creating issues.

Feature Requests

For feature requests:

  1. Describe the problem the feature would solve
  2. Explain your proposed solution with examples
  3. Consider alternatives you've thought about
  4. Estimate complexity if you're familiar with the codebase

Development Tips

Debugging

  • Use console.log() in React components for frontend debugging
  • Use println!() or eprintln!() in Rust for backend debugging
  • Check the browser developer tools for frontend errors
  • Monitor the terminal running tauri dev for Rust errors

Common Issues

Rust compilation errors: Make sure you have the latest stable Rust toolchain

Frontend not updating: Check that Vite dev server is running on port 1420

Tauri commands not found: Ensure commands are properly registered in main.rs

Git operations failing: Verify you're testing in a valid Git repository

Building for Distribution

# Development build
npm run tauri dev

# Production build  
npm run tauri build

Questions?

  • Create a GitHub issue for questions about contributing
  • Check existing issues and discussions first
  • Be specific about what you're trying to accomplish

Thank you for contributing to Git Alias Generator! 🚀