Contribute

CIVITAS/CORE is a community project of public-sector organisations, developed in the open under the EUPL-1.2. Contributions are welcome: bug reports, feature requests, code, documentation and tests.

This page explains where to contribute, how a change travels from an idea to a merged merge request (MR), and what reviewers expect.

Before you start

• Code of Conduct. Every contributor follows the Contributor Covenant 2.1. Report unacceptable behaviour to core@civitasconnect.digital.
• Support questions do not belong in the issue tracker. Use the community forum or the open community call (every fourth Wednesday, 10:00–11:00).
• Security vulnerabilities. Do not open a public issue or MR. Follow Reporting Vulnerabilities.
• Name and logo. "CIVITAS/CORE" is a registered trademark of Civitas Connect e. V. You can use the name to describe your work, but you must not present your build as an official release. See the TRADEMARK.md in each repository.

Open development and terms of participation

CIVITAS/CORE is developed openly and transparently. Technical discussions, decisions and contributions therefore take place in public. There are three main channels for communication, each with its own purpose:

Channel	Use it for
GitLab	General communication, delivering code (merge requests) and creating work items such as bugs and feature requests. This is the default place for everything that leads to a change.
Zulip	Low-threshold exchange between developers, for example quick questions, ideas and coordination while you work on a change.
Community forum	Questions and discussion for users who do not develop themselves.

The following rules generally apply to your participation:

• Participation is open to people aged 18 or older.
• Each person has only one account. Multiple accounts on the same platform are not allowed.
• You may use a pseudonym or a username of your choice. Do not pose as another person.
• English is the general community language. In Zulip and the community forum you may use German as well.
• Discuss project topics in the public CIVITAS/CORE channels. Do not post security vulnerabilities, data protection or security incidents, complaints about individuals, or confidential or particularly sensitive information in public channels. For vulnerabilities, follow Reporting Vulnerabilities.

Zulip only:

• The Open Development channels are web-public. Anyone can read their content on the internet, even without a Zulip account.
• Together, the posts published in the same folder of the Open Development channels form the terms of use, the community terms and the contribution terms for CIVITAS/CORE. By creating and submitting contributions, you accept the terms that apply to your participation.

Questions about the terms and non-public reports: core@civitasconnect.digital

Operator: Civitas Connect e. V., Hafenweg 7, 48155 Münster.

Where to contribute

These are the most relevant repositories for new contributions. Additional repositories are listed in Project Structure.

Repository	Content	Target branch
civitas-core-platform	Custom components: portal backend and frontend, authz, config adapters, Model Forge, NiFiApache NiFiA stream processing and connector framework. In CIVITAS/CORE it is the pipeline engine for data integration and transformation (see ADR 047) and implements dataset-defined data flows. extensions	develop
civitas-core-deployment	Helmfile, Helm charts and defaults for all platform components	develop
documentation	This documentation (Docusaurus)	main

Roles

Role	What they do
Contributor	Creates issues, comments and opens merge requests. Has no write access to the protected branches.
Reviewer	Reviews merge requests and gives approvals. In the platform and deployment repositories, every project member can approve.
Maintainer	Merges approved merge requests into the protected branches (main, develop, staging).
Architecture board	Decides on architecture and architecture concepts. Product architect, product owner, lead developers and the security architect are members. Decisions are recorded as Architecture Decision Records.

Report a bug

1. Search the issues of the affected repository first.
2. Create an issue in that repository and add the label type::bug.
3. Describe at least: the precondition and environment, the steps to reproduce, and the expected and the observed behaviour.

If you test the platform and want a lightweight way to report unexpected behaviour, use the type Finding and the Findings Board.

If you have an idea to improve existing behaviour, use the type Improvement instead. Improvements work the same way as Findings and have their own Improvements Board. Either create the work item directly with the type Improvement, or change the type afterwards: open the menu in the top right corner of the work item and select Change type.

Suggest a feature

