# 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/](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/](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/](../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](SECURITY.md) for full details.

## Questions?

- Check existing [documentation](01_Knowledge_Base/)
- Review [SECURITY.md](SECURITY.md) and [LICENSES.md](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