# Contributing

> How to propose changes, the CLA requirement, and the local development setup.

> For the complete documentation index, see [llms.txt](https://helpdesk.orangescrum.com/llms.txt).

Source: https://helpdesk.orangescrum.com/guide/community/project/contributing

---
Contributions are welcome. Two things are worth knowing before you start: open
an issue first for anything non-trivial, and you will need to sign the CLA.

## Open an issue first

For anything beyond a small fix, **discuss it before you build it**. It avoids
someone spending a weekend on a change that does not fit the project's
direction — which, for a deliberately minimal edition, is a real risk. The
Community Edition's scope is intentionally narrow, and features removed on
purpose will not be accepted back.

> **Scope is a design decision, not an oversight**
>
> Agile boards, Gantt, reporting and integrations were removed deliberately.
> See [What's included](https://helpdesk.orangescrum.com/guide/community/get-started/whats-included) before
> proposing one of them.

## The CLA

Before your first contribution can be merged, you must sign the
**Contributor License Agreement**.

Why it exists: Andolasoft Inc. distributes a commercially licensed edition that
shares this codebase, and needs permission to use contributions in both.
**You keep the copyright to your work** — the CLA grants a licence, it does not
transfer ownership.

**Read CLA.md**

    In the repository root.

**Add yourself to CONTRIBUTORS.md**

    In your first pull request. That is the signature.

**Corporate contributors**

    If you are contributing as part of your employment, your employer may need
    to sign a Corporate CLA. Check with them — this catches people out after the
    work is done.

## Development setup

```bash
git clone https://github.com/Orangescrum/orangescrum.git
cd orangescrum
docker compose up -d --build
```

The app comes up on **http://localhost:8091** with the install wizard. Full
detail in [Install with Docker](https://helpdesk.orangescrum.com/guide/community/install/docker).

**Stack:** CakePHP 4.6 on PHP 8.2+, PostgreSQL 16, Docker.

## Making a change

**Branch**

```bash
git checkout -b fix/short-description
```

**Follow the surrounding code**

    Match the conventions of the files you are editing rather than importing
    your own style. CakePHP conventions apply.

**Test it**

```bash
docker compose exec orangescrum-app vendor/bin/phpunit
```

    Add tests for behaviour you change. A bug fix without a regression test
    invites the bug back.

**Check the error log**

```bash
docker compose exec orangescrum-app tail -50 logs/error.log
```

    A clean log is part of "it works".

**Open a pull request**

    Explain what changed and why. Link the issue. Mention anything you
    deliberately did not do.

## What makes a PR easy to merge

- **One thing at a time**: A focused diff gets reviewed. A 40-file refactor sits.

- **Explain the why**: The code shows what changed; the description should say why.

- **Tests included**: Especially for bug fixes.

- **No unrelated reformatting**: Whitespace churn hides the real change.

## Good first contributions

- Bug fixes with a clear reproduction
- Documentation corrections
- Accessibility improvements
- Localisation
- Test coverage for existing behaviour

## Reporting bugs

Include what you did, what happened, what you expected, the relevant
`logs/error.log` lines, your version from `VERSION.txt`, your PHP version, and
whether it reproduces on a fresh install.

- [Licence](https://helpdesk.orangescrum.com/guide/community/project/licence): What the AGPL means for your contribution and your deployment.