Contributing to IOU Architecture

The IOU Architecture Framework is an open-source project published under the European Union Public Licence v1.2 (EUPL-1.2). Contributions of any kind — documentation improvements, bug reports, feature suggestions, or code — are welcome from everyone.

---

Code of Conduct

This project adheres to the principles of the Contributor Covenant Code of Conduct. By participating you agree to uphold these principles:

• Be respectful and inclusive. Treat all participants with dignity regardless of background, experience level, gender, ethnicity, religion, or nationality.
• Assume good faith. Interpret ambiguous contributions charitably and ask for clarification before escalating concerns.
• Be constructive. Feedback should focus on the work, not the person. Offer concrete suggestions rather than criticism alone.
• Respect the scope. Keep discussions on-topic for the project. Off-topic, harassing, or abusive behaviour will not be tolerated.

Violations can be reported confidentially to steven.gort@ictu.nl. All reports will be handled with discretion and care.

---

Repositories

Each component of the IOU Architecture ecosystem lives in its own repository on the open-regels.nl GitLab instance.

Component	Repository	Issues
IOU Architecture Docs	showcases/iou-architectuur	Issues
RONL Business API	hosting/ronl-business-api	Issues
Norm Editor	regels/editor	Issues
CPSV Editor	showcases/ttl-editor	Issues
Linked Data Explorer	hosting/linked-data-explorer	Issues
CPRMV API	standards/cprmv	Issues

For component-specific development setup, refer to each component's Developer Docs:

• RONL Business API — Local Development
• Norm Editor — Local Development
• CPSV Editor — Local Development
• Linked Data Explorer — Local Development
• CPRMV API — Local Development

---

How to Contribute for Users

Submit a use case →

How to Contribute for Developers

There are two equally valid routes into development, depending on the tooling you have to hand. Maintainers and core contributors working with the AI-assisted pipeline should follow the Development Workflow subsection. Contributors working from a fork should use the fork-and-merge-request process below, which is the complete and correct route into the project regardless of which repository you're contributing to.

1. Open an issue first

Before starting any significant work, open an issue in the relevant repository to describe what you intend to do. This avoids duplicate effort and allows early feedback. For small corrections (typos, broken links, formatting) you can skip straight to a merge request.

2. Fork the repository

Fork the relevant repository to your own GitLab account or namespace.

3. Create a feature branch

Always work on a dedicated branch, never directly on main or acc.

git checkout acc                          # start from the acceptance branch
git pull origin acc                       # make sure it is up to date
git checkout -b feature/your-topic-name  # create your feature branch

Branch naming convention:

Prefix	Use for
feature/	New content or functionality
fix/	Corrections and bug fixes
docs/	Documentation-only changes
refactor/	Restructuring without content change

4. Make your changes

Run the documentation site locally while you work:

python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
mkdocs serve

The site is then available at http://127.0.0.1:8000/.

For every English page you add or change, also update the corresponding Dutch placeholder under docs/nl/. Dutch placeholders use an info admonition linking back to the English source — see any existing file under docs/nl/ for the correct format.

5. Commit your changes

Follow the Conventional Commits specification:

docs: add troubleshooting section to LDE user guide
fix: correct broken link in CPSV Editor overview
feat: add CPRMV API authentication reference page

6. Open a merge request

Push your branch to your fork and open a merge request against the acc branch of the upstream repository.

git push origin feature/your-topic-name

In the merge request description:

• Reference the related issue (Closes #123)
• Briefly describe what changed and why
• Note any follow-up work that is out of scope for this MR

Merge requests are reviewed by the maintainer. Feedback is given directly in the MR thread. Once approved, the maintainer merges into acc and promotes to main as part of the regular release cycle.

Read Code Standards →

acc may be protected

In CPSV Editor and RONL Business API, the acc branch requires a pull request and a passing supply-chain audit check, with no bypass actors — a direct git push origin acc is rejected. See Supply-Chain Pinning for what the gate checks and why.

---

Contact

For questions, feature requests, or anything else related to the IOU Architecture that does not fit a GitLab issue, you can reach the project maintainer directly:

Steven Gort — ICTU
steven.gort@ictu.nl

---

Licensed under EUPL-1.2.