Contributing

Use this guide to report bugs and contribute fixes to QUIQQER packages or Core. Check the affected repository's README and contribution guidelines for its supported versions, development branches and available checks.

Where To Contribute

GitLab is the primary development platform and the preferred place for issues and merge requests. Report a package bug in that package's repository. Use the Core issue tracker for Core bugs. Search existing reports before opening a new issue and link related reports.

You can also submit a pull request through the affected repository's GitHub mirror, such as QUIQQER/Core. Maintainers transfer accepted changes to GitLab; you do not need a GitLab account for this route. Commit, code style and test requirements are the same on both platforms. A change is integrated when its transfer to GitLab is complete.

Report A Bug

Give the issue a clear, concise title and include:

• QUIQQER version and the names and versions of affected packages.
• Relevant PHP, database, browser, operating system and server information.
• Exact reproduction steps and a minimal example or configuration.
• Expected behaviour and actual behaviour.
• Sanitized logs, stack traces, screenshots or sample files where useful.
• Known impact, regression, last working version, priority or workaround.

Remove credentials, tokens, personal data and customer data from all examples and attachments. Reduce the example until another developer can reproduce the problem without access to your private installation.

Answer follow-up questions and update the issue when you learn more. Maintainers manage labels and status. Issues awaiting the reporter's response are closed after three months without feedback.

Bug Report Template

Copy this template and replace the example details. The media preview scenario is an illustrative Core bug report.

## Summary

The media manager shows no preview for a transparent PNG.

## Versions and environment

- QUIQQER / Core: <version>
- Affected package(s): <name and version>
- PHP / database: <versions>
- Browser / operating system: <versions, if relevant>

## Steps to reproduce

1. Open the administration area and go to Media.
2. Upload the attached minimal example.png.
3. Open its details.

## Expected behaviour

The image preview is displayed.

## Actual behaviour

The details panel opens, but the preview remains blank.

## Additional context

- Minimal example or configuration: <attachment or steps>
- Regression / last working version: <if known>
- Impact / priority / workaround: <if known>
- Sanitized logs, screenshot or stack trace: <if available>

“Media is broken. Please fix quickly.” is not enough: it omits the affected version, reproduction steps and expected result.

Report A Security Vulnerability

Send security vulnerabilities privately to support@pcsg.de. Include affected versions, prerequisites, reproduction steps or a minimal proof of concept, and the possible impact. Remove sensitive data and send only what is needed to investigate.

Do not publish vulnerability details in a public issue, MR, PR or Discord channel. For example, unauthorized access to private files belongs in a private security report, rather than a public bug report.

Prepare A Bugfix

1. Check or create an issue and describe the intended fix. Agree larger changes with maintainers before implementing them.
2. Fork the affected repository and create a focused branch from the matching next-*.x development branch. Prefix its name with the GitLab issue number when available, for example 123-fix-media-preview.
3. Target that same development branch with the MR or PR. For Core 2.x, use next-2.x. Breaking changes belong on the next unreleased major branch, such as next-3.x while 2.x is stable; confirm the target with maintainers.
4. Reproduce the issue and fix its cause. Keep the change small and separate unrelated refactoring and formatting.
5. Preserve backwards compatibility. Describe intentional API changes, deprecations and required migrations.
6. Add or update regression tests, document manual test steps and update affected documentation and translations. Explain any automated test gap.

See Development Workflow for branch updates, reverts and the complete commit conventions.

Commit And Code Standards

Each commit must contain one complete, independently reversible work unit. Write the entire message in English with this header:

<type>[(<scope>)][!]: <short summary>

