# Contributing to FlowDrop

Thank you for your interest in contributing to FlowDrop! This document provides
guidelines and information for contributors.

## Code of Conduct

This project follows the [Drupal Code of Conduct](https://www.drupal.org/dcoc).
By participating, you are expected to uphold this code.

## How to Contribute

### Reporting Bugs

- Search the [issue queue](https://www.drupal.org/project/issues/flowdrop) first
  to avoid duplicates.
- When filing a bug report, include:
  - Drupal and PHP version
  - Steps to reproduce
  - Expected vs. actual behavior
  - Error messages or logs

### Suggesting Features

- Open a feature request in the
  [issue queue](https://www.drupal.org/project/issues/flowdrop).
- Describe the use case and why it would benefit the project.

### Submitting Patches

1. **Fork** the repository on [git.drupalcode.org](https://git.drupalcode.org/project/flowdrop).
2. **Create a branch** from the `1.x` branch for your change.
3. **Follow the coding standards** described below.
4. **Write or update tests** for your change.
5. **Submit a merge request** referencing the related issue.

## Development Setup

See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed instructions on setting up a
local development environment with DDEV.

## Coding Standards

### PHP

- Follow [Drupal coding standards](https://www.drupal.org/docs/develop/standards).
- All files must declare `declare(strict_types=1)`.
- Use PHP 8 constructor property promotion where appropriate.
- Run `ddev phpcs` to check coding standards compliance.
- Run `ddev phpstan` to verify static analysis passes (level 5).
- Run `ddev phpunit` to verify tests pass.

### JavaScript / TypeScript

- Run `npm run lint` from `modules/flowdrop_ui_components/lib/flowdrop/`.
- Run `npm run format` to auto-format with Prettier.

### Commit Messages

- Use imperative mood ("Add feature" not "Added feature").
- Reference the Drupal.org issue number (e.g., "Issue #1234567: Add feature").
- Keep the subject line under 72 characters.

## API Stability

FlowDrop follows [semantic versioning](https://semver.org/). Before contributing,
review the [backward compatibility policy](docs/reference/api/bc-policy.md) to
understand which parts of the codebase have stability guarantees:

- **`@api`** — Stable public API. Changes require a major version bump.
- **`@internal`** — No backward compatibility promise.

When adding new classes or interfaces:

- Mark extension points intended for external use with `@api`.
- Mark implementation details with `@internal`.

## Testing

### Running Tests

```bash
# PHP unit tests
ddev phpunit

# Code standards
ddev phpcs

# Static analysis
ddev phpstan
```

### Writing Tests

- Place unit tests in `tests/src/Unit/`.
- Place kernel tests in `tests/src/Kernel/`.
- Place functional tests in `tests/src/Functional/`.
- See existing tests in `modules/*/tests/` for examples.

## Project Structure

See [AGENTS.md](AGENTS.md) for a detailed overview of the project architecture,
key services, and common patterns.

## Questions?

- Open an issue in the [issue queue](https://www.drupal.org/project/issues/flowdrop).
- Check the [documentation](docs/) for guides and reference material.
