Contribution Guidelines

The Orthogramic Metamodel is an open-source project that welcomes contributions from the community. This page explains how to contribute effectively.

Ways to Contribute

Contribution Type	Description	Skill Level
Report Issues	Identify bugs, gaps, or improvements	Beginner
Improve Documentation	Fix typos, clarify content, add examples	Beginner
Propose Enhancements	Suggest new features or domains	Intermediate
Submit Schema Changes	Modify or extend JSON schemas	Intermediate
Create Examples	Add real-world usage examples	Intermediate
Build Integrations	Develop platform integrations	Advanced
Review Pull Requests	Help review community contributions	Advanced

Getting Started

1. Understand the Project

Before contributing, familiarize yourself with:

Metamodel Overview — Core concepts
Domain Documentation — Existing domains
JSON Schema Index — Schema structure
Open Source Manifesto — Project philosophy

2. Set Up Your Environment

# Fork the repository on GitHub
# Clone your fork
git clone https://github.com/YOUR-USERNAME/orthogramic-metamodel.git
cd orthogramic-metamodel

# Add upstream remote
git remote add upstream https://github.com/orthogramic/metamodel.git

# Install dependencies
npm install

# Run validation
npm run validate-schemas

3. Find Something to Work On

Check GitHub Issues for open tasks
Look for issues labeled good first issue for beginner-friendly tasks
Review help wanted labels for community priority items

Contribution Workflow

For Documentation Changes

Fork the repository
Create a branch for your changes: git checkout -b docs/improve-capabilities-examples
Make changes to documentation files
Test locally by building the docs site
Submit a Pull Request with clear description
Address review feedback as needed
Celebrate when merged!

For Schema Changes

Schema changes require additional rigor:

Create an Issue first — Discuss proposed changes before implementing
Follow schema conventions — See Schema Standards below
Include tests — Add validation test cases
Update documentation — Keep docs in sync with schema changes
Provide migration guidance — If changes affect existing implementations

Schema Standards

Naming Conventions

Element	Convention	Example
Schema files	`{domain}.schema.json`	`capabilities.schema.json`
Property names	camelCase	`capabilityLevel`
Enum values	kebab-case	`in-progress`
Definition names	PascalCase	`CapabilityComponent`

Required Schema Elements

Every domain schema must include:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://orthogramic.com/schemas/domains/{domain}.schema.json",
  "title": "{Domain Title}",
  "description": "{Clear description of the domain}",
  "type": "object",
  "required": ["title", "description"],
  "properties": {
    "title": {
      "type": "string",
      "description": "The name of the {domain} entity"
    },
    "description": {
      "type": "string",
      "description": "Detailed description of the {domain} entity"
    }
  }
}

Property Guidelines

Property Aspect	Guideline
Descriptions	Every property must have a description
Types	Use specific types (not just `any`)
Required	Mark truly required fields as required
Defaults	Provide sensible defaults where appropriate
Enums	Use enums for categorical values
References	Use `$ref` for reusable definitions

Enum Conventions

{
  "maturityLevel": {
    "type": "string",
    "description": "Current maturity level of the capability",
    "enum": [
      "initial",
      "developing",
      "defined",
      "managed",
      "optimizing"
    ],
    "default": "initial"
  }
}

Documentation Standards

MDX File Structure

---
sidebar_position: 1
title: Page Title
description: Clear, concise description for SEO
keywords: [relevant, keywords, for, search]
---

# Page Title

Brief introduction paragraph.

## Main Section

Content organized in logical sections.

### Subsection

More detailed content.

## Related Documentation

- [Related Page 1](./related-1) — Brief description
- [Related Page 2](./related-2) — Brief description

Writing Style

Aspect	Guideline
Voice	Active voice preferred
Tense	Present tense for descriptions
Person	Second person ("you") for instructions
Length	Concise sentences, short paragraphs
Examples	Include practical examples
Tables	Use tables for structured comparisons

Code Examples

Include language identifier: ```json, ```python
Keep examples realistic and complete
Add comments for complex examples
Test all code examples before submitting

Pull Request Guidelines

PR Title Format

type(scope): brief description

