Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
348 lines (299 loc) · 17.8 KB

CONTRIBUTING.md

File metadata and controls

348 lines (299 loc) · 17.8 KB

🌟 Contributing to SortVision 🌟

Help us improve SortVision and make sorting algorithms more visual and intuitive!

Contributions Welcome Platform GitHub Issues Pull Requests License: MIT

🛠️ How to Contribute

1. Fork the Repository

  • Click the Fork button on the top-right corner of the repository page to create your copy.

2. Clone Your Fork

  • Clone the forked repository to your local machine: 
    git clone https://github.com/<your-username>/SortVision.git
  • Replace <your-username> with your GitHub username.

3. Create a New Branch

  • Create a branch for your feature or bug fix: 
    git checkout -b feature-name
  • Use a meaningful branch name (e.g., improve-ui, fix-bug-xyz).

4. Make Changes

  • Implement your changes in the codebase.
  • Ensure your code follows best practices and is well-documented.
  • Run tests and verify everything is working.

5. Commit Your Changes

  • Stage and commit your changes: 
    git add .
git commit -m "Describe your changes (e.g., Improved animation speed)"

6. Push to Your Branch

  • Push the changes to your forked repository: 
    git push origin feature-name

7. Submit a Pull Request

  • Go to the original repository and click New Pull Request.
  • Select your branch, provide a detailed description of your changes, and submit the pull request.

📂 Project Structure

Below is the complete overview of the SortVision project structure:

