Development Workflow

QUIQQER repositories use small, reviewable changes and standardized commit messages so releases and changelogs can be generated automatically.

Atomic Commits

A commit should contain one complete work unit. The change should be reversible without removing unrelated work.

Good commits:

• add one feature
• fix one bug
• improve one isolated code-style issue
• update one dependency set
• add tests for one behavior

Avoid mixing unrelated work in the same commit. For example, do not add a feature and reformat unrelated code in one commit. Use separate commits instead.

Commit Message Format

Commit messages must follow the Conventional Commits format:

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

Examples:

feat: add sitemap import

fix(cache): prevent stale page output

build!: bump minimum PHP version to 8.1

The header must:

• be written in English
• be at most 72 characters long
• not end with a period
• use an imperative, present-tense summary
• start the summary with a lowercase letter

Commit Types

Use one of these commit types:

Type	Use
build	Build process, dependencies, package metadata, tooling inputs.
ci	CI configuration and CI scripts.
docs	Documentation changes.
feat	New feature or user-facing capability.
fix	Bug fix or correction of unwanted behavior.
perf	Performance improvement.
refactor	Code change that is neither a bug fix nor a feature.
revert	Revert another commit.
style	Code style-only change without behavior or structure change.
test	Tests and test fixtures.

Use a scope when it makes the affected area clearer:

fix(locale): handle missing translation fallback

Breaking Changes

Mark breaking changes with ! in the header and add a BREAKING CHANGE footer.

build!: bump minimum PHP version to 8.1

BREAKING CHANGE: Drop support for PHP 7.4

Use breaking commits when existing installations or package users must change their code, configuration, dependencies, or runtime environment.

Body And Footer

Use a body when the change needs context.

fix: prevent duplicate import jobs

Store the import hash before queueing the job.
Reject another job with the same hash while the first job is pending.

Use footers for ticket references and release metadata:

Related: quiqqer/package#123
Closes: quiqqer/package#124
Acked-by: Jane Doe <jane@example.com>

Use Related when the commit is connected to an issue. Use Closes when the issue should be closed when the commit reaches the release branch.

Commit Linting

QUIQQER repositories can reject pushes when commit messages do not follow the standard. Fix the commit message before pushing again.

For an unpublished last commit:

git commit --amend

If a commit has already been pushed, avoid rewriting shared history unless the team explicitly agrees. Use a follow-up commit when appropriate.

Keeping History Clean

Use rebase when updating your local branch from the remote branch:

git pull --rebase

This avoids unnecessary merge commits in feature branches.

Use git revert when a pushed commit must be undone:

git revert <commit-hash>
git push

Use git fetch --prune to remove local references to remote branches that no longer exist:

git fetch --prune

Requesting A Version

Developers do not publish versions directly. Version creation is handled by maintainers through protected branches and automated release tooling.

Developer workflow:

• Work in the development branch used by the repository.
• Create atomic commits with valid commit messages.
• Run the available PHPCS, PHPStan, and test commands before handing work over.
• Open a merge request into the next branch.
• Let maintainers review, test, and merge into the release branch.

Version type is inferred from commit messages:

• fix creates a patch release.
• feat creates a minor release.
• ! or BREAKING CHANGE creates a major release.

Maintainer Release Documentation

Release publishing, protected branch handling, repository stabilization, semantic-release setup, and troubleshooting are maintainer tasks. They are not part of the normal package development workflow.

Use the dedicated stabilization documentation for maintainer work:

• Maintainer guide
• Branching concept
• Maintainer troubleshooting