Contributing to Mastering A*

Welcome to the Community!

Thank you for your interest in helping improve this project! Whether you're fixing a subtle bug, optimizing a performance bottleneck, improving the documentation, or introducing new research insights, your contributions are invaluable to the community. This project aims to be not just a code repository, but a central, community-maintained educational resource for pathfinding enthusiasts of all levels.

Contribution Guidelines and Workflow

To ensure maintainability and high code quality, we follow a structured contribution workflow. Please adhere to the following steps for all non-trivial changes:

1. Open an Issue First: Before starting significant work, please open an issue to discuss your proposed changes. This helps avoid duplicate work and ensures the feature aligns with the project’s pedagogical goals.
2. Fork and Clone: Fork the repository to your own GitHub account and clone it locally: git clone https://github.com/your-username/A-Pathfinding-Algorithm.
3. Dedicated Branching: Create a new branch with a descriptive name, such as fix/performance-bottleneck or feat/add-octile-heuristic.
4. Implementation: Implement your changes. Please prioritize readability and documentation over clever, obfuscated code.
5. Testing: Any new functionality or algorithmic change must be accompanied by updated unit or integration tests. We run automated tests on every PR; your code must pass them to be considered.
6. Pull Request (PR): When ready, open a Pull Request. Provide a concise but detailed explanation of your changes, including any performance benchmarks if you are introducing an optimization.

Code and Style Standards

Consistency is key to project longevity. To maintain clean, maintainable code, please follow these guidelines:

• Descriptive Naming: Use camelCase for all functions and variables. Names should be self-documenting; pathfinder.findPath() is preferred over pf.calc().
• Modular Design: Keep functions focused. A function should ideally do one thing and do it well. Large, monolithic functions should be decomposed into smaller, testable sub-functions.
• Comprehensive JSDoc: All public methods, class properties, and utility functions MUST be documented with JSDoc, detailing parameters, return types, and any assumptions (e.g., "The grid must be non-empty and 2D").
• Performance Consciousness: If you are optimizing core search logic, please benchmark your changes. Any performance claim must be supported by numbers (e.g., "This change reduces node exploration by 15% on large mazes").

Ways You Can Help

Beyond code, you can contribute in many ways:

• Educational Content: Propose improvements to the learning modules, clarify confusing concepts, or suggest new modules.
• Visualizer Features: Suggest or implement new interactive features for the demo visualizer (e.g., importing custom maps, new visualization styles).
• Issue Reporting: Found a bug or inconsistent behavior? Please provide a detailed issue report, ideally with a reproduction script or a screenshot/recording if it's a visualization bug.