SortVision/
├─ .github/                    # GitHub specific configurations
│  ├─ ISSUE_TEMPLATE/          # Templates for GitHub issues
│  │  ├─ bug_report.md         # Bug report template
│  │  ├─ config.yml            # Issue template configuration
│  │  ├─ documentation.md      # Documentation request template
│  │  ├─ feature_request.md    # Feature request template
│  │  └─ performance.md        # Performance issue template
│  ├─ dependabot.yml           # Dependabot configuration
│  └─ pull_request_template.md # PR template
├─ .gitignore                  # Git ignore configuration
├─ CODE_OF_CONDUCT.md          # Community code of conduct
├─ CONTRIBUTING.md             # Contribution guidelines (this file)
├─ LICENSE                     # MIT license file
├─ README.md                   # Project documentation
├─ SECURITY.md                 # Security policy and reporting
└─ SortVision/                 # Main application directory
   ├─ .env.example             # Environment variables template
   ├─ Dockerfile               # Docker containerization config
   ├─ api/                     # API endpoints
   │  └─ gemini.js             # Gemini AI API integration
   ├─ components.json          # Component configuration
   ├─ docker-compose.yml       # Docker Compose configuration
   ├─ eslint.config.js         # ESLint configuration
   ├─ jsconfig.json            # JavaScript configuration
   ├─ next.config.mjs          # Next.js configuration
   ├─ nginx.conf               # Nginx configuration
   ├─ package-lock.json        # NPM package lock
   ├─ package.json             # NPM package definition
   ├─ pnpm-lock.yaml           # PNPM package lock
   ├─ postcss.config.mjs       # PostCSS configuration
   ├─ public/                  # Public static assets
   │  ├─ code/                 # Algorithm implementations in multiple languages
   │  │  ├─ bubble/            # Bubble Sort implementations
   │  │  │  ├─ c/              # C implementation
   │  │  │  ├─ cpp/            # C++ implementation
   │  │  │  ├─ csharp/         # C# implementation
   │  │  │  ├─ dart/           # Dart implementation
   │  │  │  ├─ golang/         # Go implementation
   │  │  │  ├─ haskell/        # Haskell implementation
   │  │  │  ├─ java/           # Java implementation
   │  │  │  ├─ javascript/     # JavaScript implementation
   │  │  │  ├─ julia/          # Julia implementation
   │  │  │  ├─ kotlin/         # Kotlin implementation
   │  │  │  ├─ lua/            # Lua implementation
   │  │  │  ├─ php/            # PHP implementation
   │  │  │  ├─ pseudocode/     # Pseudocode representation
   │  │  │  ├─ python/         # Python implementation
   │  │  │  ├─ r/              # R implementation
   │  │  │  ├─ ruby/           # Ruby implementation
   │  │  │  ├─ rust/           # Rust implementation
   │  │  │  ├─ scala/          # Scala implementation
   │  │  │  ├─ swift/          # Swift implementation
   │  │  │  └─ typescript/     # TypeScript implementation
   │  │  ├─ bucket/            # Bucket Sort implementations (same language structure)
   │  │  ├─ heap/              # Heap Sort implementations (same language structure)
   │  │  ├─ insertion/         # Insertion Sort implementations (same language structure)
   │  │  ├─ merge/             # Merge Sort implementations (same language structure)
   │  │  ├─ quick/             # Quick Sort implementations (same language structure)
   │  │  ├─ radix/             # Radix Sort implementations (same language structure)
   │  │  └─ selection/         # Selection Sort implementations (same language structure)
   │  ├─ devTools/             # Developer tools directory
   │  │  ├─ core.js            # Core utilities and initialization
   │  │  ├─ device-info.js     # Device detection and information
   │  │  ├─ index.js           # Main entry point for debug tools
   │  │  ├─ monitoring.js      # Performance monitoring utilities
   │  │  ├─ performance.js     # Performance metrics tracking
   │  │  └─ ui.js              # Debug UI components and panel
   │  ├─ favicon.svg           # Site favicon
   │  ├─ google12e2679e2ea95334.html # Google site verification
   │  ├─ manifest.json         # PWA manifest
   │  ├─ mobile.css            # Mobile-specific styles
   │  ├─ og-image.png          # Open Graph image for sharing
   │  ├─ robots.txt            # Search engine crawling instructions
   │  ├─ sitemap.xml           # Site map for search engines
   │  ├─ splash.svg            # App splash screen
   │  ├─ sw.js                 # Service worker for offline support
   │  └─ twitter-image.png     # Twitter card image
   ├─ scripts/                 # Build and utility scripts
   │  └─ generate-sitemap.js   # Sitemap generator
   ├─ server/                  # Backend server directory
   │  └─ index.js              # Express server for API proxy
   ├─ src/                     # Source code directory
   │  ├─ App.css               # App-level styles
   │  ├─ App.jsx               # Main App component
   │  ├─ algorithms/           # Sorting algorithm implementations
   │  │  ├─ bubbleSort.jsx     # Bubble sort implementation
   │  │  ├─ bucketSort.jsx     # Bucket sort implementation
   │  │  ├─ heapSort.jsx       # Heap sort implementation
   │  │  ├─ index.js           # Algorithm exports
   │  │  ├─ insertionSort.jsx  # Insertion sort implementation
   │  │  ├─ mergeSort.jsx      # Merge sort implementation
   │  │  ├─ quickSort.jsx      # Quick sort implementation
   │  │  ├─ radixSort.jsx      # Radix sort implementation
   │  │  └─ selectionSort.jsx  # Selection sort implementation
   │  ├─ app/                  # Next.js App Router directory
   │  │  ├─ [[...slug]]/       # Dynamic catch-all route
   │  │  │  ├─ client.jsx      # Client-side component
   │  │  │  └─ page.jsx        # Page component with SEO metadata
   │  │  ├─ favicon.svg        # App favicon
   │  │  ├─ globals.css        # Global CSS styles
   │  │  └─ layout.jsx         # Root layout component
   │  ├─ components/           # UI components
   │  │  ├─ MobileOverlay.jsx  # Mobile device support
   │  │  ├─ SEOContent.jsx     # SEO content component
   │  │  ├─ SortingVisualizer.jsx # Main visualization component
   │  │  ├─ chatbot/           # AI Chatbot components
   │  │  │  ├─ ChatAssistant.jsx # Main chatbot component
   │  │  │  ├─ ChatButton.jsx  # Chat button trigger
   │  │  │  ├─ ChatModal.jsx   # Chat modal dialog
   │  │  │  ├─ assistantEngine.js # AI engine logic with offline knowledge
   │  │  │  └─ index.js        # Chatbot exports
   │  │  ├─ feedback/          # User feedback system
   │  │  │  ├─ FeedbackButton.jsx # Feedback button
   │  │  │  ├─ FeedbackForm.jsx # Feedback form
   │  │  │  ├─ FeedbackModal.jsx # Feedback modal
   │  │  │  ├─ githubService.js # GitHub integration for feedback
   │  │  │  ├─ index.js        # Feedback exports
   │  │  │  └─ locationService.js # Location detection service
   │  │  ├─ panels/            # UI panels directory
   │  │  │  ├─ ConfigPanel.jsx # Configuration panel
   │  │  │  ├─ ContributionPanel.jsx # Contribution information panel
   │  │  │  ├─ DetailsPanel.jsx # Algorithm details panel
   │  │  │  ├─ MetricsPanel.jsx # Performance metrics panel
   │  │  │  ├─ config/         # Configuration components
   │  │  │  │  ├─ AlgorithmSelector.jsx # Algorithm selection
   │  │  │  │  ├─ ArraySizeControl.jsx # Array size controls
   │  │  │  │  ├─ ComplexityInfo.jsx # Complexity information display
   │  │  │  │  ├─ ControlButtons.jsx # Control buttons (play/pause/reset)
   │  │  │  │  ├─ SpeedControl.jsx # Animation speed control
   │  │  │  │  └─ index.js     # Config component exports
   │  │  │  ├─ contributions/  # Contribution-related components
   │  │  │  │  ├─ guide/       # Contribution guides
   │  │  │  │  │  ├─ BestPractices.jsx # Best practices guide
   │  │  │  │  │  ├─ ContributeGuide.jsx # How to contribute guide
   │  │  │  │  │  ├─ QuickReferences.jsx # Quick reference guide
   │  │  │  │  │  └─ index.js  # Guide component exports
   │  │  │  │  ├─ index.js     # Contribution component exports
   │  │  │  │  ├─ overview/    # Contribution overview
   │  │  │  │  │  ├─ ContributorList.jsx # List of contributors
   │  │  │  │  │  ├─ ContributorStats.jsx # Contributor statistics
   │  │  │  │  │  ├─ RepositoryHealth.jsx # Repository health metrics
   │  │  │  │  │  └─ index.js  # Overview component exports
   │  │  │  │  └─ ssoc/        # SSOC leaderboard system
   │  │  │  │     ├─ ExportButton.jsx # Data export functionality
   │  │  │  │     ├─ LeaderboardList.jsx # Leaderboard display
   │  │  │  │     ├─ LeaderboardRow.jsx # Individual row component
   │  │  │  │     ├─ config.js # Configuration settings
   │  │  │  │     ├─ exportService.js # Export service logic
   │  │  │  │     ├─ githubService.js # GitHub API integration
   │  │  │  │     └─ index.js  # SSOC exports
   │  │  │  ├─ details/        # Detail components
   │  │  │  │  ├─ AlgorithmDetails.jsx # Algorithm detail display
   │  │  │  │  ├─ AlgorithmInfo.jsx # Algorithm information
   │  │  │  │  ├─ AlgorithmSelector.jsx # Algorithm selection
   │  │  │  │  ├─ DataPanel.jsx # Data display panel
   │  │  │  │  ├─ FunFact.jsx  # Fun facts about algorithms
   │  │  │  │  ├─ InteractiveTip.jsx # Interactive tips
   │  │  │  │  ├─ LanguageSelector.jsx # Programming language selector
   │  │  │  │  └─ index.js     # Detail component exports
   │  │  │  ├─ index.js        # Panel component exports
   │  │  │  └─ metrics/        # Metric components
   │  │  │     ├─ AlgorithmComparison.jsx # Algorithm comparisons
   │  │  │     ├─ CurrentRunMetrics.jsx # Current run metrics
   │  │  │     ├─ RankingCard.jsx # Algorithm ranking display
   │  │  │     ├─ TestControls.jsx # Testing controls
   │  │  │     ├─ WinnerSummary.jsx # Algorithm comparison results
   │  │  │     └─ index.js     # Metric component exports
   │  │  ├─ settings/          # Application settings
   │  │  │  ├─ SettingsButton.jsx # Settings button
   │  │  │  ├─ SettingsForm.jsx # Settings form
   │  │  │  ├─ SettingsModal.jsx # Settings modal
   │  │  │  └─ index.js        # Settings exports
   │  │  ├─ sortingVisualizer/ # Visualization components
   │  │  │  ├─ AudioControls.jsx # Audio control components
   │  │  │  ├─ PerformanceMetrics.jsx # Performance display
   │  │  │  ├─ SortingControls.jsx # Sorting control buttons
   │  │  │  ├─ SortingHeader.jsx # Visualization header
   │  │  │  ├─ SortingVisualizer.jsx # Main visualizer
   │  │  │  └─ index.js        # Visualizer component exports
   │  │  ├─ ui/                # UI component library
   │  │  │  ├─ VolumeControl.jsx # Volume control component
   │  │  │  ├─ badge.jsx       # Badge component
   │  │  │  ├─ button.jsx      # Button component
   │  │  │  ├─ card.jsx        # Card component
   │  │  │  ├─ input.jsx       # Input component
   │  │  │  ├─ select.jsx      # Select dropdown component
   │  │  │  ├─ slider.jsx      # Slider component
   │  │  │  └─ tabs.jsx        # Tabs component
   │  │  └─ visualizations/    # Visualization components
   │  │     ├─ ArrayVisualization.jsx # Array visual representation
   │  │     └─ index.js        # Visualization component exports
   │  ├─ context/              # React Context providers
   │  │  └─ AlgorithmState.jsx # Algorithm state management
   │  ├─ hooks/                # Custom React hooks
   │  │  └─ useAudio.js        # Audio management hook
   │  ├─ index.css             # Global styles
   │  ├─ lib/                  # Library utilities
   │  │  └─ utils.js           # Shared utility functions
   │  └─ utils/                # Utility modules
   │     ├─ audioEngine.js     # Audio engine for sound effects
   │     ├─ seo.js             # SEO optimization utilities
   │     ├─ soundEffects.js    # Sound effect definitions
   │     └─ themeUtils.js      # Theme management utilities
   └─ vercel.json              # Vercel deployment configuration

