Skip to content

Contributing to VSD Fleet Management System

Thank you for your interest in contributing to VSD Fleet Management System! This document provides guidelines and information for contributors of all types - developers, business analysts, documentation writers, and fleet management experts.

📝 Project Background

This is a community fork of the original VVSD-LTD/vsd_fleet_ms project, enhanced with comprehensive documentation and additional features based on real customer needs. The original project was built by VVSD-LTD after studying SAP's fleet management solutions, making it one of the most sophisticated fleet management applications in the ERPNext ecosystem.

Why This Fork Exists: Instead of building a new fleet management system from scratch, this fork provides a solid foundation with professional documentation, allowing developers to start with a proven solution and contribute improvements.

🌟 Why Contribute?

VSD Fleet MS is more than just another fleet management system. It's a native ERPNext solution that brings enterprise-grade fleet management to organizations worldwide. By contributing, you're helping to:

  • Transform Transportation Operations - Enable efficient, cost-effective fleet management
  • Bridge Technology Gaps - Connect ERP systems with fleet operations
  • Support Global Logistics - Help companies manage cross-border and international transport
  • Build Open Source Excellence - Create a world-class, community-driven solution
  • Avoid Reinventing the Wheel - Build upon proven SAP-inspired architecture

🎯 Areas for Contribution

🚀 Development

  • Bug Fixes - Improve system stability and reliability
  • Feature Development - Add new capabilities and enhancements
  • Performance Optimization - Improve system speed and efficiency
  • Integration Development - Connect with third-party systems

📊 Business Logic

  • Workflow Optimization - Improve business processes and efficiency
  • Industry Expertise - Share transportation and logistics knowledge
  • Compliance Features - Add regulatory and legal compliance capabilities
  • Best Practices - Implement industry-standard procedures

📚 Documentation

  • User Guides - Create clear, comprehensive instructions
  • Technical Documentation - Document APIs, configurations, and integrations
  • Video Tutorials - Create visual learning resources
  • Case Studies - Document successful implementations

🧪 Testing & Quality

  • User Testing - Test features and provide feedback
  • Performance Testing - Validate system performance under load
  • Integration Testing - Test with various ERPNext configurations
  • Regression Testing - Ensure new changes don't break existing functionality

🐛 Known Issues & Easy First Contributions

DocType Naming Convention ⭐ Perfect for New Contributors

🎯 The Perfect First Contribution Opportunity!

Many doctypes are in plural format (e.g., trips, trucks, drivers) due to conflicts with existing ERPNext doctypes during local customization. This is a known issue that provides an excellent first contribution opportunity:

Why This Happened

There were conflicts with existing local customization app doctypes that were already present on sites. The following doctypes already existed and caused naming conflicts:

Existing ERPNext Doctypes that Caused Conflicts: - trip - Already exists in ERPNext core - truck - Already exists in ERPNext core
- driver - Already exists in ERPNext core - trailer - Already exists in ERPNext core - route - Already exists in ERPNext core - location - Already exists in ERPNext core - fuel - Already exists in ERPNext core - expense - Already exists in ERPNext core - payment - Already exists in ERPNext core - request - Already exists in ERPNext core

Solution Applied: The easiest solution was to make the doctypes plural to avoid naming conflicts: - trip → trips - truck → trucks - driver → drivers - trailer → trailers - route → routes - location → locations - fuel → fuels - expense → expenses - payment → payments - request → requests

The Issue

  • Current: trips, trucks, drivers, trailers, etc.
  • Should be: trip, truck, driver, trailer, etc.
  • Impact: Minor - affects naming convention only
  • Difficulty: Easy - suitable for new contributors

Files to Modify

  • vsd_fleet_ms/doctype/trips/ → vsd_fleet_ms/doctype/trip/
  • vsd_fleet_ms/doctype/trucks/ → vsd_fleet_ms/doctype/truck/
  • vsd_fleet_ms/doctype/drivers/ → vsd_fleet_ms/doctype/driver/
  • vsd_fleet_ms/doctype/trailers/ → vsd_fleet_ms/doctype/trailer/
  • And other similar plural doctypes

What You Need to Do

  1. Rename directories from plural to singular
  2. Update JSON files to reflect new names
  3. Update Python imports and references
  4. Update JavaScript references if any
  5. Test thoroughly to ensure nothing breaks

