Start free

For AI agents: a documentation index is available at /llms.txt. A markdown version of this page is available at /guide/community/project/contributing.md.

CommunityProject

Contributing

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

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 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.

  1. Read CLA.md

    In the repository root.

  2. Add yourself to CONTRIBUTORS.md

    In your first pull request. That is the signature.

  3. 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.

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

#Making a change

  1. Branch

    bash
    git checkout -b fix/short-description

  2. Follow the surrounding code

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

  3. 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.

  4. Check the error log

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

    A clean log is part of "it works".

  5. 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

What the AGPL means for your contribution and your deployment.