Contribute

Rules

GreedyBear welcomes contributors from anywhere and from any kind of education or skill level. We strive to create a community of developers that is welcoming, friendly and right.

For this reason it is important to follow some easy rules based on a simple but important concept: Respect.

• Before starting to work on an issue, you need to get the approval of one of the maintainers. Therefore please ask to be assigned to an issue. If you do not do that but you still raise a PR for that issue, your PR can be rejected. This is a form of respect for both the maintainers and the other contributors who could have already started to work on the same problem.

• When you ask to be assigned to an issue, it means that you are ready to work on it. When you get assigned, take the lock and then you disappear, you are not respecting the maintainers and the other contributors who could be able to work on that. So, after having been assigned, you have a week of time to deliver your first draft PR. After that time has passed without any notice, you will be unassigned.

• Before asking questions regarding how the project works, please read through all the documentation and install the project on your own local machine to try it and understand how it basically works. This is a form of respect to the maintainers.

• Once you started working on an issue and you have some work to share and discuss with us, please raise a draft PR early with incomplete changes. This way you can continue working on the same and we can track your progress and actively review and help. This is a form of respect to you and to the maintainers.

• When creating a PR, please read through the sections that you will find in the PR template and compile it appropriately. If you do not, your PR can be rejected. This is a form of respect to the maintainers.

• Use AI tools appropriately. If we find that you abuse those tools and you just copy/paste without even checking what you are pushing in a PR, we will automatically reject your PR and your future PRs. This is a form of respect to the maintainers.

Setup

To start with the development setup, make sure you go through all the steps in Installation Guide and properly installed it.

If you don't have a T-Pot, you can make GreedyBear spin up its own local ElasticSearch instance. (Note: This option would require enough RAM to run the additional containers. Suggested is >=16GB).

# Development with local Elasticsearch
./gbctl init --dev --elastic-local

Please create a new branch based on the develop branch that contains the most recent changes. This is mandatory.

git checkout -b myfeature develop

Build and start the containers.

# Build Docker image locally
./gbctl build
# Start the containers
./gbctl up

In the --dev setup, the repository is mounted into the app container and Django runs via manage.py runserver, so Python changes hot-reload automatically — no rebuild needed. You only need to rebuild the docker image when you change dependencies (e.g. requirements.txt) or the Dockerfile itself.

Backend

Development

Install the python project manager uv.

Then we strongly suggest to configure pre-commit to force linters on every commit you perform:

# from the project base directory
uvx pre-commit install -c .github/.pre-commit-config.yaml

Once configured, Ruff will automatically run on every commit (see Code style below).

Code style

Keeping to a consistent code style throughout the project makes it easier to contribute and collaborate. We use Ruff as our all-in-one linter and formatter, which provides:

• Code Formatting: Replaces black with fast, compatible formatting
• Import Sorting: Replaces isort with automatic import organization
• Linting: Replaces flake8 with 100+ rule sets including:
  • pycodestyle (E/W) - PEP 8 style enforcement
  • pep8-naming (N) - Naming convention checks
  • pyupgrade (UP) - Modern Python syntax suggestions
  • flake8-bugbear (B) - Common bug detection
  • flake8-comprehensions (C4) - List/dict comprehension improvements
  • flake8-django (DJ) - Django-specific best practices
  • any many more...

If you want to manually run Ruff before committing, you can use:

uvx ruff check .           # Check for linting issues
uvx ruff check . --fix     # Auto-fix issues
uvx ruff format .          # Format code

Tests

Just run:

docker exec greedybear_app python3 manage.py test

Frontend

Development

The frontend is tested in CI against Node.js 24 — we recommend using the same version locally to avoid surprises.

To start the frontend in "develop" mode, you can execute the startup npm script within the folder frontend:

cd frontend/
# Install
npm i
# Install config dependencies for linter 
npm run lint-config-install
# Start
npm start

If you get "Invalid Host header" errors when proxying API requests, set server.allowedHosts in vite.config.js.

Most of the time you would need to test the changes you made together with the backend. In that case, you would need to run the backend locally too:

./gbctl up

gb-ui

The GreedyBear Frontend is tightly linked to gb-ui — our fork of certego-ui. Most of the React components are imported from there. The dependency is installed directly from GitHub at a pinned git tag (see @greedybear/gb-ui in frontend/package.json); it is not published to npm.

Because of this, it may happen that, during development, you would need to work on that library too. To install gb-ui for local development, please take a look at npm link and remember to start it without installing peer dependencies (to avoid conflicts with GreedyBear dependencies):

git clone https://github.com/GreedyBear-Project/gb-ui.git
# change directory to the folder where you have cloned the library
cd gb-ui/
# install, without peer deps (to use packages of GreedyBear)
npm i --legacy-peer-deps
# create link to the project (this will globally install this package)
sudo npm link
# compile the library
npm start

Then, open another command line tab, create a link in the frontend to gb-ui and re-install and re-start the frontend application (see previous section):

cd frontend/
npm link @greedybear/gb-ui

This trick will allow you to see reflected every change you make in gb-ui directly in the running frontend application.

Example application

The gb-ui repo comes with an example project that showcases the components that you can re-use and import to other projects, like GreedyBear:

# To have the Example application working correctly, be sure to have installed `gb-ui` *without* the `--legacy-peer-deps` option and having it started in another command line
cd gb-ui/
npm i
npm start
# go to another tab
cd gb-ui/example/
npm i
npm start

Tests

All the frontend tests must be run from the folder frontend.

Tests run with Vitest. Note that npm test starts in watch mode by default; pass -- run (or invoke npx vitest run) for a single non-interactive run, e.g. in CI.

Run all tests

npm test

Run a specific component tests

npm test <componentPath>
# example
npm test tests/components/auth/Login.test.jsx

Run a specific test

npm test -- -t '<describeString> <testString>'
# example
npm test -- -t "Login component User login"

Creating a pull request

Before opening the PR

• Your branch must be based on develop, and the PR must target develop — the main branch only receives code on release.
• Merge the latest changes from develop into your branch first. PRs with merge conflicts will not be accepted.
• Make sure backend and frontend tests pass (see Backend → Tests and Frontend → Tests).
• If you skipped the pre-commit setup, run Ruff manually so the linter check passes in CI.
• If your changes affect user-facing behavior documented in this wiki, prepare the wiki update and mention it in the PR description.
• For GUI changes, attach a screenshot and add or update frontend tests.

Opening the PR

• Use the title format: <feature name>. Closes #999.
• Fill in every section of the PR template — description, related issues, type-of-change, and the checklist. PRs that skip the template will be rejected.
• Write the description yourself; do not just paste raw LLM output. If you used an LLM to generate code, review and verify it before pushing.
• We encourage opening the PR as a draft while you are still iterating, so we can track progress and review early. Mark it ready for review when you are done.

Review

• When the work is ready, click "Ready for review" (if your PR is a draft), or otherwise request a review explicitly.
• For each round of changes, address the feedback and click "Re-request review" next to the reviewer's avatar at the top right.