📁 Key Areas for Contributors:

🎯 Algorithm Development (src/algorithms/ & public/code/)

  • Visualization Logic: Implement step-by-step algorithm execution in JSX files
  • Multi-Language Support: Add implementations in 20+ programming languages
  • Algorithm Optimization: Improve performance and add new sorting algorithms

🤖 AI Features (src/components/chatbot/)

  • Knowledge Base: Expand algorithm knowledge in assistantEngine.js
  • Query Understanding: Improve natural language processing
  • Response Generation: Enhance contextual responses

📊 Data Visualization (src/components/panels/)

  • Metrics Display: Enhance performance tracking and comparison
  • UI Panels: Improve user interface components
  • Interactive Elements: Add new interactive features

🔧 Developer Experience (public/devTools/)

  • Performance Monitoring: Enhance debugging tools
  • Device Detection: Improve cross-platform compatibility
  • Development Utils: Add new developer utilities

🌐 Backend Integration (server/ & api/)

  • API Development: Expand server capabilities
  • External Services: Add new integrations
  • Data Management: Improve data handling

Why This Structure?

  • 🚀 Scalable → Modular design supports easy feature additions
  • 🔧 Maintainable → Clear separation of concerns
  • 🎯 Educational → Comprehensive algorithm implementations
  • 🤝 Collaborative → Well-organized for team development
  • 🌍 Accessible → Multi-language support for global learning

🤝 Code of Conduct

By contributing to this project, you agree to abide by our Code of Conduct. Be respectful, inclusive, and collaborative in all interactions.

💡 Tips for Contributing

  1. Check the Issues tab for open feature requests or bug reports.
  2. Keep your commits small and focused on a single change.
  3. Avoid committing unnecessary files.
  4. Regularly sync your fork with the main repository: 
    git pull upstream main

🛠️ Need Help?

If you have any questions:

  1. Open an Issue in the repository.
  2. Contact the maintainers via the repository discussion section.

Thank you for contributing to SortVision! 🎉 Let's make sorting visual, interactive, and fun! 🚀