Jason Thistlethwaite
80 lines
3.6 KiB
Markdown
80 lines
3.6 KiB
Markdown
# 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.
|
|
`validate_test_instance.py` performs read-only post-import checks, and
|
|
`validate_helpdesk_outbox_worker.py` runs the controlled Helpdesk/outbox live
|
|
validator. 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 validate_test_instance.py helpdesk_smoke_test.py validate_helpdesk_outbox_worker.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
|
|
./validate_test_instance.py
|
|
./helpdesk_smoke_test.py
|
|
./validate_helpdesk_outbox_worker.py
|
|
./redmine_outbox_worker.py --status
|
|
./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. The post-import workflow lives in
|
|
`docs/test_instance_post_import.md`; the Helpdesk/redMCP live smoke test is
|
|
documented in `docs/helpdesk_smoke_test.md`; the Helpdesk outbox worker
|
|
validator is documented in `docs/helpdesk_outbox_worker_validation.md`; worker
|
|
processing policy is documented in `docs/outbox_worker_policy.md`.
|
|
|
|
## 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.
|