Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
226 lines (156 loc) · 5.71 KB

CONTRIBUTING.md

File metadata and controls

226 lines (156 loc) · 5.71 KB

Contributing to Soul.md

Thank you for your interest in contributing to the Soul.md specification! This document provides guidelines for contributing.

Ways to Contribute

1. Report Issues

Found a bug, ambiguity, or inconsistency in the specification?

  1. Check existing issues to avoid duplicates
  2. Open a new issue with:
    • Title: Clear, concise description
    • Section reference: Which section(s) are affected
    • Description: What's wrong and why
    • Proposed fix: If you have one (optional)

Example issues:

  • Normative contradiction between Sections X and Y
  • Ambiguous wording in merge semantics
  • Missing cross-reference
  • Typo or formatting error

2. Propose Enhancements

Have an idea for a new feature or improvement?

  1. Start a discussion first
  2. Describe:
    • Use case: What problem does this solve?
    • Proposed solution: How would it work?
    • Alternatives considered: What else did you think about?
    • Impact: Breaking change? New optional feature?
  3. If consensus is reached, create an issue for tracking

Examples:

  • New optional field for a specific domain
  • Alternative merge strategy
  • Extension namespace proposal

3. Submit Pull Requests

Ready to fix an issue or implement an enhancement?

Before You Start

  • For small fixes (typos, formatting, clarifications): just submit a PR
  • For significant changes (new sections, breaking changes): discuss first (see above)

PR Guidelines

  1. Fork the repository
  2. Create a branch: git checkout -b fix/section-5-typo or feature/add-field-x
  3. Make changes:
    • Follow existing style and formatting
    • Update Table of Contents if adding/removing sections
    • Add/update examples if relevant
    • Keep changes focused (one issue per PR)
  4. Test:
    • Validate YAML examples
    • Check cross-references
    • Ensure numbering is correct
  5. Commit: Use clear, descriptive messages 
    Fix typo in Section 8.3

Changed "merege" to "merge" in Standard Merge rules.
  6. Submit PR with:
    • Title: Brief description
    • Description: What changed and why
    • Related issues: Link to issue(s) if applicable

Review Process

  • Maintainer will review within 1-2 weeks
  • May request changes or clarifications
  • Once approved, PR will be merged

4. Share Extensions

Implemented a useful extension for Soul.md?

  1. Document your extension:
    • Namespace (reverse-DNS)
    • Semantics and behavior
    • Example usage
    • Implementation notes
  2. Share in Discussions under "Extensions"
  3. Consider submitting for inclusion in a future RFC version

Example extensions:

  • Custom merge strategies
  • Advanced predicate languages for triggers
  • Provider-specific presentation hints

5. Provide Feedback

Used Soul.md in a real project?

  • Share your experience in Discussions
  • What worked well?
  • What was confusing or difficult?
  • What features are missing?

6. Create Tools

Built a validator, converter, or runtime loader?

  • Share it in Discussions under "Show and Tell"
  • Consider adding it to an "Ecosystem" list (TBD)

Example tools:

  • JSON Schema validator
  • YAML formatter
  • Soul.md → OpenAI system prompt converter
  • IDE plugin (syntax highlighting, autocomplete)

Specification Style Guide

General Principles

  1. RFC-style language: Use RFC 2119 keywords (MUST, SHOULD, MAY)
  2. Normative vs Non-normative: Clearly distinguish
    • Normative: defines required behavior
    • Non-normative: examples, guidance, rationale
  3. Clarity over brevity: Be precise, avoid ambiguity
  4. Examples: Provide concrete examples for complex features

Formatting

  • Sections: Use numbered sections (e.g., ## 5. Core Model)
  • Subsections: Use ### for major subsections, #### for minor
  • Code blocks: Use triple backticks with language hint (yaml)
  • Links: Use reference-style links for cross-references
  • Emphasis: code, bold, italic (sparingly)

Normative Language

Keyword Meaning
MUST / REQUIRED Mandatory requirement
MUST NOT Prohibited
SHOULD / RECOMMENDED Strong recommendation (deviation allowed with justification)
SHOULD NOT Strong discouragement
MAY / OPTIONAL Truly optional

Example Structure

## N. Feature Name

Brief overview.

### N.1 Field name (REQUIRED/OPTIONAL)

Type: string/int/enum/etc.

Description of field.

**Normative behavior:**

- Rule 1
- Rule 2

**Example:**

\`\`\`yaml
field: value
\`\`\`

Rationale: Why this design choice.

Code of Conduct

Our Pledge

We are committed to providing a welcoming and inclusive environment for all contributors.

Our Standards

Positive behaviors:

  • Respectful and constructive feedback
  • Focusing on what's best for the specification
  • Gracefully accepting constructive criticism
  • Showing empathy toward other contributors

Unacceptable behaviors:

  • Harassment, trolling, or insulting comments
  • Personal or political attacks
  • Publishing others' private information
  • Other conduct inappropriate in a professional setting

Enforcement

Violations may result in temporary or permanent ban from the project.

Report issues to: ecsiar@gmail.com

Questions?

Thank you for contributing to Soul.md! 🎉