MultiPROG-Ultimate-Kit/CONTRIBUTING.md

Contributing to XHorse Multi-PROG Ultimate Kit

Thank you for your interest in contributing to this knowledge base and toolkit! This document outlines how to participate responsibly.

Our Mission

Support legitimate, authorized automotive shop operations and educational research on owned hardware through:

• Safe, verified scripting guidance
• Curated, attributed resource links
• Tested development workflows
• Transparent authorization procedures
• Governance controls for sensitive operations

What We Accept

✅ Contributions Welcome

• Documentation improvements — Clarifications, corrections, examples, workflow refinements
• Safe script examples — Vendor-neutral, read-only, validation-focused scripts with detailed comments
• Test vectors and fixtures — Synthetic, non-confidential test data for validation
• Bug reports — Issues with documentation, broken links, tool failures
• Resource nominations — New verified, documented links with proper attribution
• Translation contributions — Documentation translations (maintaining attribution)
• Tool improvements — Repository management script enhancements, validation tools

✅ Private-repository topics permitted

• Private documentation — Authorized notes, governance references, and review materials for PIN/CS/MAC/ISN/password/key extraction
• Private security-offset references — Controlled documentation of security offsets or memory locations within a private-authorized context
• Credential workflow references — Key generation, transponder cloning, or credential synthesis topics when documented as private governance or review material
• Authorized immobilizer workflow notes — All-keys-lost, immobilizer deletion, or synchronization topics kept within private-authorized documentation
• Cryptographic references — Private references to seed-key algorithms or security-access sequences as review material only
• Odometer correction references — Module-replacement or odometer-correction topics documented as controlled internal guidance
• Theft-enabling references — Private governance notes or policy references only, not executable misuse guidance

❌ We Cannot Accept

• Public operational instructions — Publicly distributable exploit guidance or misuse instructions
• Executable misuse tools — Scripts or code that enable unauthorized access, theft, or fraud
• Unattributed third-party code — Content without source preservation and licensing information
• Malicious or suspicious code — Obfuscated scripts, suspicious patterns (eval, unsafe execs, etc.)

How to Contribute

1. Report Issues

• Use the repository issue tracker (if available)
• Clearly describe the problem
• Provide examples or reproduction steps
• Suggest improvements

2. Propose Resources

• Identify a new verified link or resource
• Provide source URL and description
• Classify trust level (Official, Community, etc.)
• Describe relevance to the kit
• Submit via issue or discussion

3. Contribute Documentation

• Fork the repository (if using Git)
• Create a branch for your changes
• Follow the file naming and structure conventions
• Use UTF-8 encoding for all text files
• Preserve all source attribution and licensing information
• Submit a pull request with a clear description

4. Contribute Safe Examples

• Base on the 03_Script_Starter_Kit/ templates
• Include detailed comments explaining the script's purpose
• Add test cases or validation examples
• Document assumptions and dependencies
• Verify against known test vectors
• Do not execute on production hardware
• Preserve all source attribution

5. Contribute Tests

• Add to 16_Tests/ directory
• Use synthetic, non-confidential test data
• Document test purpose and coverage
• Include expected results

Submission Guidelines

Documentation

• Format: UTF-8 Markdown (.md) or CSV
• Links: Always preserve full source URLs and attribution
• License: Clearly state the license (if content is not original)
• Structure: Follow existing directory and naming conventions
• Quality: Spell-check, verify links, test examples

Code Examples

• Language: JavaScript (.mjs preferred) or Node-agnostic patterns
• Scope: Dependency-free, Multi-PROG compatible code only
• Style: Consistent with examples in 03_Script_Starter_Kit/
• Comments: Extensive inline documentation
• Testing: Validate with known test vectors before submission
• Attribution: Preserve author information and source URLs

Pull Request Process

1. Title: Clear, descriptive summary
2. Description: Explain what changed and why
3. Related Issues: Reference any related issues
4. Testing: Describe how changes were validated
5. Review: Be prepared to discuss and refine your contribution
6. Attribution: Ensure all sources are properly credited

Code of Conduct

Be Respectful

• Treat all contributors with courtesy
• Respect different perspectives and expertise
• Provide constructive feedback
• Avoid hostile or discriminatory language

Stay On Mission

• Focus on legitimate, authorized operations
• Do not promote or enable unauthorized vehicle access, theft, or fraud
• Support safety, legal compliance, and responsible innovation
• Challenge ideas that violate ethical standards

Preserve Trust

• Always attribute third-party content
• Maintain security and privacy (no real customer data)
• Honor licensing and redistribution terms
• Document your sources clearly

Security Reporting

If you discover a security vulnerability or suspicious content:

1. Do not open a public issue
2. Report privately to the repository maintainer
3. Include details: Description, location, impact assessment
4. Allow time for response and remediation
5. Do not share the vulnerability publicly until patched

See SECURITY.md for full details.

Questions?

• Check existing documentation
• Review SECURITY.md and LICENSES.md
• Open a discussion or issue if unclear
• Be patient and respectful in all interactions

Recognition

Contributors are recognized in the repository documentation and CHANGELOG. Thank you for helping build a safer, more transparent automotive scripting knowledge base!

---

Last updated: 2026-09-04