Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
140 lines (104 loc) · 5.79 KB

CONTRIBUTING.md

File metadata and controls

140 lines (104 loc) · 5.79 KB
Raw

Contributing to ORC

Welcome! We're glad you're interested in contributing to openstack-resource-controller (ORC). Whether you're fixing a bug, adding a new controller, reviewing code, or improving documentation, your help is greatly appreciated.

Types of Contributions

There are many ways to contribute to ORC:

  • Bug fixes: Check the open issues for reported bugs. If you find a bug that isn't tracked yet, please open an issue.

  • New OpenStack resource controllers: ORC aims to cover all OpenStack APIs that can be expressed declaratively. If a resource you need isn't supported yet (see the supported resources), consider implementing a controller for it. The developing controllers guide will help you get started.

  • Code reviews: Reviewing open pull requests is a valuable contribution. Fresh eyes catch bugs, improve code quality, and help contributors learn from each other.

  • Documentation: Improvements to the website docs, code comments, and this repository's documentation are always welcome.

  • Tests: We value good test coverage. This includes unit tests, API validation tests, and kuttl end-to-end tests. See Writing Tests for what's expected.

If you're unsure where to start, look for issues labelled as good first issues, or ask on Slack.

Communication

  • Slack: Join us on Kubernetes Slack in #gophercloud. Visit slack.k8s.io for an invitation.
  • GitHub Issues: For bug reports, feature requests, and design discussions.

Setting Up a Development Environment

Follow the local development quickstart to set up a kind cluster, DevStack, and run ORC from source. The developer guide covers the controller architecture and how all the pieces fit together.

Submitting Changes

Before you start

For non-trivial changes, we recommend opening a GitHub issue first to discuss the approach. This avoids spending time on work that may need a different direction.

For bug fixes, please ensure a GitHub issue exists before submitting a PR, even for small fixes. Having a tracking issue makes it easier to reference the bug in commit messages, changelogs, and future discussions.

For significant new features or architectural changes, please submit an enhancement proposal and get it approved before starting implementation.

Workflow

  1. Fork the repository and create a feature branch from main.
  2. Make your changes. Follow the coding standards.
  3. Run checks locally before pushing: 
    make generate   # Required after API type changes
make lint       # Run linters
make test       # Run unit tests
  4. Open a pull request with a clear description of what you changed and why. Reference any related issue.
  5. CI must pass: GitHub Actions runs tests and linting on every PR.
  6. Address review feedback: At least one maintainer review is required before merging. Please be responsive to feedback.
  7. Keep a clean history: During review, push fixups as separate commits so reviewers can see what changed between rounds. Rebase them into the correct commits before merging.

Contributing New Controllers

New controllers tend to produce large PRs. To keep them reviewable and easy to update when tooling or conventions change, follow the commit structure, incremental PR, and deferred mutability guidelines in the developer documentation.

AI-Assisted Contributions

Using AI tools (LLMs, coding assistants, etc.) to help write code is fine. However:

  • Authors are responsible for the code they submit. Review, understand, and test AI-generated code before committing it. The author of a commit is accountable for its correctness, not the tool that helped produce it.
  • Authorship: The human contributor must be the commit author. You may optionally add the AI tool as a Co-authored-by trailer, but there is no requirement to use Assisted-by, Generated-by, or similar labels.
  • Autonomous agents: Fully autonomous AI agents (e.g. those that open PRs without direct human involvement) must clearly identify themselves as such in the PR description.

Becoming a Maintainer

Maintainership is informal and invite-based. There is no formal ladder, but the general progression looks like:

  1. First-time contributor: You submit your first PR and get it merged.
  2. Regular contributor: You contribute consistently over time, be it code, reviews, helping others on Slack or in issues.
  3. Invited maintainer: Existing maintainers invite new maintainers based on demonstrated trust, domain knowledge, and sustained engagement with the project.

The best way to move along this path is to show up consistently: write high-quality code, review others' PRs thoughtfully, and help the community.

License

ORC is licensed under the Apache License 2.0. By contributing to this project, you agree that your contributions will be made under the same license.