# Repository Guidelines

## Project Structure & Module Organization

This repository tracks tooling and local plugin forks for a legacy Redmine 3.4.4
environment. The canonical plugin sources live in `plugins/`:

- `plugins/redmine_event_outbox/` - local event outbox plugin.
- `plugins/redmine_contacts/` - patched RedmineUP Contacts fork.
- `plugins/redmine_contacts_helpdesk/` - patched RedmineUP Helpdesk fork.

Top-level Python helpers such as `redmine_outbox_worker.py` and
`reset_helpdesk_mail_settings.py` support LAN test-instance operations. Project
notes and design records live in `docs/`. `redMCP/` contains the PHP
Redmine API/MCP wrapper. `dist/*.MANIFEST.md` files are tracked; rollback
tarballs are intentionally ignored. `redmine-copy/` is an ignored
working/reference copy, not the source of truth.

## Build, Test, and Development Commands

Use targeted syntax checks before committing:

```sh
ruby -c plugins/redmine_contacts/lib/redmine_contacts/utils/check_mail.rb
ruby -c plugins/redmine_contacts_helpdesk/app/models/helpdesk_mailer.rb
ruby -c plugins/redmine_event_outbox/lib/redmine_event_outbox.rb
python3 -m py_compile redmine_outbox_worker.py reset_helpdesk_mail_settings.py
cd redMCP && php -l app/RedmineClient.php && composer validate
```

Dry-run operational helpers before applying changes:

```sh
./reset_helpdesk_mail_settings.py --dry-run
./redmine_outbox_worker.py --dry-run --batch-size 10
```

## Coding Style & Naming Conventions

Follow the surrounding legacy style. Ruby plugin code uses two-space indentation
and old Rails 4/Redmine 3 idioms. Python helpers use standard library modules,
type hints where useful, and `snake_case` names. Keep shell-facing scripts
executable and avoid printing secrets such as API keys or mail passwords.

## Testing Guidelines

Prefer focused checks over broad legacy test runs unless changing shared plugin
behavior. For mail or database helpers, validate with dry runs first, then test
against the LAN Redmine copy using controlled projects such as `fud-helpdesk` or
`fud-nohelpdesk`. Record notable manual validation in `docs/` when behavior or
deployment assumptions change.

## Commit & Pull Request Guidelines

The current history uses concise, imperative commit subjects, for example:
`Initial Redmine tooling and local plugin forks`. Keep commits focused and
describe the operational impact in the body when touching deployed plugin code.

Pull requests should include a short summary, affected plugin/helper paths,
commands run, and any LAN test result. Mention if `redmine-copy/` or the test
host was updated outside the tracked `plugins/` source.

## Security & Configuration Tips

Do not commit `.env`, cache files, database exports, rollback tarballs, or the
full `redmine-copy/` tree. Do not commit `redMCP/vendor/` or `composer.phar`.
Treat Redmine API keys, SSH keys, mail passwords, and production-derived data as
sensitive. Use `plugins/` for plugin source changes and `redMCP/` for API/MCP
wrapper work.