arrow_back_ios_new

Synced automatically from infinity-project/rulebook (main) at build time – edit the source repository, not this file.

Code development and testing

← Back to index

When to create a repository?

Create a new repository in Codeberg’s INFINITY organization whenever there is an activity which leads to the production of a new component of the INFINITY Ecosystem.

Do I really need to create a repository for anything I do?

No. Yet as soon as the idea of a new component is discussed or presented in a meeting, and its development is agreed, a repository should be already there or follow straight after! A first repository may simply provide a URL and name to the component development process. A repository with annotated component descriptions is mandatory for components mentioned in official project deliverables.

What if a repository already exists somewhere else?

You don’t need to fork the repository within the INFINITY organization. External components can be described (with annotations and referencing the external repository) in an internal repository which still reuses the guidelines of this rulebook, e.g. metadata.

Repository requirements

Every project submitted to the ecosystem must meet the following repository requirements.

Mandatory files

Each repository must contain the following base set of files in the top level (root) directory:

  • README.md
  • LICENSE
  • CONTRIBUTING.md — how to contribute
  • MAINTAINERS.md — defines ownership and roles (e.g. champion)
  • CODE_OF_CONDUCT.md — rules of behaviour for all contributors
  • CHANGELOG.md — document notable changes, updates or fixes

The following files are additionally recommended:

  • AI_USAGE.md — see Dealing with AI Agents; may also live inside LICENSE, or be paired with ai.txt
  • SECURITY.md — describing how to report vulnerabilities*
  • SUPPORT.md — how to request help, report issues*
  • .editorconfig — ensures consistent formatting
  • .gitignore — prevents commit of unnecessary files

* Otherwise, default procedures are to be followed.

YAML header

Copy the YAML block below and use it as the header of your component description .md file, changing values and removing terms that are not needed. A list of component types can be found in the reeco-annotation-schema README. The main categories to reuse unless your component falls outside them:

  • Data (most general category), Dataset (curated and structured data), Schema, Ontology, KnowledgeGraph
  • Software — source code, a library, a workflow definition, a notebook or a script
  • Application — something deployed and run as an end-user- or system-facing product: a website, a web app, a web/API service someone calls, a mobile app, a CLI tool
  • Report — a textual or visual document intended for human reading, such as a project deliverable
---
component-id: fabulous-component-source-code
type: Software
name: The Fabulous Source Code
description: Source code of The Fabulous
image: https://www.example.org/image.png
logo: https://www.example.org/logo.png
work-package:
- WPn
pilot:
- pilot name

project: infinity-project
demo: URL of an online demo
release-date: YYYY/MM/DD
release-number: v1.0-alpha
release-link: URL of the latest software release
doi: 10.5281/zenodo.000000
changelog: URL of the changelog
licence:
- CC-BY-SA_v4
copyright: "Copyright (c) 2026 The Infinity Project Contributors"
contributors:
- A champion <name, org, email>
- Another contributor

related-components:
- extends:
  - another component
- reuses:
  - another component
  - another dataset
- serves:
  - another component
- generated-by:
  - The AI code generator http://www.my-software-factory.com
- derived-from:
  - this-other-component
credits: "This project has received funding from the European Union's Horizon Europe research and innovation programme under grant agreement N. 101233051"
---

README requirements

The README must include as human-readable documentation:

  • Component overview
  • Installation instructions (incl. prerequisites)
  • Usage examples
  • API documentation (if applicable)
  • FAQ (Frequently Asked Questions)
  • Citation for the repository itself* and other references (e.g. project deliverable, published articles or reports)
  • References to other mandatory files (e.g. license, contributing, code of conduct, security, support, changelog)
  • Any appropriate declarations, e.g. use of AI

* You can also put a CITATION.cff file for a machine-readable citation.

Information on installation and setup

  • Either package requirements (e.g. requirements.txt)
  • Or add instructions to recreate the software environment (e.g. conda environment, docker, installer)
  • If applicable, list data sources to be downloaded (with links)