Open an issue with the label type::feature request. Explain the purpose and the benefit. The project management answers in the issue and creates linked implementation issues.

Discuss larger changes in an issue before you write code. Architecture-relevant decisions are recorded as Architecture Decision Records (label type::adr).

Make a change

1. Get the code running

Follow the Local Development Setup. The platform repository also has a Docker Compose based development stack (dev-environment/).

2. Create a branch

• External contributors: fork the repository to your own GitLab account and create the branch there.
• Members of the project: create the branch in the repository. The protected branches main, develop and staging do not accept direct pushes.
• Create the branch from the issue you work on (in GitLab: Create merge request or Create branch on the issue). This gives the name <issue-number>-<short-description>, for example 2386-remove-datastructure-version-deletion-from-ui, and GitLab links the issue and the MR. Without an issue, use fix/<topic> or feat/<topic>. This is a convention, not a rule.

3. Follow the standards

Area	Read
All changes	Secure Development Guide
AI-assisted work	AI Usage Policy
Backend (Java)	Java Style Guide
Frontend	Frontend Style Guide
Deployment and Helm	Component configuration and Container Image Guidelines
Authorization	Authorization Data Model

Keep a change small: one topic per MR, ideally one new feature per version. Add or update tests, and update the documentation in the same step (see Contribute to the documentation).

You do not need to maintain a changelog. Release information is published in the release notes and milestones.

4. Write commit messages

Use Conventional Commits:

<type>(<optional scope>): <summary in imperative mood>

• Write the first line in the imperative mood ("fix", not "fixes") and keep it to 72 characters or less.
• Typical types: feat, fix, docs, chore, refactor, test, ci. The scope names the component, for example fix(frost): … or docs(backend): ….
• Reference issues and MRs after the first line.

5. Open the merge request

Target the branch from the table above. The repositories provide an MR template. Fill in:

• Description and the related issue. Link it so that GitLab closes it on merge (Closes #123).
• Security review: confirm that you followed the guides and that the CI security checks pass.
• Dependencies: if you add one, give the rationale and the risk assessment. Do not add a dependency for less than about 50 lines of code. See the Secure Development Guide.
• Testing and code quality: tests added and passing, no commented-out code or debug statements, documentation updated.
• AI maturity: state how much human control went into AI-assisted work, as described in the AI Usage Policy.

The CI pipeline must pass: build, lint, tests and the security scans (SAST, dependency and secret scanning). In the platform repository the merge is blocked until it does.

6. Review and merge

• At least one approval is required. Changes to security-relevant areas need at least two approvals. Security-relevant areas are listed in When to involve security. Documentation MRs are reviewed by the team before a developer or maintainer merges them.
• Reviewers comment in the MR. Answer each comment, or fix the point and say so.
• Contributors do not get direct commit access. A maintainer merges the approved MR. The source branch is deleted after the merge.
• You can expect feedback in a reasonable time. If an MR stays quiet, ask in the MR.

Contribute to the documentation

Documentation changes follow the same flow in the documentation repository. In addition:

• The documentation is versioned. New content goes to the development version (docs_v2/, shown as "next"). Do not change archived versions, except to fix factual errors.
• Explain the "why" before the "how". Keep pages self-contained and link related pages instead of copying content.
• Add new pages to the navigation and check that no internal link is broken. Broken links count as defects.
• Use draw.io for diagrams and commit the combined export with embedded source (*.drawio.svg or *.drawio.png).
• If your code change alters behaviour that users or operators see, update the documentation in the same step, and describe manual upgrade steps.

To check your pages locally, run npm install and npm start. For every MR, the CI also builds a preview of the documentation. You find the link on the MR page. It has the form https://docs.core.civitasconnect.digital/review-<branch-name>/.

License and copyright

All contributions are licensed under the EUPL-1.2 or any later version. There is no Contributor License Agreement. The copyright stays with the individual contributors. Do not change the license of files that carry a different license.

Recognition

Contributors are listed in CONTRIBUTORS.md of each repository.