Contributing Guide

Overview

This guide covers the full workflow for contributing to the Iroko Framework vocabulary — from setting up your local environment through validation, HTML generation, and deployment. The vocabulary files are RDF/Turtle (.ttl); the HTML documentation pages are generated from them programmatically.

Development Setup

Prerequisites

• Python 3.10 or later
• Git (with write access to the repository)
• A text editor with Turtle syntax support (VS Code with the Stardog RDF Grammars extension is recommended)

Install dependencies

pip install rdflib

Clone the repository

git clone https://github.com/iroko-framework/iroko-framework.git
cd iroko-framework

Repository Structure

iroko-framework/
  index.html                 # Homepage
  assets/
    IHS-Logo.jpg
    iroko-style.css          # Shared stylesheet
  vocab/
    index.html               # Vocabulary index
    iroko-core.ttl           # Core module (source of truth)
    iroko-core.html          # Generated — do not edit directly
    iroko-ewe.ttl
    iroko-ewe.html
    iroko-nkisi.ttl
    iroko-nkisi.html
    iroko-travay.ttl
    iroko-travay.html
    iroko-ile.ttl
    iroko-ile.html
  docs/
    index.html               # This documentation index
    CONTRIBUTING.html
    REUSE.html
    ARCHITECTURE.html
  generate_browse_pages.py   # HTML generator script

Editing Vocabulary Files

Turtle syntax conventions

• Use 2-space indentation throughout
• One triple per line for readability; use semicolons for same-subject continuation
• Prefix declarations at the top; alphabetize after @base
• All rdfs:label values in English (@en); add skos:prefLabel in additional languages for concept schemes
• All rdfs:comment and skos:definition values in English only unless explicitly multilingual

Access levels

Every property must carry iroko:minimumAccessLevel pointing to a concept in the Access Level Classification scheme. The six levels are:

• iroko:access-public-unrestricted — visible to anyone
• iroko:access-community-restricted — visible to recognized community members
• iroko:access-initiated-only — visible to initiated practitioners
• iroko:access-elder-only — visible to recognized elders
• iroko:access-no-access — not exported; internal record only

Adding a new concept scheme

1. Declare the scheme as a skos:ConceptScheme with rdfs:label, skos:prefLabel (all five languages), and skos:hasTopConcept listing all top-level concepts
2. Declare each concept with a skos:Concept, skos:inScheme, skos:prefLabel (all five languages), and skos:definition
3. Add skos:scopeNote for anything contested or requiring clarification

Validation

Parse check

python3 -c "
from rdflib import Graph
g = Graph()
g.parse('vocab/iroko-core.ttl', format='turtle')
print(f'OK - {len(g)} triples')
"

Full validation script

Run against all TTL files before committing:

for f in vocab/*.ttl; do
  python3 -c "
from rdflib import Graph
g = Graph()
g.parse('$f', format='turtle')
print(f'OK: $f — {len(g)} triples')
"
done

Generating HTML Documentation

After editing any TTL file, regenerate the HTML browse pages:

python3 generate_browse_pages.py

This reads all TTL source files and overwrites the corresponding .html files. Commit both the TTL and the regenerated HTML together.

Deployment Workflow

1. Edit the relevant .ttl file
2. Validate: python3 -c "from rdflib import Graph; g = Graph(); g.parse('vocab/iroko-X.ttl'); print(len(g))"
3. Regenerate HTML: python3 generate_browse_pages.py
4. Commit TTL + HTML together: git add vocab/ && git commit -m "Update iroko-X: [describe change]"
5. Push: git push origin main
6. GitHub Pages deploys automatically within ~60 seconds

Pull Request Guidelines

• One logical change per PR — don't bundle unrelated vocabulary additions
• Include a brief description of what changed and why
• Always include the regenerated HTML — PRs with stale HTML will be rejected
• Contested design decisions should be flagged with skos:scopeNote or iroko:contestedNotes in the TTL, not resolved silently