Running and usage examples

  • Instructions on how to run the code
  • Add either a Jupyter notebook or code samples with examples on how to run the code, features, and output — so the user sees exactly what you want them to see and doesn’t need to dive into the code (e.g. wrappers for common usage cases)

See Awesome-READMEs for a list of exemplary curated README files, plus a good example for software and a minimal dataset README template.

Dealing with AI Agents

The repository should include an AI_USAGE.md and optionally an ai.txt.

The AI_USAGE.md file should describe — in clear, legal and ethical terms — what AI systems are allowed and not allowed to do with the code (e.g., training, indexing, reuse, attribution requirements).

Complementing this, an ai.txt file provides a lightweight, machine-readable set of rules that AI agents can parse automatically, indicating which parts of the repository may be accessed or restricted (proposed here, aligned to the pre-existing definition of robots.txt for web crawlers).

Together, these files create a dual-layer policy: AI_USAGE.md communicates intent to humans and developers of AI systems, while ai.txt enables automated agents to programmatically respect those boundaries, helping ensure responsible and transparent use of open-source assets in an AI-driven ecosystem.

Code development

Coding will be done by writing code on a local machine in a git repository and then pushing it to Codeberg. You must install and configure git, then create the new repository and follow a best-practice Git workflow.

A Git workflow is a defined process that guides how developers collaborate, manage code changes, and release stable versions of software. Even in solo projects, adopting a structured workflow ensures your code remains organized, traceable, and easily revertible if something goes wrong. Developers must follow INFINITY code development guidelines faithfully to ensure that:

  • We avoid merge conflicts.
  • You keep your production code clean.
  • There is smooth collaboration with others.
  • You can track and review changes efficiently.

In INFINITY, we advise developers to follow the guidelines at githubflow.github.io.

In terms of the use of AI to generate programming code, assistance in programming IDEs (e.g. Claude Code, GitHub Copilot) is acceptable. Developers are responsible for checking the validity of AI generated code.

Repositories must declare the use of AI assistance in the README using a simple statement such as “Claude Code was used for correcting and completing parts of the code.” If specific parts were generated directly by AI, refer to the INFINITY Project Handbook for AI citation policy.

Champions & external developers

Each repository must have a champion, annotated in the MAINTAINERS.md file. A champion is a person who is part of the INFINITY project consortium and should work for the partner who is the lead responsible for the related workpackage/task in the project where the component is being developed.

The Champion serves as the primary steward of the component and is responsible for guiding its technical direction, maintaining its quality standards, and ensuring alignment with the ecosystem’s principles. The Champion acts as the technical owner and accountability point for the repository.

1. Technical Leadership

  • Defining the overall architecture and design of the component
  • Ensuring the repository follows INFINITY technical standards
  • Approving major technical changes
  • Ensuring compatibility with the broader INFINITY Ecosystem
  • Maintaining long-term technical vision

2. Repository Stewardship

  • Maintaining repository structure and documentation
  • Ensuring required files are present and updated
  • Managing issue tracking and backlog prioritization
  • Ensuring consistent code organization and standards
  • Keeping dependencies updated and secure

3. Code Review and Quality Assurance

  • Reviewing pull requests or delegating reviews to trusted maintainers
  • Enforcing code style and formatting standards
  • Ensuring appropriate test coverage
  • Ensuring that CI pipelines pass before merging
  • Rejecting contributions that do not meet quality standards

4. Contributor Coordination

  • Welcoming and onboarding new contributors
  • Assigning issues and tasks
  • Providing technical guidance and mentorship
  • Ensuring respectful collaboration within the community
  • Resolving technical disagreements

5. Security Oversight

  • Responding to security vulnerability reports
  • Coordinating vulnerability fixes
  • Ensuring secure dependency management
  • Maintaining a vulnerability disclosure process
  • Coordinating security audits when required