Why This is Perfect for New Contributors

  • ✅ Clear scope - well-defined task
  • ✅ Low risk - naming convention change only
  • ✅ Good learning - understand Frappe doctype structure
  • ✅ High impact - improves code consistency
  • ✅ Easy to test - clear before/after state

Other Easy Contribution Areas

  • Documentation improvements - Fix typos, add examples, clarify instructions
  • Code comments - Add docstrings and inline comments
  • UI text - Improve field labels and descriptions
  • Error messages - Make them more user-friendly

🛠️ Development Setup

Prerequisites

  • Python 3.10+
  • Node.js 16+
  • Git
  • Frappe Bench (for ERPNext development)

Local Development Environment

  1. Clone the Repository 

    git clone https://github.com/nelsonmpanju/Fleet-Management-System.git
cd Fleet-Management-System

  2. Install Dependencies 

    # Install Python dependencies
pip install -r requirements.txt

# Install Node.js dependencies (if any)
npm install

  3. Setup Frappe Bench 

    # Install Frappe Bench
pip install frappe-bench

# Initialize bench
bench init frappe-bench
cd frappe-bench

# Create new site
bench new-site fleet-ms.local

# Install ERPNext
bench get-app erpnext
bench --site fleet-ms.local install-app erpnext

# Install VSD Fleet MS
bench get-app vsd_fleet_ms
bench --site fleet-ms.local install-app vsd_fleet_ms

  4. Start Development Server 

    bench start

Code Style Guidelines

Python Code

  • Follow PEP 8 style guidelines
  • Use meaningful variable and function names
  • Add docstrings for all functions and classes
  • Keep functions focused and single-purpose
def create_vehicle_trip_from_manifest(manifest_name, transporter_type):
    """
    Create a vehicle trip from an existing manifest.

    Args:
        manifest_name (str): Name of the source manifest
        transporter_type (str): Type of transporter (In House/Sub-Contractor)

    Returns:
        dict: Created trip document data
    """
    # Implementation here

JavaScript Code

  • Use ES6+ features where appropriate
  • Follow consistent naming conventions
  • Add JSDoc comments for complex functions
  • Handle errors gracefully
/**
 * Assign cargo to manifest with validation
 * @param {string} cargoId - Cargo identifier
 * @param {string} manifestName - Target manifest name
 * @returns {Promise<Object>} Assignment result
 */
async function assignCargoToManifest(cargoId, manifestName) {
    try {
        // Implementation here
    } catch (error) {
        console.error('Assignment failed:', error);
        throw error;
    }
}

DocType Development

  • Use descriptive field names
  • Include proper validation rules
  • Add helpful field descriptions
  • Follow ERPNext naming conventions

📋 Contribution Process

1. Issue Reporting

Before starting work, check if an issue already exists: - Bug Reports: Include steps to reproduce, expected vs actual behavior - Feature Requests: Describe the use case and business value - Enhancement Ideas: Explain the improvement and benefits

2. Development Workflow

  1. Fork the repository on GitHub
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes following the coding guidelines
  4. Test thoroughly on your local environment
  5. Commit with clear, descriptive messages
  6. Push to your fork and create a Pull Request

3. Pull Request Guidelines

  • Clear Title: Describe the change concisely
  • Detailed Description: Explain what, why, and how
  • Screenshots: Include UI changes or new features
  • Testing: Describe how you tested the changes
  • Related Issues: Link to any related issues

4. Code Review Process

  • All contributions require review by maintainers
  • Address feedback and make requested changes
  • Ensure all tests pass
  • Update documentation as needed

🎯 Priority Areas

High Priority

  • Bug Fixes - Critical issues affecting system stability
  • Security Issues - Vulnerabilities and security concerns
  • Data Integrity - Issues affecting data accuracy and consistency
  • Performance - Significant performance improvements

Medium Priority

  • New Features - Valuable functionality additions
  • UI/UX Improvements - Better user experience
  • Integration Enhancements - Better ERPNext integration
  • Documentation - Improved guides and references

Low Priority

  • Nice-to-Have Features - Convenience and enhancement features
  • Code Refactoring - Code quality improvements
  • Additional Reports - New reporting capabilities
  • Localization - Multi-language support