• Keep the complete header at most 72 characters long, without a final period.
• Start the summary with a lowercase letter and use the imperative present tense, for example fix, not fixed.
• Use build, ci, docs, feat, fix, perf, refactor, revert, style or test. The optional scope identifies an area such as media.
• Separate the header, optional body and optional footer with blank lines. Body and footer lines must not exceed 100 characters. Start the body with a capital letter and explain the motivation in the imperative present tense.
• Link related issues with Related: project/package#123. Use Closes: project/package#123 only when the issue should close on reaching the default or release branch. In GitHub PR descriptions, use the full GitLab issue URL to avoid ambiguous issue numbers.
• Breaking changes require ! before the colon and an explanatory BREAKING CHANGE: footer, including migration instructions where needed.

fix(media): restore preview for transparent PNG images

Use the original image when the thumbnail URL is missing.
Add a regression test for the preview metadata.

Related: quiqqer/core#123

build!: drop support for an obsolete dependency

BREAKING CHANGE: Remove support for old/package 1.x
Upgrade to old/package 2.x before updating.

GitLab server hooks can reject invalid commit messages or code style. Before accepting a GitHub PR, maintainers check every incoming commit, including the final merge or squash message. The later import does not repair messages.

Follow Coding Standards: PHP uses PSR-12; JavaScript uses the QUIQQER JSHint rules or the package's .jshintrc. Follow existing conventions for CSS, templates and translations. Escape output for its context, bind query parameters and consider permissions and data handling.

Run Checks

Use a working QUIQQER development installation and the tools provided by the affected package. Check its README, Composer scripts and CI configuration. See Developer Setup and Testing and Quality for setup and test details.

For Core, run these commands from packages/quiqqer/core. Composer, PHIVE and the PHP version and extensions required by composer.json must be available:

composer dev:init
composer test

Run composer dev:init when setting up the checkout; it installs pinned tools and enabled Git hooks. Run composer test before handing over changes. Core also provides individual checks:

composer dev:lint
composer dev:phpunit
./tools/phpcs
./tools/phpstan
./tools/phpunit

Record commands, results and checks you could not run. Add regression coverage for the fix and document manual verification, including relevant browser-console checks for UI changes. Maintainers consider CI results and review before integrating the change.

Describe The Merge Request Or Pull Request

Keep one problem per MR or PR. Link the issue and explain the problem, cause, solution, affected packages, tests and compatibility implications. Replace the example issue URL in this copyable template:

## Problem and affected packages

<What fails, who is affected, and which packages change?>

## Related issue

https://dev.quiqqer.com/quiqqer/core/-/issues/123

## Root cause

<Why does the problem occur?>

## Solution

<How does this change address the cause?>

## Tests

- Automated: <command, regression covered and result>
- Manual: <steps, environment and result>
- Limitations: <checks not run and why, or none>

## Compatibility and documentation

<API, permissions, dependencies, translations, release notes or migration needs>

Contributor Checklist

• [ ] The issue is linked and the correct development branch is targeted.
• [ ] The change fixes one problem; unrelated refactoring and formatting are separate.
• [ ] Commits are atomic and all commit messages follow the standard.
• [ ] Reproduction was verified and regression coverage was added or updated, or the gap is explained.
• [ ] Relevant style, static analysis and test checks passed; results and limitations are recorded.
• [ ] Manual test steps and results are documented.
• [ ] Compatibility, permissions, sensitive data and public API changes were considered.
• [ ] Documentation, translations and release or migration notes are updated where needed.

Reviewer Checklist

• [ ] The issue provides enough information to reproduce the problem.
• [ ] The fix addresses the cause and is small enough to review.
• [ ] Tests cover the regression and relevant checks have passed.
• [ ] Compatibility, security, permissions and data handling were reviewed.
• [ ] The target branch and all commit messages are valid, including GitHub merge or squash commits before import.

Releases And Repository Guides

Maintainers manage protected branches, versioning, tags and publication. Contributors submit tested changes to the matching development branch. Describe user-visible changes, deprecations and migration needs in the MR or PR, and add documentation or changelog notes where the repository requires them. Maintainers prepare the release and merge into main or the appropriate maintenance branch; release automation uses commit messages to determine versions and release notes.

The Core contribution guide also links translations for the seven Core languages. Follow the affected repository's own guide when contributing to another package.