6. Release Management

  • Approving release candidates
  • Ensuring versioning follows semantic versioning
  • Maintaining the project changelog
  • Tagging official releases
  • Ensuring releases are stable and documented

7. Ecosystem Alignment

  • Following ecosystem technical policies
  • Participating in ecosystem governance discussions when necessary
  • Coordinating with maintainers of related components
  • Ensuring interoperability with ecosystem tools and standards

8. Documentation Ownership

  • Maintaining an accurate README
  • Keeping technical documentation current
  • Documenting APIs and interfaces
  • Maintaining contribution guidelines
  • Ensuring onboarding documentation for new developers

9. Maintenance and Sustainability

  • Monitoring project activity
  • Preventing repository stagnation
  • Recruiting additional maintainers when needed
  • Planning future roadmap items
  • Initiating deprecation if the project becomes obsolete

10. Accountability

The Champion is the primary accountable individual for the repository. They must:

  • Respond to ecosystem governance inquiries
  • Address technical or security issues in a timely manner
  • Ensure the project remains compliant with the rulebook
  • Step down or nominate a successor if they can no longer maintain the project

Each repository must always have an active Champion. The champion may also name a deputy, especially in cases where they are not always available and there is significant activity in the repository. The deputy takes over the role of champion when the champion is unavailable.

Repository contributors will usually be restricted to developers working for organisations which are INFINITY project consortium members and named contributors to the workpackage/task where the component is being developed. Anyone may contribute to the INFINITY Ecosystem provided they:

  • Are permitted to do so by the champion of the respective repository
  • Accept the Contributor License Agreement (CLA)
  • Follow the Code of Conduct
  • Comply with this technical rulebook

Contributors must use a verified developer identity to ensure accountability. It is at the champion’s discretion to permit external developers to contribute, and the champion takes responsibility for their actions on behalf of the INFINITY project.

The CLA may read: “All contributors grant the project a perpetual, worldwide, non-exclusive, royalty-free license to use, reproduce, modify, and distribute their contributions as part of this component.” — to be included in CONTRIBUTING.md.

Discussion and decisions

Discussions can happen anywhere at any time, but they must be recorded within the discussion section of the component’s repository — any discussion which began elsewhere (e.g. a workpackage/task meeting) should be added and continued there.

Discussions should be clear about who proposes what, and proposals need clear, unambiguous communication about what is being proposed.

Considerations of actions that would impact the development of the component MUST be logged as an issue and motivated by the person calling for the action. Sufficient time must be allowed for all participants to discuss before a decision is taken. If needed, decisions may be based on votes (by all registered contributors to the affected repository, excluding observers), but the champion always has the last word.

Agreement to an implementation change based on an issue must include the responsible person (to make the change), ideally with a deadline for internal delivery — the implementation task may continue in the same issue where the decision was made.

If the discussion and decision is not being recorded in the repository itself, it never happened.

Tracking changes (commits)

Commit messages are mandatory and must reference at least one Issue.

All commits SHOULD follow the Conventional Commits specification (type(scope): description) to enable automated changelog generation, semantic versioning, and AI-assisted analysis.

Tracking progress

Progress on the development of each component MUST be reported in the Issues section periodically — ideally at least monthly, in line with work package meetings.