🧪 Testing Guidelines

Unit Testing

  • Write tests for all new functions and methods
  • Maintain high test coverage
  • Test edge cases and error conditions
  • Use descriptive test names
def test_create_vehicle_trip_from_manifest():
    """Test vehicle trip creation from manifest"""
    # Setup test data
    manifest = create_test_manifest()

    # Execute function
    trip = create_vehicle_trip_from_manifest(manifest.name, "In House")

    # Assert results
    assert trip.manifest == manifest.name
    assert trip.transporter_type == "In House"

Integration Testing

  • Test complete workflows end-to-end
  • Verify ERPNext integration points
  • Test with real data scenarios
  • Validate financial calculations

User Acceptance Testing

  • Test from end-user perspective
  • Verify business process flows
  • Check data accuracy and consistency
  • Validate reporting outputs

📚 Documentation Standards

User Documentation

  • Write for the end-user, not developers
  • Use clear, simple language
  • Include step-by-step instructions
  • Add screenshots for complex processes
  • Provide examples and use cases

Technical Documentation

  • Document all public APIs and methods
  • Include code examples
  • Explain configuration options
  • Provide troubleshooting guides
  • Keep documentation up-to-date

API Documentation

  • Document all endpoints and parameters
  • Include request/response examples
  • Explain authentication and authorization
  • Provide error code explanations

🤝 Community Guidelines

Code of Conduct

  • Be respectful and inclusive
  • Welcome newcomers and help them contribute
  • Provide constructive feedback
  • Focus on the code and ideas, not the person

Communication

  • Use clear, professional language
  • Be patient with questions and clarifications
  • Share knowledge and help others learn
  • Celebrate contributions and successes

Collaboration

  • Work together to solve problems
  • Share ideas and suggestions
  • Help review and improve others' work
  • Build on existing contributions

🏆 Recognition

Contributor Recognition

  • Contributors List: All contributors are listed in the repository
  • Release Notes: Significant contributions are mentioned in releases
  • Documentation Credits: Contributors are credited in documentation
  • Community Spotlight: Featured contributors in community updates

Types of Contributions

  • Code Contributions: Bug fixes, features, improvements
  • Documentation: Guides, tutorials, API docs
  • Testing: Bug reports, testing, quality assurance
  • Community: Support, mentoring, evangelism

📞 Getting Help

Development Questions

  • GitHub Issues: For bug reports and feature requests
  • GitHub Discussions: For questions and community discussions
  • Email: nelsonnorbert87@gmail.com for direct support

Learning Resources

🚀 Quick Start for New Contributors

  1. Choose an Issue: Look for issues labeled "good first issue" or "help wanted"
  2. Set Up Environment: Follow the development setup instructions
  3. Make a Small Change: Start with a simple bug fix or documentation update
  4. Submit Your First PR: Follow the contribution process
  5. Get Feedback: Learn from code reviews and community feedback
  6. Keep Contributing: Build on your experience and tackle more complex issues
  1. Fix a typo in documentation
  2. Add a comment to unclear code
  3. Improve an error message
  4. Add a docstring to a function
  5. Fix the plural doctype naming (see Known Issues section)

📄 License

By contributing to VSD Fleet Management System, you agree that your contributions will be licensed under the same license as the project (GNU General Public License v3.0).

🙏 Acknowledgments

Original Development

  • VVSD-LTD - Original creators of the VSD Fleet Management System
  • SAP Research - Inspiration and best practices from SAP's fleet management solutions
  • ERPNext Community - Framework and ecosystem support

Community Contributions

  • Documentation - Comprehensive guides and technical references
  • Feature Enhancements - Customer-driven improvements
  • Testing & Feedback - Quality assurance and user experience improvements
**Ready to make a difference in fleet management?** [🚀 Start Contributing](https://github.com/nelsonmpanju/Fleet-Management-System) • [📖 View Issues](https://github.com/nelsonmpanju/Fleet-Management-System/issues) • [💬 Join Discussion](https://github.com/nelsonmpanju/Fleet-Management-System/discussions) **Forked from [VVSD-LTD/vsd_fleet_ms](https://github.com/VVSD-LTD/vsd_fleet_ms) with enhanced documentation and features**