Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
202 lines (163 loc) · 8.42 KB

CONTRIBUTING.md

File metadata and controls

202 lines (163 loc) · 8.42 KB

Contributing to Chess Ultimate

Thank you for your interest in contributing to Chess Ultimate! We welcome contributions from the community, including bug reports, feature requests, code improvements, and documentation enhancements. This guide outlines how to get involved and help improve this open-source chess game.

Table of Contents

Code of Conduct

All contributors are expected to adhere to the Code of Conduct. This ensures a respectful and inclusive environment for everyone involved in the project.

How to Contribute

Reporting Bugs

If you encounter a bug in Chess Ultimate:

  1. Check Existing Issues: Search the Issues page to see if the bug has already been reported.
  2. Create a New Issue: If the bug is new, open a new issue and provide:
    • A clear title and description of the bug.
    • Steps to reproduce the issue (e.g., specific moves, settings).
    • Expected and actual behavior.
    • Screenshots, videos, or browser console logs, if applicable.
    • Your environment (e.g., browser, operating system, device).
  3. Use the Bug Report Template: Follow the template provided in the issue creation form for consistency.

Example Bug Report:

  • Title: "Pawn Promotion Modal Fails to Appear"
  • Description: When a pawn reaches the 8th rank, the promotion modal does not display.
  • Steps: Start a game, move a white pawn to a8, observe no modal.
  • Expected: Modal with Queen, Rook, Bishop, Knight options appears.
  • Environment: Chrome 120, Windows 11.

Suggesting Features

We welcome ideas to enhance Chess Ultimate! To suggest a feature:

  1. Check Existing Requests: Review the Issues page to avoid duplicates.
  2. Submit a Feature Request: Open a new issue and include:
    • A clear title and detailed description of the feature.
    • The problem it solves or the benefit it provides (e.g., improves AI, adds online play).
    • Any relevant examples, mockups, or references to similar features in other chess apps.
  3. Use the Feature Request Template: Follow the provided template to structure your suggestion.

Example Feature Request:

  • Title: "Add Stockfish Integration for Stronger AI"
  • Description: Integrate Stockfish.js to replace the random-move AI with a configurable difficulty level.
  • Benefit: Makes the game more challenging and appealing to advanced players.

Submitting Pull Requests

To contribute code or documentation:

  1. Fork the Repository:

    • Fork the Chess Ultimate repository.
    • Clone your fork to your local machine: 
      git clone https://github.com/YOUR_USERNAME/Chess-Ultimate.git

  2. Create a Branch:

    • Create a new branch for your changes: 
      git checkout -b feature/your-feature-name
    • Use descriptive branch names (e.g., fix/pawn-promotion-bug, feature/add-stockfish-ai).

  3. Make Changes:

    • Implement your changes in the codebase or documentation.
    • Follow the Code Style Guidelines below.
    • Test your changes locally across multiple browsers.

  4. Commit Changes:

    • Write clear, concise commit messages: 
      git commit -m "Add feature: implement Stockfish AI integration"
    • Reference related issues (e.g., Fixes #123).

  5. Push and Create a Pull Request:

    • Push your branch to your fork: 
      git push origin feature/your-feature-name
    • Open a pull request (PR) against the main branch of the original repository.
    • Use the PR template and provide:
      • A description of the changes.
      • The issue number(s) addressed (if any).
      • Screenshots or videos for UI changes.
      • Testing performed (e.g., browsers tested, edge cases).

  6. Code Review:

    • Respond to feedback from maintainers.
    • Make requested changes and update your PR as needed.
    • Your PR will be merged once approved.

Development Setup

To set up a development environment for Chess Ultimate:

  1. Prerequisites:

    • A modern web browser (e.g., Chrome, Firefox, Edge).
    • A code editor (e.g., VS Code, Sublime Text).
    • Git installed for version control.
    • (Optional) A local server (e.g., Python’s http.server or Node.js http-server) for testing.

  2. Clone the Repository:

    git clone https://github.com/VoxDroid/Chess-Ultimate.git
cd Chess-Ultimate

  3. Install Dependencies:

    • No additional installations are required, as all dependencies (e.g., Bootstrap, Font Awesome, particles.js) are loaded via CDNs or included in the assets folder.
    • Ensure the assets, css, and js folders are present.

  4. Run the Application:

    • Open index.html in a browser, or serve the directory with a local server: 
      python -m http.server 8000
      Then visit http://localhost:8000.

  5. Test Changes:

    • Verify functionality in multiple browsers (e.g., Chrome, Firefox).
    • Test gameplay (e.g., move pieces, trigger AI, check promotion).
    • Check responsiveness on desktop and mobile devices.

Code Style Guidelines

To maintain consistency in the codebase:

  • HTML:
    • Use semantic HTML5 elements (e.g., <nav>, <section>).
    • Keep indentation at 2 spaces.
    • Use lowercase for tags and attributes.
    • Add ARIA attributes for accessibility (e.g., aria-label for buttons).
  • CSS:
    • Use kebab-case for class names (e.g., chess-board).
    • Organize styles in css/chess_styles.css with clear comments for sections.
    • Use CSS custom properties (e.g., --primary-color) for theming.
    • Keep indentation at 2 spaces.
  • JavaScript:
    • Use camelCase for variables and functions (e.g., movePiece).
    • Follow ES6+ conventions (e.g., const, let, arrow functions where appropriate).
    • Add comments for complex logic or functions.
    • Keep indentation at 2 spaces.
    • Organize code in js/chess_script.js (game logic), js/chess_color_themes.js (themes), and js/localization.js (translations).
  • File Structure:
    • Place images and piece assets in assets/chesspieces/.
    • Keep styles in css/chess_styles.css.
    • Maintain scripts in js/ folder.
  • Accessibility:
    • Ensure sufficient color contrast for readability.
    • Make interactive elements keyboard-accessible (e.g., tabindex).
    • Test with screen readers (e.g., NVDA, VoiceOver).
  • Localization:
    • Add new translations to js/localization.js using the i18n object.
    • Use data-i18n attributes for translatable elements.

Testing

Before submitting a pull request:

  • Manual Testing:
    • Test gameplay with various scenarios (e.g., castling, en passant, checkmate).
    • Verify UI elements (e.g., navbar dropdowns, settings modal, move history).
    • Check responsiveness across screen sizes (desktop, tablet, mobile).
    • Test settings (e.g., theme changes, piece styles, board size).
  • Browser Testing:
    • Verify functionality in Chrome, Firefox, Edge, and Safari.
    • Check for console errors in the browser developer tools.
  • Edge Cases:
    • Test invalid moves (e.g., moving a piece to an occupied square).
    • Ensure timers stop at 0 and trigger game over.
    • Verify AI moves are valid and don’t break the game.
    • Test promotion modal with different piece styles.
  • Localization:
    • Switch languages and ensure all text updates correctly.
    • Verify right-to-left (RTL) languages if added (e.g., Arabic).
  • Accessibility:
    • Test keyboard navigation (e.g., tab through controls).
    • Verify screen reader compatibility.

Community

Join the Chess Ultimate community:

  • GitHub Discussions: Share ideas or ask questions in the Discussions section.
  • Issues: Report bugs or suggest features on the Issues page.
  • GitHub Stars: Show your support by starring the repository.

Thank you for contributing to Chess Ultimate! Your efforts help make this game better for players worldwide.