# Contributing to LibRaw

Thank you for your interest in contributing to LibRaw. To ensure a smooth review process and maintain library stability, please read this entire document before submitting patches, issues, or bug reports.

---

## Repository & Development Workflow

LibRaw public repository is hosted on GitHub:
* **Main Project Page**: [LibRaw GitHub Repository](https://github.com/LibRaw/LibRaw)
* **Clone URL**: `https://github.com/LibRaw/LibRaw.git`
  ```bash
  git clone https://github.com/LibRaw/LibRaw.git
  ```

To participate in development:
1. **Fork** the repository to your personal account.
2. **Commit** changes to a feature branch on your fork.
3. Submit a **Pull Request (PR)** against our `master` branch.

---

## Licensing Compliance & Agreements

LibRaw is free, open-source software that is dual-licensed under:
1. **GNU Lesser General Public License (LGPL) version 2.1** | View the [LibRaw LICENSE.LGPL File](https://raw.githubusercontent.com/LibRaw/LibRaw/refs/heads/master/LICENSE.LGPL)
2. **Common Development and Distribution License (CDDL) Version 1.0** | View the [LibRaw LICENSE.CDDL File](https://raw.githubusercontent.com/LibRaw/LibRaw/refs/heads/master/LICENSE.CDDL)

### Mandatory Agreement
By submitting a patch or Pull Request, you explicitly agree that your contributed code can be distributed under **both** of the above licenses. Patches without this compliance cannot be merged into the official source tree.

---

## Code Contribution Requirements

### 1. New Camera Support
Supporting a camera requires exhaustive implementation, not just verification against a couple of sample images. In order for us to accept a patch, it must provide complete integration:
* **Variant Coverage**: All raw file formats, crop configurations, aspect ratios, and compression type variants for the camera must be supported (or cleanly fall back with correct error codes).
* **Metadata Extraction**: All necessary metadata extracted for a given camera type must be extracted.
* **Special Modes**: Proper processing of all vendor-specific burst types, multi-frame aggregates, and specialized raw outputs (e.g., Canon Dual Pixel, Olympus High-Res) must be ensured.

*Note 1: You must be prepared to provide a comprehensive reference set of raw files spanning all resolutions and modes, or wait until the community provides them for verification.*
*Note 2: We do not provide consultations on "what exactly is unfinished"; an incomplete patch may be rejected without detailed explanations.*

### 2. New Camera Format Support
Completely new standalone formats are rare. The criteria for accepting experimental format patches are initially less rigid, but contributors must remain committed to actively refining their implementation as new variant samples emerge.

---

## Bug Reports & Problem Analysis

Please use GitHub Issues strictly for actionable bug tracking, not for usage questions.

### Minimal Reproducible Example (MRE)
Every issue report must contain a minimal proof-of-concept:
* **Tool Isolation**: Demonstrate the issue using the core examples bundled with the library (such as `samples/dcraw_emu` or `samples/simple_dcraw`) alongside the required command-line switches. If the problem isn't apparent in the LibRaw examples, please provide the MINIMUM code that illustrates it.
* **Input Files**: Provide the physical, unprocessed RAW file triggering the bug. Do not substitute raw files with Dockerfiles, build environments, or external execution wrappers (e.g., Python wrappers).
* **Validation**: If a maintainer resolves your issue with a patch link, you are expected to test the fix and confirm it resolves your problem. Failure to follow up may result in future tickets being ignored.

### AI-Generated & Automated Bug Reports
Automated AI code reviews, generic static analyzers, and raw LLM triage outputs will be **closed immediately** unless accompanied by a verified, real-world exploit or physical RAW file causing a system crash. 

* **The Code Audit/Dump Ban**: Do not attach bulk HTML, PDF, or text reports generated by automated scanning suites or code auditing software to a GitHub issue. Submitting a list of theoretical vulnerabilities out of execution context does not qualify as an actionable bug report.
* **Physical Proof Requirement**: We do not accept theoretical simulations or synthetic test drivers running isolated logic loops. To validate a security report, you must provide a real, physical RAW container that illustrates the problem reported via our bundled sample programs.
* **Triage Policy**: Automated or simulated report elements must be manually reviewed. We will stop processing and close your entire issue at the very first false positive or overstated claim encountered.



### Guidelines for Using AI Assistance
* You may use AI utilities to assist in writing your code contributions.
* You **must** explicitly disclose any AI usage within the text of your Pull Request or patch notes.
* The human contributor retains full engineering responsibility for the changes. You must understand the core logic completely and be ready to defend the architecture during review. Citing *"the AI said so"* is not an acceptable response.

---

## Technical Maintenance Notes

### Creating a Distribution Tarball
Production packages match the structure compiled via our automation scripts. To build a standard distribution archive, execute:
```bash
./mkdist.sh
```
This utility automatically configures the autotools environments, builds the `./configure` script, and strips internal developer Makefiles alongside the distribution script itself.

---

## Contacts & Support

For general troubleshooting, usage questions, or broader project feedback, please reach out to us through:
* **Community Resources**: the official [LibRaw Forums](https://libraw.org) or contact forms on the primary website.
* **Direct Email Contact**: iquiries can also be forwarded directly to [info@libraw.org](mailto:info@libraw.org).