Each repository SHOULD have an issue related to the component development as a whole for general progress updates (recommended as issue #1). A simple reporting template can be a bullet list in three sections (3P):

  • Progress — what concrete work has been done since the last update
  • Problems — anything that is slowing or blocking progress, or expected to
  • Perspectives — what progress is expected going forward, including plans to address problems

The general progress updates issue should be used only for these updates. Detailed, task-based issues should be created when necessary for referencing changes (commits), and linked from the “central” issue when relevant.

Examples: Tracking progress issue (Rulebook), Tracking progress issue (External Components)

Naming conventions

For repositories:

  • Avoid including “INFINITY” in the name (e.g. ecosystem rather than infinity-ecosystem)
  • Avoid acronyms and vague/ambiguous words; only use commonly understood abbreviations. Aim for self-explanatory names (ontologynetwork instead of ON)
  • Consider including the component’s type in the name if the same functionality is released in different forms (e.g. sdk-textminer and api-textminer)
  • Consider using a primary and secondary name to group related components (e.g. X-python and X-rust)
  • Use only lowercase
  • Hyphens, not underscores
  • Don’t put version numbers in the repository name

Branches

Use branches for managing different versions of the code/components. Avoid creating a branch for each sub-system (e.g. /datasets, /ui, etc.). Instead, create different repositories and use a good naming convention to reflect the relationship between them.

Testing

Start planning for testing from the very first moment the software component is engineered — before any actual coding takes place. Design test cases for each function/method being implemented, together with a simple framework allowing automatic execution. The testing strategy depends on the type of software being developed.

Unit testing is the standard approach to demonstrate correct operation of every aspect (e.g. function, use case) of the component. Standard frameworks exist to support code tests, e.g. pytest in Python. For CI/CD, we use Woodpecker, which Codeberg provides natively (at ci.codeberg.org). Once a repository is enabled for CI, Woodpecker automatically runs a pipeline on each push or pull request, so broken code is caught before a merge. The pipeline is defined in a .woodpecker.yml file at the root of the repository (or, for multiple workflows, a .woodpecker/ folder containing several YAML files).

Test code must be included in the repository in its own directory. Keep tests lightweight, self-contained and easy to run. Provide all relevant instructions to configure and run the testing scripts, and clearly state what the correct result of each test should be. We recommend using mocked-up data as test inputs. Any user should be able to run the tests to verify correctness, stability and quality.

You may also measure test coverage (e.g. coverage.py in Python), shown via coverage results in the repository and/or a coverage badge in the README.

Releases

When a component is ready for release, a technical review must be undertaken, covering: code tests performed and passed, security check, and confirmation that work has followed this rulebook (e.g. presence of documentation, ethical checklist). The technical review is done by the Technical Board (responsibilities divided by component-type expertise; reviewers cannot include contributors to that component or members of the same organisation as the Champion).

On approval, the component (version) becomes an official part of the INFINITY ecosystem. Follow the agreed workflow for code release.

After a release, you should archive the frozen state of the repository in Zenodo to ensure long-term preservation and citability. Since there is no automatic synchronization with Codeberg, this must be done manually:

  1. Create a release in Codeberg (using a Git tag)
  2. Download the release archive (e.g., .zip or .tar.gz)
  3. Upload it as a new software record in Zenodo and complete the metadata fields

Use Semantic Versioning for release numbers: MAJOR.MINOR.PATCH (breaking changes, backward-compatible feature additions, bug fixes respectively). In Git, versions are implemented via tags.

Each release must include release notes recorded in CHANGELOG.md, clearly documenting added, changed, fixed, and deprecated elements.

After publication on Zenodo, include the DOI of the archived release:

  • in the README.md file (recommended as a badge or citation section)
  • and, where applicable, in CITATION.cff and other metadata files

This ensures users can cite a stable, versioned snapshot of the software, independent of ongoing development in the repository.

Release notes

Release notes communicate what was changed, improved, or fixed in a new version of a component.

  • Always tie release notes to a specific version number (MAJOR.MINOR.PATCH)
  • Keep it concise but informative — focus on what’s meaningful to users and developers
  • Structure the notes consistently for readability and automation
  • Reference issues or pull requests for traceability

Header format:

# Version X.Y.Z – YYYY-MM-DD

Followed by a short summary of the overall release (aim for a single sentence), then categorized changes:

  • Added – New features or components
  • Changed – Modifications to existing functionality
  • Fixed – Bug fixes or performance improvements
  • Deprecated – Features or APIs planned for removal
  • Removed – Features or APIs removed

Reference issues, pull requests or commits using repository links to help trace changes.

← Back to index · Next: Code documentation →