docs: add contributing guide with issue policy

CONTRIBUTING.md

@@ -1,28 +1,128 @@
 # Contributing
 
-For general Kuadrant contribution guidance, see the [Kuadrant contributing guide](https://kuadrant.io/contributing/).
+For general contribution guidelines, PR requirements, and issue triage rules, see the [Kuadrant contributing guide](https://github.com/Kuadrant/.github/blob/main/CONTRIBUTING.md).
 
-This document covers the automated governance rules enforced in this repository and the project-specific workflow for getting a contribution merged.
+## Issue Policy
 
-## Issue Triage
+**Do not start work on an issue unless it has been assigned to you by a maintainer.**
 
-All new issues are automatically labelled `triage/needs-triage`. A maintainer will review and move the issue to `triage/accepted` once it has been discussed and prioritised.
+Issues go through a triage and planning process before they are ready for contribution. Working on unassigned issues — whether manually or via AI coding agents — wastes your time and ours.
 
-| Label | Meaning |
-|---|---|
-| `triage/needs-triage` | New issue, awaiting maintainer review |
-| `triage/accepted` | Reviewed, prioritised, and ready for work |
+**Pull requests submitted against unassigned issues will be automatically closed and will not be reopened.**
 
-Only Kuadrant org members can change triage labels. If a non-member attempts to add or remove a triage label, the change is automatically reverted.
+If you're interested in contributing to an issue, leave a comment and wait for a maintainer to assign it to you before starting any work.
 
-## Pull Request Requirements
+Issues labelled `maintainers-only` are reserved for the maintainer team and are not available for external contribution.
 
-Every PR from an external contributor must:
+## Contributions
 
-1. **Link to an issue** — use `Fixes #123` or `Closes #123` in the PR description, or link it via the GitHub sidebar.
-2. **Link to a triaged issue** — the linked issue must carry the `triage/accepted` label before the PR is opened.
-3. **Not duplicate existing work** — if another contributor already has an open PR for the same issue, your PR will be auto-drafted until that one is resolved.
+We welcome code and non-code contributions to our project. Non-code contributions can come in the form of documentation updates, bug reports, enhancement requests, and feature requests.
 
-PRs that do not meet these requirements are automatically closed with an explanatory comment. Your branch is kept intact, so you can reopen once the requirements are satisfied.
+### Finding Issues to Work On
 
-This enforcement is implemented by the [Kuadrant contributor governance workflow](https://github.com/Kuadrant/.github/blob/main/.github/workflows/contributor-governance.yml), called from [`.github/workflows/contributor-governance.yml`](.github/workflows/contributor-governance.yml) in this repo.
+The best place to start is to look through our issues for [bugs](https://github.com/Kuadrant/developer-portal-controller/issues?q=is%3Aopen+is%3Aissue+label%3Akind%2Fbug) and [good first issues](https://github.com/Kuadrant/developer-portal-controller/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22). These are a great starting point for new contributors.
+
+Remember: only work on issues that are `triage/accepted` and assigned to you.
+
+### Bug Reporting
+
+If you found a bug, please submit an [issue](https://github.com/Kuadrant/developer-portal-controller/issues/new) describing the problem. Include:
+
+- Steps to reproduce the bug
+- The Kubernetes/OpenShift version you are running
+- CRD versions installed
+- Any relevant logs
+
+### Enhancement Requests
+
+If you want an enhancement of a feature or workflow, submit an [issue](https://github.com/Kuadrant/developer-portal-controller/issues/new) describing the enhancement. Include:
+
+- What you are wanting to see improved
+- The current behavior
+- The new behavior you wish to see
+
+### Feature Requests
+
+If you want to see a new feature, file an [issue](https://github.com/Kuadrant/developer-portal-controller/issues/new) detailing the new feature. Include:
+
+- What you are trying to achieve with the new feature
+- What you will need
+- Any relevant documentation or information on the new feature
+
+### Documentation
+
+If there is documentation that is unclear or could use some improvements, please raise an issue or submit a pull request.
+
+### Pull Requests
+
+If you want to submit code changes to the project, here are some guidelines:
+
+1. **Create a Branch**
+
+   ```bash
+   git checkout -b your-feature-branch
+   ```
+
+2. **Implement Your Changes**
+
+   Make your code changes, ensuring that you follow the project's coding standards and best practices.
+
+   If you modify API types in `api/v1alpha1/*_types.go`, regenerate code and CRDs:
+
+   ```bash
+   make manifests generate
+   ```
+
+3. **Testing**
+
+   Ensure all tests pass before committing.
+
+   ```bash
+   make test                       # run unit tests with coverage
+   make test-e2e                   # run e2e tests (creates/deletes Kind cluster)
+   go test ./internal/controller -v  # run controller tests only
+   ```
+
+4. **Linting and Formatting**
+
+   Ensure your code passes linting and formatting checks.
+
+   ```bash
+   make fmt                        # run go fmt
+   make vet                        # run go vet
+   make lint                       # run golangci-lint
+   ```
+
+5. **Ensure CI Passes**
+
+   Your contributions will need to pass the Continuous Integration (CI) tests for pull requests.
+
+6. **Commit Changes**
+
+   Use meaningful commit messages following the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+
+   ```bash
+   git commit -m "feat: add new feature"
+   ```
+
+7. **Push to Your Fork**
+
+   ```bash
+   git push origin your-feature-branch
+   ```
+
+8. **Open a Pull Request**
+
+   Go to the original repository and click on **New Pull Request**. Provide a clear description of your changes, including any issues your PR fixes, acceptance criteria, and any special notes to the reviewers.
+
+## Commit Messages
+
+Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+- `feat`: A new feature.
+- `fix`: A bug fix.
+- `docs`: Documentation changes.
+- `style`: Code style changes (formatting, missing semi-colons, etc.).
+- `refactor`: Code changes that neither fix a bug nor add a feature.
+- `test`: Adding or correcting tests.
+- `chore`: Changes to the build process or auxiliary tools.