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 — but not all on the same host, and for the application repositories the difference decides where a contribution lands.

Component	Developed on	Mirror	Issues
IOU Architecture Docs	sgort/iou-architectuur — GitHub Actions	showcases/iou-architectuur	Issues
RONL Business API	sgort/ronl-business-api — GitHub Actions	hosting/ronl-business-api	Issues
Norm Editor	regels/editor — GitLab CI	—	Issues
CPSV Editor	sgort/ttl-editor — GitHub Actions	showcases/ttl-editor	Issues
Linked Data Explorer	sgort/linked-data-explorer — GitHub Actions	hosting/linked-data-explorer	Issues
CPRMV API	standards/cprmv — GitLab CI	—	Issues

All three application repositories are developed on GitHub — pull requests, issues, and every CI gate described under Code Standards and Supply-Chain Pinning run there — and are mirrored by hand to the open-regels.nl GitLab instance. Open issues and pull requests on GitHub; the mirror has no CI and runs none of those gates. On 11 September 2026 the CPSV Editor's and the Linked Data Explorer's GitHub trackers held 12 and 10 issues, the GitLab ones 1 and 2; the RONL Business API's held 20 open issues on 12 September 2026, and the issue numbers its changelog cites are GitHub's.

This site's issue tracker moved to GitHub on 12 September 2026, so all four now keep issues and pull requests in the same place. The GitLab tracker keeps the 57 issues it held on 11 September and receives no new ones; open anything further on GitHub, beside the pull request that will close it. The split that preceded this — pull requests on one host, issues on the other — cost a decision its context every time.

Since 12 September 2026 each of the three checks its mirror at every release, with scripts/check-mirror.sh called from /bump-release. It reports and never pushes — see Supply-Chain Pinning — the GitLab mirror. The Norm Editor and the CPRMV API are developed on GitLab, where their pipelines run.

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 the pull or merge request.

Open it where the repository lives, which the table above gives per component: the three applications and this site take issues and pull requests on GitHub; the Norm Editor and the CPRMV API take issues and merge requests on GitLab. The steps below are the same on both hosts — where they say merge request, read pull request on GitHub.

2. Fork the repository

Fork the relevant repository to your own account or namespace on the host it lives on.

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 is protected in all three applications

In the CPSV Editor, the Linked Data Explorer and the RONL Business API, acc requires a pull request with no bypass actors — a direct git push origin acc is rejected — plus a passing audit, a passing scan, and, since 19 September 2026, that repository's build and deploy checks. In practice that means a merge request whose tests fail cannot be merged into acc.

Two of the three also gate main, but with fewer checks than acc, not the same ones: no main requires a build or a test anywhere — in the Linked Data Explorer and the RONL Business API, production is deployed by a promotion workflow on the push to main, not on the pull request. See Branch Protection for what each branch requires, and the controls index for where every control holds.

---

Contact

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

Steven Gort — ICTU
steven.gort@ictu.nl

---

Licensed under EUPL-1.2.