# Contributing Guide

Thank you for your interest in contributing! We appreciate all pull requests (PRs), code reviews, bug reports, and feature ideas. To keep things smooth for everyone, please follow these guidelines.

---

## Table of Contents
1. [Getting Started](#getting-started)
2. [Code of Conduct](#code-of-conduct)
3. [How to Contribute](#how-to-contribute)
   - [Reporting Issues](#reporting-issues)
   - [Proposing Enhancements](#proposing-enhancements)
   - [Pull Requests](#pull-requests-prs)
4. [Commit Message Guidelines](#commit-message-guidelines)
5. [Pull Request Process](#pull-request-process)
6. [Maintainer Responsibilities](#maintainer-responsibilities)
7. [License](#license)

---

## Getting Started
1. **Fork the repository** and create your own branch.
2. **Clone your fork** to your local machine.
3. **Create** a new branch for each piece of work:
   ```bash
   git checkout -b feature/brief-description
   ```

## Code of Conduct
All contributors are expected to follow our [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Be respectful, inclusive, and open-minded.

## How to Contribute

### Reporting Issues
- Search the issue tracker to see if your issue has already been reported.
- If not, open a new issue and provide:
  - **Title**: Clear, concise.
  - **Description**: Steps to reproduce, expected vs. actual behavior.
  - **Environment**: OS, Java version, etc.
  - **Screenshots/Logs**: When applicable.

### Proposing Enhancements
- Check existing enhancement requests.
- Clearly outline:
  - Motivation and use case.
  - Proposed solution or approach.
  - Potential alternatives.

### Pull Requests (PRs)
> **Important:**  
> - **An issue _must_ exist before any PR is submitted.**  
> - **Every PR _must_ link to its corresponding issue in the description (e.g., “Closes #123”).**  
> - **All PRs _must_ be merged using a squash commit.**  

Steps:
1. Ensure your branch is up to date with `main`:
   ```bash
   git fetch origin
   git rebase origin/main
   ```
2. Commit your changes (see “Commit Message Guidelines” below).
3. Push your branch to your fork:
   ```bash
   git push -u origin feature/brief-description
   ```
4. Open a PR against `main`.
5. Fill out the PR template completely.

---

## Commit Message Guidelines
format: "`<type>`: `<message>`"

Allowed `<type>` values:
`feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `ci`, `chore`.

Example:
> fix: prevent NPE in OrderService when cart is null docs: add README section for Docker usage

---

## Pull Request Process

1. **Ensure the PR description links to its issue**  
   Use “Closes #<issue-number>” (or “Fixes”, “Resolves”).
2. Keep the PR focused—one logical change per PR.
3. Rebase onto the latest `main` before opening or updating the PR:
   ```bash
   git fetch origin
   git rebase origin/main
   ```
4. Push to your fork:
   ```bash
   git push -u origin feature/brief-description
   ```
5. Fill out every section of the PR template (tests, screenshots, etc.).
6. Address all review comments; push additional commits as needed.
7. **Merging strategy**  
   All PRs are merged using **“Squash and merge.”**  
   This keeps the main branch history linear and clean.
8. Once approved and all checks pass, a maintainer will squash-merge the PR.

---

## Maintainer Responsibilities

* Triage new issues and confirm validity.
* Review PRs in a timely manner.
* Ensure all CI checks pass before merging.
* Enforce the squash-merge rule.
* Keep the documentation and release notes up to date.

---

## License

By contributing, you agree that your work will be licensed under the same license as the project. See [LICENSE](LICENSE).

---

Thank you again for helping make this project better!