Contributing

Welcome Contributors!

Thank you for your interest in contributing to the Sorting Algorithms Visualiser! This project is open source and welcomes contributions from developers of all skill levels.

First-time contributors are especially welcome! Don’t hesitate to ask questions or request guidance through GitHub issues or pull requests.

Ways to Contribute

Report Bugs

Found a bug? Open an issue on GitHub with detailed reproduction steps and your environment details.

Suggest New Algorithms

Have an interesting sorting algorithm to visualize? Propose it through a GitHub issue or implement it directly!

Improve Documentation

Help others understand the project better by improving code comments, README files, or adding usage examples.

Optimize Performance

Identify and fix performance bottlenecks, optimize rendering, or improve algorithm efficiency.

Add New Features

Enhance the visualizer with:

Additional UI controls
New color schemes
Sound effects for comparisons
Adjustable animation speeds
Different visualization modes

Code Quality

Refactor code, improve structure, add error handling, or modernize C++ usage.

Getting Started

Fork the repository

Create your own fork of the project:

Visit github.com/DevBoiAgru/SortingAlgorithmsVisualiser
Click the “Fork” button in the top-right corner
Clone your fork locally:

git clone https://github.com/YOUR-USERNAME/SortingAlgorithmsVisualiser.git
cd SortingAlgorithmsVisualiser

Create a feature branch

Create a new branch for your changes:

git checkout -b feature/your-feature-name

Use descriptive branch names:

feature/add-radix-sort
fix/font-loading-error
docs/improve-readme
refactor/sorting-functions

Set up the development environment

Follow the Building from Source guide to set up your development environment and build the project.Ensure you can successfully:

Build the project
Run the application
Make and test changes

Make your changes

Implement your feature, fix, or improvement:

Write clean, readable code
Follow the existing code style
Add comments for complex logic
Test your changes thoroughly

Test thoroughly

Before submitting, test your changes:

Build in both Debug and Release configurations
Test on x86 and x64 platforms (if applicable)
Verify the application runs correctly
Test edge cases and error conditions
Ensure existing functionality still works

Commit your changes

Create meaningful commit messages:

git add .
git commit -m "Add radix sort algorithm with visualization"

Good commit message examples:

Fix font loading error on startup
Add command-line argument for window size
Optimize rendering for large list sizes
Refactor button creation into separate class

Push and create a pull request

Push your branch to GitHub:

git push origin feature/your-feature-name

Then create a pull request:

Go to your fork on GitHub
Click “Compare & pull request”
Fill in the PR template with details
Submit the pull request

Code Style Guidelines

To maintain consistency across the codebase:

Naming Conventions

// Variables: camelCase
int listSize = 250;
bool canClick = true;

// Constants: UPPER_SNAKE_CASE
const int WINDOW_X = 1280;
const int WINDOW_Y = 720;

// Functions: camelCase
void HighlightRectangles(int current, int next, int prev);
bool is_number(const std::string& s);

// Classes: PascalCase
class Button {
    // ...
};

Code Organization

Keep functions focused: Each function should do one thing well
Use meaningful names: Variable and function names should be self-documenting
Comment complex logic: Especially algorithm implementations
Avoid magic numbers: Use named constants instead

Example: Adding a New Sorting Algorithm

// Good: Clear function name and comments
void RadixSort() {
    if (!canClick) return;
    canClick = false;
    
    // Find the maximum number to determine digit count
    int maxNum = *std::max_element(numbers.begin(), numbers.end());
    
    // Perform counting sort for each digit
    for (int exp = 1; maxNum / exp > 0; exp *= 10) {
        CountingSortByDigit(exp);
    }
    
    canClick = true;
}

Formatting

Indentation: Use consistent indentation (the project uses 4 spaces)
Braces: Opening brace on same line for functions and control structures
Spacing: Space after keywords (if, for, while), around operators
Line length: Keep lines reasonably short (under 120 characters when possible)

Pull Request Guidelines

When submitting a pull request:

PR Description Should Include:

What: Brief description of changes
Why: Reason for the changes
How: Technical approach (if not obvious)
Testing: How you tested the changes
Screenshots: For UI changes, include before/after screenshots

Example PR Template:

## Description
Adds visualization for Radix Sort algorithm

## Motivation
Radix Sort is a non-comparative sorting algorithm that can be faster than
comparison-based sorts for certain data types. This adds variety to the
available sorting algorithms.

## Changes
- Implemented RadixSort() function
- Added "Radix Sort" button to UI
- Updated button layout to accommodate new algorithm

