Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
175 lines (120 loc) · 8.82 KB

CONTRIBUTING.md

File metadata and controls

175 lines (120 loc) · 8.82 KB

Contributing to llm-d-modelservice

Thank you for your interest in contributing to llm-d-modelservice! Community involvement is highly valued and crucial for the project's growth and success. This project accepts contributions via GitHub pull requests. This document outlines the process to help get your contribution accepted.

To ensure a clear direction and cohesive vision for the project, the project leads have the final decision on all contributions. However, these guidelines outline how you can contribute effectively.

How You Can Contribute

There are several ways you can contribute:

  • Reporting Issues: Help us identify and fix bugs by reporting them clearly and concisely.
  • Suggesting Features: Share your ideas for new features or improvements.
  • Improving Documentation: Help make the project more accessible by enhancing the documentation.
  • Submitting Code Contributions: Code contributions that align with the project's vision are always welcome.

Code of Conduct

This project adheres to the Code of Conduct and Covenant. By participating, you are expected to uphold this code.

Community and Communication

Local Development Setup

Before submitting a pull request, please make sure you have the following tools installed:

You can install these tools by:

# Install tools locally in PROJECT_DIR/bin directory
make tools
# Export PATH to use the locally installed tools directly
export PATH="$(pwd)/bin:$PATH"

Then run:

# After exporting PATH, you can use the tools directly
helm repo add bitnami https://charts.bitnami.com/bitnami
helm dependency update charts/llm-d-modelservice/
helm dependency build charts/llm-d-modelservice/

make verify

To test your local changes, you can preview the Kubernetes manifests that are generated by using Helm's dry run capability. For example:

helm template cpu-sim charts/llm-d-modelservice -f examples/values-cpu.yaml

Make sure that the repo you're templating against is your local chart (charts/llm-d-modelservice) and not an upstream chart (llm-d-modelservice/llm-d-modelservice).

Pre-commit

Set up pre-commit hooks to automatically run checks before each commit:

# Install pre-commit hooks
make pre-commit-install

This will install the pre-commit hooks defined in .pre-commit-config.yaml. The hooks will automatically run when you make commits and will help ensure code quality and consistency.

You can also run pre-commit manually on all files:

# Run pre-commit on all files
make pre-commit-run

Contributing Process

We follow a lazy consensus approach: changes proposed by people with responsibility for a problem, without disagreement from others, within a bounded time window of review by their peers, should be accepted.

Types of Contributions

1. Features with Public APIs or New Components

All features involving public APIs, behavior between core components, or new core subsystems must be accompanied by an approved project proposal.

Process:

  1. Create a pull request adding a proposal document under ./docs/proposals/ with a descriptive name
  2. Include these sections: Summary, Motivation (Goals/Non-Goals), Proposal, Design Details, Alternatives
  3. Get review from impacted component maintainers
  4. Get approval from project maintainers

2. Fixes, Issues, and Bugs

For changes that fix broken code or add small changes within a component:

  • All bugs and commits must have a clear description of the bug, how to reproduce, and how the change is made
  • Any other changes can be proposed in a pull request — a maintainer must approve the change
  • For moderate size changes, create an RFC issue in GitHub, then engage in Slack

Code Review Requirements

  • All code changes must be submitted as pull requests (no direct pushes)
  • All changes must be reviewed and approved by a maintainer other than the author
  • All repositories must gate merges on compilation and passing tests
  • All experimental features must be off by default and require explicit opt-in

Commit and Pull Request Style

  • Pull requests should describe the problem succinctly
  • Rebase and squash before merging
  • Use minimal commits and break large changes into distinct commits
  • Commit messages should have:
    • Short, descriptive titles
    • Description of why the change was needed
    • Enough detail for someone reviewing git history to understand the scope
  • DCO Sign-off: All commits must include a valid DCO sign-off line (Signed-off-by: Name <email@domain.com>)

Submitting a Pull Request

For every Pull Request submitted, ensure the following steps have been done:

  1. Sign your commits

  2. Sign-off your commits

  3. Run pre-commit hooks to ensure code quality and schema validation: make pre-commit-run

  4. Ensure that make lint passes to validate your changes

  5. Ensure that make verify passes to confirm generated examples are in sync

  6. Update the version number in the charts/llm-d-modelservice/Chart.yaml file using semantic versioning. Follow the X.Y.Z format so the nature of the changes is reflected in the chart.

    • X (major) is incremented for breaking changes,
    • Y (minor) is incremented when new features are added without breaking existing functionality,
    • Z (patch) is incremented for bug fixes, minor improvements, or non-breaking changes.

    If you modify the chart, please bump the chart version. You can run make bump-chart-version-patch to automatically increment the patch version. After updating the chart, run make lint to validate your changes.

  7. Lint tests have been run for the Chart using the Chart Testing tool and the make lint command.

Code Organization and Ownership

  • Components are the primary unit of code organization
  • Maintainers own components and approve changes
  • Contributors can become maintainers through sufficient evidence of contribution
  • Code ownership is reflected in OWNERS files consistent with Kubernetes project conventions

Security

See SECURITY.md for our vulnerability disclosure process.

API Changes and Deprecation

  • No breaking changes: Once an API/protocol is in GA release, it cannot be removed or behavior changed
  • Versioning: All protocols and APIs should be versionable with clear compatibility requirements
  • Documentation: All APIs must have documented specs describing expected behavior

FAQ and Troubleshooting

PR check make verify is failing

If make verify fails, review the error messages for details. If the failure is related to files under the examples directory being out of sync, you can run make generate to automatically update the generated code. After running make generate, re-run make verify to confirm the issue is resolved.

PR check Pre-commit / Pre-commit (pull_request) is failing

Please check the job logs for more information. This usually means you forgot to run make pre-commit-run before submitting your PR. Refer to the setup steps above. To avoid this in the future, ensure you have run make pre-commit-install to set up the pre-commit hooks.