Examples:
- docs(capabilities): add example for manufacturing
- schema(risk): add control effectiveness enum
- fix(validation): correct required field check

Types: docs, schema, fix, feat, refactor, test, chore

PR Description Template

## Description
Brief description of changes.

## Motivation
Why is this change needed?

## Changes Made
- Change 1
- Change 2

## Testing
How were these changes tested?

## Related Issues
Closes #123

## Checklist
- [ ] Documentation updated
- [ ] Schema validates correctly
- [ ] Examples tested
- [ ] No breaking changes (or migration guide provided)

Review Process

Automated checks — CI runs schema validation and doc builds
Community review — At least one approval required
Maintainer review — Final approval from project maintainer
Merge — Squash and merge to main branch

Issue Guidelines

Bug Reports

## Bug Description
Clear description of the bug.

## Steps to Reproduce
1. Step one
2. Step two
3. Step three

## Expected Behavior
What should happen.

## Actual Behavior
What actually happens.

## Environment
- Browser/Tool: 
- Version:

## Additional Context
Screenshots, logs, etc.

Feature Requests

## Feature Description
Clear description of the proposed feature.

## Motivation
Why is this feature needed? What problem does it solve?

## Proposed Solution
How should this feature work?

## Alternatives Considered
Other approaches considered and why this is preferred.

## Additional Context
Mockups, examples from other tools, etc.

Community Guidelines

Code of Conduct

We are committed to providing a welcoming and inclusive environment:

Be respectful — Treat all contributors with respect
Be constructive — Focus on improving the project
Be patient — Remember that contributors have varying experience levels
Be collaborative — Work together toward common goals

Communication Channels

Channel	Purpose
GitHub Issues	Bug reports, feature requests
GitHub Discussions	Questions, ideas, general discussion
Pull Requests	Code and documentation contributions

Response Times

Activity	Expected Response
Issue triage	Within 1 week
PR initial review	Within 2 weeks
Discussion reply	Within 1 week

Recognition

Contributors

All contributors are recognized in:

GitHub contributors list
Release notes for significant contributions
Annual contributor acknowledgment

Types of Recognition

Contribution Level	Recognition
First contribution	Welcome message, first-timer badge
Regular contributor	Contributor badge
Significant impact	Featured contributor
Sustained contribution	Maintainer consideration

Licensing

Contribution License

By contributing to the Orthogramic Metamodel, you agree that your contributions will be licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.

What This Means

Your contributions can be shared and adapted
Attribution will be given
Derivative works must use the same license
Commercial use is permitted

Getting Help

Stuck?

Check existing GitHub Issues
Ask in GitHub Discussions
Review similar merged PRs for examples

Questions About This Guide?

Open an issue with the label question or ask in Discussions.

Quick Reference

Common Commands

# Validate all schemas
npm run validate-schemas

# Build documentation locally
npm run docs:build

# Run local documentation server
npm run docs:start

# Run all tests
npm test

# Format code
npm run format

File Locations

Content Type	Location
Domain schemas	`/schemas/domains/`
Extension schemas	`/schemas/extensions/`
Documentation	`/`
Examples	`/examples/`
Tests	`/tests/`

Open Source Manifesto — Project philosophy
JSON Schema Index — Schema reference
Domain Attributes — Attribute reference

Ways to Contribute​

Getting Started​

1. Understand the Project​

2. Set Up Your Environment​

3. Find Something to Work On​

Contribution Workflow​

For Documentation Changes​

For Schema Changes​

Schema Standards​

Naming Conventions​

Required Schema Elements​

Property Guidelines​

Enum Conventions​

Documentation Standards​

MDX File Structure​

Writing Style​

Code Examples​

Pull Request Guidelines​

PR Title Format​

PR Description Template​

Review Process​

Issue Guidelines​

Bug Reports​

Feature Requests​

Community Guidelines​

Code of Conduct​

Communication Channels​

Response Times​

Recognition​

Contributors​

Types of Recognition​

Licensing​

Contribution License​

What This Means​

Getting Help​

Stuck?​

Questions About This Guide?​

Quick Reference​

Common Commands​

File Locations​

Related Documentation​