## Testing
- Tested with list sizes from 5 to 500
- Verified correct sorting behavior
- Checked performance on Debug and Release builds
- Tested on x64 Windows 11

## Screenshots
[Include screenshot of the new button and algorithm in action]

PR Checklist:

Code follows the project’s style guidelines
Changes have been tested thoroughly
No compiler warnings introduced
Comments added for complex code
PR description is clear and complete
Branch is up to date with main

Reporting Bugs

When reporting bugs, include:

Description: Clear description of the bug
Steps to Reproduce: Detailed steps to reproduce the issue
Expected Behavior: What should happen
Actual Behavior: What actually happens
Environment:
- OS version (e.g., Windows 11)
- Visual Studio version
- Build configuration (Debug/Release, x86/x64)
- SFML version
Screenshots/Videos: If applicable
Error Messages: Full error messages or stack traces

Feature Requests

For feature requests, describe:

Feature Description: What you want to add
Use Case: Why this feature would be useful
Proposed Implementation: If you have ideas on how to implement it
Alternatives: Other approaches you’ve considered

Code Review Process

Automated Checks: Ensure your PR passes any automated checks
Maintainer Review: A project maintainer will review your changes
Feedback: Address any requested changes or questions
Approval: Once approved, your PR will be merged
Recognition: Contributors are acknowledged in release notes

Project License

This project is licensed under the MIT License. By contributing, you agree that your contributions will be licensed under the same license.

MIT License

Commercial use
Modification
Distribution
Private use

See the LICENSE file for full details.

Getting Help

If you need help:

GitHub Issues: Ask questions in a new issue
Pull Requests: Request feedback in your PR
Code Comments: Check existing code for examples
Documentation: Review the Building and Dependencies pages

Suggested Contributions

Looking for ideas? Here are some suggested improvements:

Easy (Good for beginners):

Add more color schemes
Improve error messages
Add keyboard shortcuts
Update README with usage examples

Medium:

Implement additional sorting algorithms (Radix, Bucket, Shell sort)
Add algorithm complexity information display
Create a settings menu for customization
Add sound effects for comparisons/swaps

Advanced:

Port to cross-platform (Linux/macOS support)
Add CMake build system
Implement algorithm comparison mode (run multiple algorithms simultaneously)
Add recording/export functionality (save visualization as video)
Create algorithm step-by-step mode with explanations

Community Guidelines

Be respectful and constructive
Welcome newcomers and help them learn
Focus on technical merit, not personal opinions
Give credit where credit is due
Have fun and learn together!

Ready to Contribute?

Visit the GitHub repository to get started!

Overview

Algorithms

Usage

Development

Welcome Contributors!

Ways to Contribute

Report Bugs

Suggest New Algorithms

Improve Documentation

Optimize Performance

Add New Features

Code Quality

Getting Started

Code Style Guidelines

Naming Conventions

Code Organization

Example: Adding a New Sorting Algorithm

Formatting

Pull Request Guidelines

PR Description Should Include:

Example PR Template:

PR Checklist:

Reporting Bugs

Feature Requests

Code Review Process

Project License

MIT License

Getting Help

Suggested Contributions

Easy (Good for beginners):

Medium:

Advanced:

Community Guidelines

Ready to Contribute?

Build docs developers (and LLMs) love

Overview

Algorithms

Usage

Development

​Welcome Contributors!

​Ways to Contribute

Report Bugs

Suggest New Algorithms

Improve Documentation

Optimize Performance

Add New Features

Code Quality

​Getting Started

​Code Style Guidelines

​Naming Conventions

​Code Organization

​Example: Adding a New Sorting Algorithm

​Formatting

​Pull Request Guidelines

​PR Description Should Include:

​Example PR Template:

​PR Checklist:

​Reporting Bugs

​Feature Requests

​Code Review Process

​Project License

MIT License

​Getting Help

​Suggested Contributions

​Easy (Good for beginners):

​Medium:

​Advanced:

​Community Guidelines

Ready to Contribute?

Build docs developers (and LLMs) love

Welcome Contributors!

Ways to Contribute

Getting Started

Code Style Guidelines

Naming Conventions

Code Organization

Example: Adding a New Sorting Algorithm

Formatting

Pull Request Guidelines

PR Description Should Include:

Example PR Template:

PR Checklist:

Reporting Bugs

Feature Requests

Code Review Process

Project License

Getting Help

Suggested Contributions

Easy (Good for beginners):

Medium:

Advanced:

Community Guidelines