Thank you for your interest in contributing to the Instrumentation Score Specification! This document provides guidelines for contributing to the project.
- Getting Started
- Ways to Contribute
- Contributing to the Specification
- Contributing Rules
- Submitting Changes
- Communication
- Code of Conduct
The Instrumentation Score Specification defines a standardized metric for assessing OpenTelemetry instrumentation quality. Before contributing, please:
- Read the specification: Review the main specification.md document
- Understand the goals: Familiarize yourself with the project's objectives and scope
- Join the community: Connect with us on CNCF Slack #instrumentation-score
- Review existing issues: Check GitHub Issues for current discussions
We welcome various types of contributions:
- Improve specification clarity and completeness
- Fix typos, grammar, and formatting
- Add examples and use cases
- Enhance explanations of concepts
- Propose new scoring rules
- Improve existing rule definitions
- Provide rationale for rule changes
- Contribute rule validation examples
- Report ambiguities or gaps in the specification
- Suggest improvements to existing rules
- Identify inconsistencies or contradictions
- Suggest new features or capabilities
- Propose extensions to the scoring framework
- Share implementation experiences and feedback
- Provide research on instrumentation best practices
- Share data on real-world instrumentation patterns
- Contribute analysis of scoring effectiveness
The main specification is organized into these key sections:
- Introduction: Project overview and goals
- Prior Art: Learning from existing scoring systems
- Goals and Non-Goals: Project scope definition
- Detailed Specification: Core technical specification
- Score Calculation: Mathematical framework
- Rule Structure: How rules are defined and applied
- Small Changes: For minor fixes (typos, clarifications), submit a pull request directly
- Significant Changes: For major modifications, start with an issue to discuss the proposal
- Clarity: Write clearly and avoid ambiguous language
- Completeness: Ensure all concepts are fully defined
- Consistency: Maintain consistent terminology throughout
- Implementability: Ensure the specification can be practically implemented
- Vendor Neutrality: Avoid favoring specific tools or vendors
Rules are the core mechanism for calculating instrumentation scores. They are located in the rules/ directory.
Each rule must include:
- ID: Unique identifier (e.g., RES-001, SPAN-042)
- Description: Clear, human-readable explanation
- Rationale: Why this rule matters for instrumentation quality
- Criteria: Specific, objective conditions for rule application
- Target: Which OTLP element it applies to (Resource, TraceSpan, Metric, Log)
- Impact: Impact level (Critical, Important, Normal, Low)
- Objective: Rules must be measurable and unambiguous
- Based on Standards: Align with OpenTelemetry Semantic Conventions
- Well-Justified: Include clear rationale for the rule's importance
- Implementable: Ensure rules can be consistently implemented across tools
- Tested: Provide examples of when the rule should and shouldn't trigger
- Research: Ensure the rule aligns with OpenTelemetry best practices
- Issue First: Create an issue describing the proposed rule
- Community Input: Allow time for community discussion
- Implementation: Submit a pull request with the complete rule definition
- Fork the Repository: Create your own fork of the project
- Create a Branch: Use a descriptive branch name (e.g.,
add-service-version-rule) - Make Changes: Implement your changes with clear, focused commits
- Test: Ensure your changes don't break existing content
- Submit PR: Create a pull request with a clear description
- Title: Use a clear, descriptive title, following conventional commits
- Description: Explain what changes you made and why
- Scope: Keep PRs focused on a single issue or feature
- Documentation: Update related documentation as needed
Use clear, descriptive commit messages:
feat: add rule for missing `service.version` attribute
- Defines RES-002 rule for service.version presence
- Categorized as "Important" impact
- Includes rationale and implementation criteria
- GitHub Issues: For specific problems, proposals, and bugs
- CNCF Slack: Join #instrumentation-score for real-time discussion
- Pull Requests: For code and documentation review discussions
If you need assistance:
- Check existing documentation and issues
- Ask questions in the CNCF Slack channel
- Create a GitHub issue with the "question" label
- Reach out to the maintainers directly
We hold regular community meetings to discuss:
- Project roadmap and priorities
- Rule proposals and changes
- Implementation feedback
- Community questions and concerns
Meeting details will be announced in the CNCF Slack channel and GitHub discussions.
This project follows the CNCF Code of Conduct. By participating, you agree to uphold this code. Please report unacceptable behavior to the project maintainers.
- Inclusive: Welcome contributors from all backgrounds
- Respectful: Treat everyone with respect and professionalism
- Collaborative: Work together constructively
- Constructive: Provide helpful, actionable feedback
Contributors are recognized in several ways:
- Contributors are listed in project documentation
- Significant contributors may be invited to become maintainers
- Community achievements are highlighted in project communications
If you have questions about contributing, please:
- Join our CNCF Slack channel
- Create a GitHub issue with the "question" label
- Review the governance document for project structure
Thank you for contributing to the Instrumentation Score Specification!