|
| 1 | +# Contribution Guidelines |
| 2 | + |
| 3 | +- [Ways to contribute](#ways-to-contribute) |
| 4 | + - [Report Security Vulnerabilities](#report-security-vulnerabilities) |
| 5 | + - [File issues](#file-issues) |
| 6 | + - [Find something to work on](#find-something-to-work-on) |
| 7 | +- [Community Assignments](#community-assignments) |
| 8 | + - [Assignment Process](#assignment-process) |
| 9 | + - [Stale Assignment Policy](#stale-assignment-policy) |
| 10 | + - [Best Practices for Assignees](#best-practices-for-assignees) |
| 11 | +- [Contributing code](#contributing-code) |
| 12 | + - [Small changes (bug fixes)](#small-changes-bug-fixes) |
| 13 | + - [Large changes (features, refactors)](#large-changes-features-refactors) |
| 14 | + - [Tips to get started](#tips-to-get-started) |
| 15 | +- [Requirements for PRs](#requirements-for-prs) |
| 16 | + - [DCO](#dco) |
| 17 | + - [Testing](#testing) |
| 18 | + - [Unit Tests](#unit-tests) |
| 19 | + - [End-to-End (E2E) Tests](#end-to-end-e2e-tests) |
| 20 | + - [Code review guidelines](#code-review-guidelines) |
| 21 | +- [Documentation](#documentation) |
| 22 | +- [Get in touch](#get-in-touch) |
| 23 | + |
| 24 | +## Ways to contribute |
| 25 | + |
| 26 | +Thanks for your interest in contributing to kagent! We have a few different ways you can get involved. To understand contributor roles, refer to the [contributor ladder guide](https://github.com/kagent-dev/community/blob/main/CONTRIBUTOR_LADDER.md). |
| 27 | + |
| 28 | +### Report Security Vulnerabilities |
| 29 | + |
| 30 | +If you would like to report a security issue, please refer to our [SECURITY.md](SECURITY.md) file. |
| 31 | + |
| 32 | +### File issues |
| 33 | + |
| 34 | +To file a bug or feature request in the [kagent GitHub repo](https://github.com/kagent-dev/kagent): |
| 35 | + |
| 36 | +1. Search existing issues first. |
| 37 | +2. If no existing issue addresses your case, create a new one. |
| 38 | +3. Use [issue templates](https://github.com/kagent-dev/kagent/tree/main/.github/ISSUE_TEMPLATE) when available |
| 39 | +4. Add information or react to existing issues, such as a thumbs-up 👍 to indicate agreement. |
| 40 | + |
| 41 | +### Find something to work on |
| 42 | + |
| 43 | +The project uses [GitHub issues](https://github.com/kagent-dev/kagent/issues) to track bugs and features. Issues labeled with the [`good first issue`](https://github.com/kagent-dev/kagent/issues?q=state%3Aopen%20label%3A%22good%20first%20issue%22) label are a great place to start. |
| 44 | + |
| 45 | +Additionally, the project has a [project board](https://github.com/orgs/kagent-dev/projects/3) tracking the roadmap. Any issues in the project board are a great source of things to work on. If an issue has not been assigned, you can ask to work on it by leaving a comment on the issue. |
| 46 | + |
| 47 | +Flaky tests are a common source of issues and a good place to start contributing to the project. You can find these issues by filtering with the `Type: CI Test Flake` label. If you see a test that is failing regularly, you can leave a comment asking if someone is working on it. |
| 48 | + |
| 49 | +## Community Assignments |
| 50 | + |
| 51 | +We welcome community contributions and encourage members to work on issues. To maintain an active and healthy development environment, we have the following policies: |
| 52 | + |
| 53 | +### Assignment Process |
| 54 | + |
| 55 | +- **Organization members**: Can self-assign issues using the GitHub assignee dropdown |
| 56 | +- **External contributors**: Should comment on the issue expressing interest in working on it. A maintainer will then assign the issue to you. |
| 57 | + |
| 58 | +### Stale Assignment Policy |
| 59 | + |
| 60 | +- **Timeframe**: If an assignee hasn't made any visible progress (comments, commits, or draft PRs) within **30 days** of assignment, the issue assignment may be considered stale |
| 61 | +- **Communication**: We'll reach out to check on progress and offer assistance before unassigning |
| 62 | +- **Unassignment**: After **5 additional days** without response or progress, issues will be unassigned and made available for other contributors |
| 63 | +- **Re-assignment**: Previous assignees are welcome to request re-assignment if they become available to work on the issue again |
| 64 | + |
| 65 | +### Best Practices for Assignees |
| 66 | + |
| 67 | +- Comment on the issue with your approach or ask questions if you need clarification |
| 68 | +- Provide regular updates (even brief ones) if work is taking longer than expected |
| 69 | +- Create draft PRs early to show progress and get feedback |
| 70 | +- Don't hesitate to ask for help in the issue comments or community channels like Discord or CNCF Slack |
| 71 | +- Join the community meetings to share progress or engage with other members for discussions |
| 72 | + |
| 73 | +## Contributing code |
| 74 | + |
| 75 | +Contributing features to kagent is a great way to get involved with the project. We welcome contributions of all sizes, from small bug fixes to large new features. Kagent uses a "fork and pull request" approach. This means that as a contributor, you create your own personal fork of a code repository in GitHub and push your contributions to a branch in your own fork first. When you are ready to contribute, open a pull request (PR) against the project's repository. For more details, see the [GitHub docs about working with forks](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks). |
| 76 | + |
| 77 | +### Small changes (bug fixes) |
| 78 | + |
| 79 | +For small changes (less than 100 lines of code): |
| 80 | + |
| 81 | +1. Open a pull request. |
| 82 | +2. Ensure tests verify the fix. |
| 83 | +3. If needed, [update the documentation](#documentation). |
| 84 | + |
| 85 | +### Large changes (features, refactors) |
| 86 | + |
| 87 | +Large features often touch many files, extend many lines of code, and often cover issues such as: |
| 88 | + |
| 89 | +* Large bug fixes |
| 90 | +* New features |
| 91 | +* Refactors of the existing codebase |
| 92 | + |
| 93 | +For large changes: |
| 94 | + |
| 95 | +1. **Open an issue first**: Open an issue about your bug or feature in the [kagent](https://github.com/kagent-dev/kagent) repo. |
| 96 | +2. **Message us on Slack or Discord**: Reach out to us to discuss your proposed changes in our [CNCF Slack channel, `#kagent-dev`](https://cloud-native.slack.com/archives/C08ETST0076) or [Discord server](https://discord.gg/Fu3k65f2k3). |
| 97 | +3. **Agree on implementation plan**: Write a plan for how this feature or bug fix should be implemented. Should this be one pull request or multiple incremental improvements? Who is going to do each part? Discuss it with us on Slack/Discord or join our [community meeting](https://calendar.google.com/calendar/u/0?cid=Y183OTI0OTdhNGU1N2NiNzVhNzE0Mjg0NWFkMzVkNTVmMTkxYTAwOWVhN2ZiN2E3ZTc5NDA5Yjk5NGJhOTRhMmVhQGdyb3VwLmNhbGVuZGFyLmdvb2dsZS5jb20). |
| 98 | +4. **Submit a draft PR**: It's important to get feedback as early as possible to ensure that any big improvements end up being merged. Open a draft pull request from your fork, label it `work in progress`, and start getting feedback. |
| 99 | +5. **Review**: At least one maintainer should sign off on the change before it's merged. Look at the following [Code review](#code-review-guidelines) section to learn about what we're looking for. |
| 100 | +6. **Close out**: A maintainer will merge the PR and let you know about the next release plan. |
| 101 | + |
| 102 | +For large or broad changes, we may ask you to write an enhancement proposal. Use [this template](https://github.com/kagent-dev/kagent/blob/main/design/template.md) to get you started. You can find the existing enhancement proposals [here](https://github.com/kagent-dev/kagent/tree/main/design). |
| 103 | + |
| 104 | +### Tips to get started |
| 105 | + |
| 106 | +To help you get started with contributing code: |
| 107 | + |
| 108 | +- **Development Setup**: See the [DEVELOPMENT.md](DEVELOPMENT.md) file for detailed instructions on setting up your development environment. |
| 109 | +- **Code of Conduct**: Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md). |
| 110 | +- **Past PRs**: We recommend looking at past PRs that are doing similar things to what you are trying to do. |
| 111 | +- **Agent Examples**: Check out the [sample agents](https://github.com/kagent-dev/kagent/tree/main/python/samples) for examples of how to build agents. |
| 112 | +- **Architecture**: Review the [architecture documentation](https://github.com/kagent-dev/kagent#architecture) to understand how kagent works. |
| 113 | + |
| 114 | +## Requirements for PRs |
| 115 | + |
| 116 | +Contributing to open source can be a daunting task, especially if you are a new contributor and are not yet familiar with the workflows commonly used by open source projects. |
| 117 | + |
| 118 | +After you open a PR, the project maintainers will review your changes. Reviews typically include iterations of suggestions and changes. This is totally normal, so don't be discouraged if asked to make changes to your contribution. |
| 119 | + |
| 120 | +It's difficult to cover all the possible scenarios that you might encounter when contributing to open source software in a single document. However, this contributing guide outlines several requirements that even some well-versed contributors may not be familiar with. If you have questions, concerns or just need help getting started please don't hesitate to reach out through one of the channels covered in the [Get in touch section](#get-in-touch). |
| 121 | + |
| 122 | +### DCO |
| 123 | + |
| 124 | +DCO, short for Developer Certificate of Origin, is a per-commit signoff that you, the contributor, agree to the terms published at [https://developercertificate.org](https://developercertificate.org) for that particular commit. This will appear as a `Signed-off-by: Your Name <your.email>` trailer at the end of each commit message. The kagent project requires that every commit contains this DCO signoff. |
| 125 | + |
| 126 | +The easiest way to make sure each of your commits contains the signoff is to run make `init-git-hooks` in the repo to which you are contributing. This will configure your repo to use a Git hook which will automatically add the required trailer to all of your commit messages. |
| 127 | + |
| 128 | +```shell |
| 129 | +make init-git-hooks |
| 130 | +``` |
| 131 | + |
| 132 | +If you prefer not to use a Git hook, you must remember to use the `--signoff` option (or `-s` for short) on each of your commits when you check in code: |
| 133 | + |
| 134 | +```shell |
| 135 | +git commit -s -m "description of my excellent contribution" |
| 136 | +``` |
| 137 | + |
| 138 | +If you forget to sign off on a commit, your PR will be flagged and blocked from merging. You can sign off on previous commits by using the rebase command. The following example uses the `main` branch, which means this command rewrites the `git` history of your current branch while adding signoffs to commits visible from `main` (not inclusive). Please be aware that rewriting commit history does carry some risk, and if the commits you are rewriting are already pushed to a remote, you will need to force push the rewritten history. |
| 139 | + |
| 140 | +```shell |
| 141 | +git rebase --signoff main |
| 142 | +``` |
| 143 | + |
| 144 | +### Testing |
| 145 | + |
| 146 | +Tests are essential for any non-trivial PR. They ensure that your feature remains operational and does not break due to future updates. Tests are a critical part of maintaining kagent's stability and long-term maintainability. |
| 147 | + |
| 148 | +A useful way to explore the different tests that the project maintains, is to inspect the [GitHub action that runs the CI pipeline](.github/workflows/ci.yaml) |
| 149 | + |
| 150 | +We have the following types of tests: |
| 151 | + |
| 152 | +#### Unit Tests |
| 153 | + |
| 154 | +These are useful for testing small, isolated units of code, such as a single function or a small component. |
| 155 | + |
| 156 | +**Go Unit Tests**: |
| 157 | + |
| 158 | +```bash |
| 159 | +cd go |
| 160 | +go test -race -skip 'TestE2E.*' -v ./... |
| 161 | +``` |
| 162 | + |
| 163 | +**Helm Unit Tests**: |
| 164 | + |
| 165 | +```bash |
| 166 | +helm plugin install https://github.com/helm-unittest/helm-unittest |
| 167 | +make helm-version |
| 168 | +helm unittest helm/kagent |
| 169 | +``` |
| 170 | + |
| 171 | +**Python Unit Tests**: |
| 172 | + |
| 173 | + ```bash |
| 174 | +cd python |
| 175 | +uv run pytest ./packages/**/tests/ |
| 176 | + ``` |
| 177 | + |
| 178 | +**UI Unit Tests**: |
| 179 | + |
| 180 | + ```bash |
| 181 | +cd ui |
| 182 | +npm run test |
| 183 | +``` |
| 184 | + |
| 185 | +#### End-to-End (E2E) Tests |
| 186 | + |
| 187 | +These tests are done in a `kind` cluster with real agents, using real or mock LLM providers. |
| 188 | +See: [go/test/e2e](https://github.com/kagent-dev/kagent/tree/main/go/test/e2e) |
| 189 | + |
| 190 | +Features that introduce behavior changes should be covered by E2E tests (exceptions can be made for minor changes). Testing with real Kubernetes resources and agent invocations is crucial because it: |
| 191 | + |
| 192 | +- Prevents regressions. |
| 193 | +- Detects behavior changes from dependencies. |
| 194 | +- Ensures the feature is not deprecated. |
| 195 | +- Confirms the feature works as the user expects it to. |
| 196 | + |
| 197 | +### Code review guidelines |
| 198 | + |
| 199 | +Code can be reviewed by anyone! Even if you are not a maintainer, please feel free to add your comments. |
| 200 | +All code must be reviewed by at least one [maintainer](https://github.com/kagent-dev/community/blob/main/MAINTAINERS.md) before merging. Key requirements: |
| 201 | + |
| 202 | +1. **Code Style** |
| 203 | + |
| 204 | + **Go Code**: |
| 205 | + - Follow [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments). |
| 206 | + - Follow [Effective Go](https://golang.org/doc/effective_go). |
| 207 | + - Run `make lint` to check for common issues before submitting. |
| 208 | + |
| 209 | + **Python Code**: |
| 210 | + - Follow PEP 8 style guidelines. |
| 211 | + - Run `make lint` to check for common issues before submitting. |
| 212 | + |
| 213 | + **UI Code**: |
| 214 | + - Follow the project's ESLint configuration. |
| 215 | + - Run `npm run lint` before submitting. |
| 216 | + |
| 217 | +2. **Testing** |
| 218 | + |
| 219 | + - Add unit tests for new functionality. |
| 220 | + - Ensure existing tests pass. |
| 221 | + - Include e2e tests when needed. |
| 222 | + |
| 223 | +3. **Documentation** |
| 224 | + |
| 225 | + - Update relevant documentation. |
| 226 | + - Include code comments for non-obvious logic. |
| 227 | + - Update API documentation if changing interfaces. |
| 228 | + - Add examples for new features. |
| 229 | + |
| 230 | +## Documentation |
| 231 | + |
| 232 | +The kagent documentation lives at [kagent.dev/docs](https://kagent.dev/docs/kagent). The code lives at [kagent website](https://github.com/kagent-dev/website). |
| 233 | + |
| 234 | +## Get in touch |
| 235 | + |
| 236 | +Please refer to the [Project README](README.md#get-involved) for methods to get in touch |
0 commit comments