Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
140 lines (84 loc) · 7.43 KB

CONTRIBUTING.md

File metadata and controls

140 lines (84 loc) · 7.43 KB
Raw

Contributing to the FOCUS Working Group

This repository represents the written spec, not working code. As such, most people will not need any development environment; most of the work around the spec happens in regularly scheduled discussions and issues here in Github.

Thank you for your interest in contributing to the FinOps Open Cost and Usage Specification (FOCUS).
This repository contains the technical specification and supporting documentation for the FOCUS project under the FinOps Foundation.

Before contributing, please review the following guidelines carefully to ensure consistency and efficiency across all contributions.

1. Before You Start

  1. Join the FOCUS Project

    • If you’re not already a participant, visit the FOCUS Enrolment for instructions on how your company can join the FOCUS Open Standards Project. In addition, you must be approved by your company as a contributor to this project. You are required to complete the steps indicated in the README of the EasyCLA repository.
    • Only authorized contributors can submit or review Pull Requests.

  2. Get Familiar with the Project

2. Types of Contributions

You can contribute to this repository in several ways:

  • Action Items – Updates or follow-up tasks resulting from meetings.

  • Feature Requests – Proposals for new functionality, attributes, or examples.

  • Feedback – Comments or recommendations on existing content.

  • Maintenance – Fixes or updates for typos, structure, or metadata.

  • Work Items – Specific contributions tracked as GitHub issues.

If you are not sure where your contribution fits, open a Blank Issue first and request feedback before submitting a Pull Request (PR).

3. AI-Assisted Contributions

AI tools (such as GitHub Copilot, Claude Code, Cursor, and similar coding assistants) may be used to assist with FOCUS contributions. AI-generated content follows the same review standards as human-authored content.

Key requirements:

  • A CLA-covered human MUST take responsibility for all contributions
  • Approved AI agents MAY create PRs on behalf of a human who requested the work
  • The responsible human reviews and approves AI-generated contributions
  • AI-assisted contributions follow the same review process as other contributions, including peer review and consensus approval

For complete guidance, see AI Usage Guidelines.

4. Contribution Process

  1. Create a branch in this repository for your work. CLA-signed members have write access and should commit directly to a branch here, not a fork. This ensures GitHub Actions checks (PDF builds, PR status syncs) run on your PR, since repository secrets are not exposed to workflows triggered from forks.
git checkout -b <issue-number>-<short-description>

External contributors without write access may fork the repository instead. For branch naming conventions and further details on working with Git and GitHub, refer to the GitHub Guidelines.

  1. Reference existing issues or create a new one to track your change. Include the issue number in your PR title or description (e.g., Fixes #845).

  2. Follow FOCUS content conventions:

  • Use BCP-14 keywords (MUST, SHOULD, MAY, etc.) correctly.
  • Do not remove normative content without prior discussion.

See Typographic Conventions, (e.g., “for how to use BCP-14 keywords”).

  1. Submit your PR
  • Include a clear summary of the change.
  • Use one PR per logical change.
  • Assign appropriate labels (e.g., normative-change, editorial, discussion).

For details about labels and stages, see Git Issues - Project - Content Creation

  1. Participate in the review

  • Your PR will go through the following review sequence:

    • Maintainers / Task Force(s) → Members (for review and approval)

    • Be responsive to reviewer comments and requested edits.

  1. Writing Style and Format
  • Use the provided Markdown Editorial Guidelines for all specification text.
  • Follow the structure of existing sections (Introduction → Requirements → Examples → Notes).
  • Use RFC 2119 language for normative statements.

Visit Editorial Guidelines for further information.

  1. Normative vs Supporting Content
  • Normative content defines required behavior using MUST, SHALL, or SHOULD.
  • Supporting content explains context or provides examples.
  • If your contribution changes a normative rule, it will require review by the Task Force and Members before approval.
  1. Review and Approval Flow
Stage Responsible Group Description
1 Maintainers Broad alignment and quality assurance
2 Task Force Technical review and discussion of proposed change
3 Members Working Group Broad review and approval

Status changes and approvals are tracked in GitHub Issues and Pull Requests.

  1. Resources and References
  1. License and Intellectual Property

All contributions are made under the terms of the FOCUS Member Agreement, as stated in the LICENSE file.
By submitting a contribution, you agree that:

  • Your work complies with the project’s IPR and CLA requirements.
  • You have the rights to submit the content.
  • Contributions become part of the open FinOps FOCUS Specification.