# Contributing to ADconsole

Thanks for helping out. This is a small, focused project — a web UI for everyday
Active Directory administration. Contributions that keep it small and sharp are
very welcome.

## Before you start

- Read [`CLAUDE/AGENTS.md`](CLAUDE/AGENTS.md) (the architecture in one page) and
  [`docs/architecture.md`](docs/architecture.md).
- By participating you agree to the [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).
- For anything non-trivial, open an issue first so we can agree on the approach.

## Ground rules

1. **No SQL storage for AD objects.** All directory reads/writes go through
   LdapRecord. The database is for app infrastructure and `panel_settings` only.
2. **Every user-facing string is a translation key** in *both*
   `lang/pl/*` and `lang/en/*`. No inline copy.
3. **Keep it dependency-light.** No new runtime Composer/npm package without a
   clear reason in the issue.
4. **Least privilege.** New AD operations must be documented in
   [`docs/active-directory.md`](docs/active-directory.md) with the exact right
   they require.
5. **Security-sensitive by nature** — think about what a hostile panel user or a
   compromised service account could do with your change.

## Dev loop

```sh
composer install
cp .env.example .env && php artisan key:generate
php artisan migrate
php artisan test
vendor/bin/pint
```

See [`docs/development.md`](docs/development.md) for the details (SQLite for dev,
the fake `ldap` guard in tests, the harmless `DEPR` tag, etc.).

## Pull requests

- Branch from `main`; keep the PR focused on one thing.
- Include tests for logic changes. Feature tests may seed caches / fake the
  guard rather than hitting a real DC (see `tests/Feature/DashboardTest.php`).
- Run `php artisan test` and `vendor/bin/pint --test` — both must be green
  (`DEPR` in the test summary is fine; `failed` is not).
- Update the relevant `docs/` page and add a `CHANGELOG.md` entry under
  *Unreleased*.
- Describe the change, the motivation, and any AD permission / migration impact
  in the PR body.

## Reporting bugs

Open an issue with: ADconsole version / commit, PHP version, how it's deployed
(Docker / bare metal), the exact error (with `APP_DEBUG=true` and the relevant
`storage/logs/laravel.log` lines — **redact DNs, hostnames and account names**),
and steps to reproduce.

## Security issues

**Do not** open a public issue — see [`SECURITY.md`](SECURITY.md).

## Licence

By contributing you agree your work is released under the project's
[MIT Licence](LICENSE).