Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
83 lines (61 loc) · 3.41 KB

CONTRIBUTING.md

File metadata and controls

83 lines (61 loc) · 3.41 KB

🤝 Contributing to Universal Learning Engine (ULE)

Thank you for your interest in contributing to ULE — a universal adaptive learning engine with automatic subject discovery and intelligent difficulty adjustment.

This project began as part of a personal learning journey and has grown into a sophisticated open-source foundation for adaptive, terminal-based education systems.

We welcome contributions in all forms:

  • 🧠 New questions or concept sets for existing subjects
  • 🌐 New learning subjects (Math, JavaScript, Logic, etc.)
  • 🧪 Bug fixes or performance improvements
  • 🧰 Feature suggestions or UI enhancements
  • 📚 Documentation improvements

🚀 Getting Started

For Quick Contributions

  1. Clone the repo: git clone https://github.com/RyanRustill/universal-learning-engine.git
  2. Launch the system: python3 ule.py
  3. Explore the engine/ (core algorithms) and subjects/python/ (content) folders

For Content Contributors

If you're adding questions or creating new subjects:

  • Follow the JSON schema shown in subjects/python/python_questions.json
  • Ensure questions include clear, educational explanations
  • Test your content using the question analyzer: python3 tests/analyze_questions.py your_subject
  • Verify quality metrics: aim for GOOD rating (25+ questions, balanced difficulty)
  • See EXTENDIBILITY.md for detailed step-by-step guidance

For Code Contributors

  • Follow the existing modular structure (engine/core/, engine/ui/, engine/modules/)
  • Use Python 3.8+ with type hints and dataclasses
  • Run the test suite before submitting: python3 tests/run_tests.py
  • Ensure all 40 tests pass (current success rate: 95%+)
  • Test the universal launcher discovers your changes automatically
  • Submit a pull request with a clear summary

🧪 Testing Requirements

All contributions must pass our comprehensive testing infrastructure:

# Run all tests (required before PRs)
python3 tests/run_tests.py

# Analyze question databases for quality
python3 tests/analyze_questions.py

# Test specific functionality
python3 -m unittest tests.test_core_engine -v
python3 -m unittest tests.test_ui -v

Quality Standards:

  • ✅ All unit tests must pass
  • ✅ Question databases should achieve "GOOD" quality rating
  • ✅ New features require corresponding tests
  • ✅ No regression in existing functionality

🎯 Universal Learning Platform

ULE features sophisticated automatic discovery - simply add a subject module to subjects/[name]/ with a launcher file (ule_[name].py) and it appears instantly in the main menu. No hardcoding required!

The system includes:

  • 🧠 Adaptive algorithms that adjust difficulty based on performance
  • 🔄 Universal navigation with seamless return to main menu
  • 💾 Session persistence that remembers progress across restarts
  • 📊 Learning analytics with comprehensive progress tracking

🌟 What Makes This Special

This isn't just another educational tool - it's a universal learning engine that:

  • Works for any subject (Python, Math, Logic, etc.)
  • Never repeats questions within your learning journey
  • Provides detailed explanations for every answer
  • Teaches systematic reasoning through the "Detective Method"

📫 Questions?

Open an issue or email [ryanrustill@gmail.com]
We're especially welcoming of new contributors and learners who want to grow alongside the engine.

See you in the learning journey! 🧠