mirror of
https://github.com/netbirdio/docs.git
synced 2026-10-17 02:59:04 +02:00
Contributors Guide
This commit is contained in:
PizzaLovingNerd
@@ -1,42 +1,39 @@
|
||||
# The NetBird documentation
|
||||
|
||||
This repository contains assets required to build the [documentation website for NetBird](https://docs.netbird.io/). It is built using [Next.js](https://nextjs.org/) with MDX support, a modern React framework for building static and dynamic websites.
|
||||
This repository builds [docs.netbird.io](https://docs.netbird.io/) with Next.js and MDX.
|
||||
|
||||
We're glad that you want to contribute!
|
||||
## Work on the docs locally
|
||||
|
||||
- [Contributing to the docs](#contributing-to-the-docs)
|
||||
Use Node.js 20.9 or newer. Install the versions pinned in `package-lock.json`:
|
||||
|
||||
### Requirements
|
||||
* node 16
|
||||
* npm 8+
|
||||
|
||||
### Installation
|
||||
|
||||
```
|
||||
$ npm install
|
||||
```bash
|
||||
npm ci
|
||||
```
|
||||
|
||||
### Local Development
|
||||
Start the development server:
|
||||
|
||||
```
|
||||
$ npm run dev
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
|
||||
Before opening a pull request, run the checks used by docs CI:
|
||||
|
||||
```bash
|
||||
npm run lint:mdx
|
||||
npm run build
|
||||
```
|
||||
|
||||
CI also runs Codespell. If you change JSX, JavaScript, navigation, or a component, run `npm run lint` and make sure your change introduces no new findings.
|
||||
|
||||
## Contributing to the docs
|
||||
|
||||
You can click the **Fork** button in the upper-right area of the screen to create a copy of this repository in your GitHub account. This copy is called a _fork_. Make any changes you want in your fork, and when you are ready to send those changes to us, go to your fork and create a new pull request to let us know about it.
|
||||
Fork the repository and create a focused branch from the current `main` branch. Keep the pull request limited to one problem, explain how you verified the change, and include screenshots for layout or interaction changes.
|
||||
|
||||
Once your pull request is created, a NetBird reviewer will take responsibility for providing clear, actionable feedback. As the owner of the pull request, **it is your responsibility to modify your pull request to address the feedback that has been provided to you by the NetBird reviewer.**
|
||||
|
||||
Also, note that you may end up having more than one NetBird reviewer provide you feedback or you may end up getting feedback from a NetBird reviewer that is different than the one initially assigned to provide you feedback.
|
||||
|
||||
Furthermore, in some cases, one of your reviewers might ask for a technical review from a NetBird author when needed. Reviewers will do their best to provide feedback in a timely fashion but response time can vary based on circumstances.
|
||||
For the full workflow, start with [Contribute to NetBird](src/pages/contribute/index.mdx). The guide also covers the [repository map](src/pages/contribute/repositories.mdx), [local development and test safety](src/pages/contribute/development.mdx), [pull request review](src/pages/contribute/pull-requests.mdx), and [security and contribution policies](src/pages/contribute/policies.mdx).
|
||||
|
||||
## Code of conduct
|
||||
|
||||
Participation in the NetBird community is governed by the [NetBirds' Code of Conduct](https://github.com/netbirdio/netbird/blob/main/CODE_OF_CONDUCT.md).
|
||||
Participation in the NetBird community is governed by the [NetBird Code of Conduct](https://github.com/netbirdio/netbird/blob/main/CODE_OF_CONDUCT.md).
|
||||
|
||||
## Components and Use
|
||||
|
||||
@@ -54,7 +51,7 @@ import {Note} from "@/components/mdx"
|
||||
|
||||
<Note>
|
||||
NetBird is an **[open-source](https://github.com/netbirdio/netbird)** project and can be self-hosted.
|
||||
See a comparison between the self-hosted and cloud-hosted versions [here](/selfhosted/self-hosted-vs-cloud-netbird).
|
||||
Compare the [self-hosted and cloud-hosted versions](/about-netbird/self-hosted-vs-cloud).
|
||||
</Note>
|
||||
```
|
||||
|
||||
@@ -65,7 +62,7 @@ Displays warning content with a red theme:
|
||||
import {Warning} from "@/components/mdx"
|
||||
|
||||
<Warning>
|
||||
The API is still in Beta state so some errors might not be handled properly yet.
|
||||
Do not include setup keys, tokens, or unredacted logs in a public issue.
|
||||
</Warning>
|
||||
```
|
||||
|
||||
@@ -223,18 +220,20 @@ Displays small status badges:
|
||||
```mdx
|
||||
import {Badge} from "@/components/mdx"
|
||||
|
||||
<Badge>New</Badge>
|
||||
<Badge variant="secondary">Beta</Badge>
|
||||
<Badge status="info" text="New" />
|
||||
<Badge status="experimental" text="Beta" hoverText="This feature may change." />
|
||||
```
|
||||
|
||||
`status` accepts `default`, `info`, or `experimental`. Set the visible label with `text`; use `hoverText` only when the badge needs a short explanation.
|
||||
|
||||
#### Code Blocks
|
||||
Code syntax highlighting (automatically available):
|
||||
|
||||
```mdx
|
||||
\`\`\`bash
|
||||
````mdx
|
||||
```bash
|
||||
npm install
|
||||
npm run dev
|
||||
\`\`\`
|
||||
```
|
||||
|
||||
// Or use code groups for multiple languages
|
||||
<CodeGroup>
|
||||
@@ -245,7 +244,7 @@ npm run dev
|
||||
yarn install
|
||||
```
|
||||
</CodeGroup>
|
||||
```
|
||||
````
|
||||
|
||||
## Thank you
|
||||
|
||||
|
||||
@@ -1011,6 +1011,28 @@ export const docsNavigation = [
|
||||
{ title: 'Homelab', href: '/use-cases/homelab' },
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'CONTRIBUTE',
|
||||
links: [
|
||||
{ title: 'Contribute to NetBird', href: '/contribute' },
|
||||
{
|
||||
title: 'Find a Repository',
|
||||
href: '/contribute/repositories',
|
||||
},
|
||||
{
|
||||
title: 'Build and Test',
|
||||
href: '/contribute/development',
|
||||
},
|
||||
{
|
||||
title: 'Pull Requests',
|
||||
href: '/contribute/pull-requests',
|
||||
},
|
||||
{
|
||||
title: 'Policies',
|
||||
href: '/contribute/policies',
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
title: 'GET MORE HELP',
|
||||
links: [
|
||||
|
||||
@@ -1,3 +1,4 @@
|
||||
import { useEffect, useRef } from 'react'
|
||||
import clsx from 'clsx'
|
||||
import Link from 'next/link'
|
||||
|
||||
@@ -36,10 +37,23 @@ function CloseIcon(props) {
|
||||
|
||||
function AnnouncementItem({ announcement, onClose }) {
|
||||
const announcementLink = useCustomQueryURL(announcement.link || '')
|
||||
const bannerRef = useRef(null)
|
||||
const { setBannerHeight } = useAnnouncements()
|
||||
|
||||
useEffect(() => {
|
||||
const banner = bannerRef.current
|
||||
if (!banner) return
|
||||
const observer = new ResizeObserver(() => {
|
||||
setBannerHeight(Math.ceil(banner.getBoundingClientRect().height))
|
||||
})
|
||||
observer.observe(banner)
|
||||
return () => observer.disconnect()
|
||||
}, [setBannerHeight])
|
||||
|
||||
return (
|
||||
<div
|
||||
id="announcement-banner"
|
||||
ref={bannerRef}
|
||||
className={clsx(
|
||||
'sticky top-0 z-50 flex w-full items-center justify-center border-b border-zinc-800 bg-netbird/95 px-4 py-1.5 text-[11px] font-medium text-black shadow-sm backdrop-blur'
|
||||
)}
|
||||
|
||||
@@ -16,6 +16,7 @@ const BANNER_HEIGHT = 33
|
||||
|
||||
const AnnouncementContext = createContext({
|
||||
bannerHeight: 0,
|
||||
setBannerHeight: () => {},
|
||||
announcements: undefined,
|
||||
closeAnnouncement: () => {},
|
||||
})
|
||||
@@ -83,6 +84,7 @@ const saveAnnouncements = (closedAnnouncements) => {
|
||||
|
||||
export function AnnouncementBannerProvider({ children }) {
|
||||
const [announcements, setAnnouncements] = useState(undefined)
|
||||
const [measuredHeight, setBannerHeight] = useState(BANNER_HEIGHT)
|
||||
const fetchingRef = useRef(false)
|
||||
|
||||
useEffect(() => {
|
||||
@@ -108,12 +110,13 @@ export function AnnouncementBannerProvider({ children }) {
|
||||
[announcements]
|
||||
)
|
||||
|
||||
const bannerHeight = announcements?.some((a) => a.isOpen) ? BANNER_HEIGHT : 0
|
||||
const bannerHeight = announcements?.some((a) => a.isOpen) ? measuredHeight : 0
|
||||
|
||||
return (
|
||||
<AnnouncementContext.Provider
|
||||
value={{
|
||||
bannerHeight,
|
||||
setBannerHeight,
|
||||
announcements,
|
||||
closeAnnouncement,
|
||||
}}
|
||||
|
||||
@@ -0,0 +1,228 @@
|
||||
import {Warning} from "@/components/mdx"
|
||||
|
||||
export const description =
|
||||
"Set up a NetBird contribution, run repository-specific checks, and contain tests that can alter networking or create live resources."
|
||||
|
||||
# Build and test NetBird changes
|
||||
|
||||
Use the target repository's instructions and continuous-integration workflows as the source of truth. The commands below are a starting point for the main NetBird repositories; local requirements can change sooner than this page.
|
||||
|
||||
## Start from the repository instructions
|
||||
|
||||
Before installing tools or running commands, inspect the repository root and `.github/` directory for:
|
||||
|
||||
- `CONTRIBUTING.md`, `AGENTS.md`, and `CLAUDE.md`;
|
||||
- the pull request and issue templates;
|
||||
- `Makefile`, `GNUmakefile`, `Taskfile.yml`, package scripts, and platform project files;
|
||||
- workflow matrices and pinned tool versions;
|
||||
- generated files and the source definitions that produce them.
|
||||
|
||||
If this page conflicts with those files, follow the repository. Do not transfer a command or policy from one NetBird project to another without checking.
|
||||
|
||||
## Prepare your checkout
|
||||
|
||||
Clone your fork, add the upstream repository, and create a focused branch from its current default branch. For a repository that uses `main`:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/YOUR_USERNAME/REPOSITORY.git
|
||||
cd REPOSITORY
|
||||
git remote add upstream https://github.com/netbirdio/REPOSITORY.git
|
||||
git fetch upstream
|
||||
git switch -c YOUR_BRANCH upstream/main
|
||||
```
|
||||
|
||||
Some repositories use another base branch or require submodules. Check the repository page and its local instructions before copying the final command unchanged.
|
||||
|
||||
Do not commit local environment files, credentials, build output, editor state, test clusters, or copied binaries. Run `git status --short` before and after every generator or build so you can distinguish intended output from local debris.
|
||||
|
||||
## Core client and services
|
||||
|
||||
The core [`netbirdio/netbird`](https://github.com/netbirdio/netbird) repository currently requires [Go 1.26](https://github.com/netbirdio/netbird/blob/main/CONTRIBUTING.md#go-126). Start with the smallest test set that covers the changed package, then expand based on the affected component.
|
||||
|
||||
```bash
|
||||
go fmt ./...
|
||||
go test ./path/to/changed/package/...
|
||||
```
|
||||
|
||||
The repository exposes its main quality checks as Make targets:
|
||||
|
||||
```bash
|
||||
make lint
|
||||
make lint-all
|
||||
make test-unit
|
||||
```
|
||||
|
||||
`make lint` checks files changed against `origin/main`; `make lint-all` runs the full-repository linter used by CI. `make test-unit` is the host-safe suite and runs without changing host networking.
|
||||
|
||||
For firewall, routing, interface management, and other privileged networking paths, run the contained privileged suite:
|
||||
|
||||
```bash
|
||||
make test-privileged
|
||||
```
|
||||
|
||||
That target selects tests carrying the `privileged` build tag and runs them in a Docker container with elevated networking capabilities. It needs Docker and can take longer than the unit suite. Narrow runs with `PRIV_RUN` and `PRIV_PKGS` only as documented in the core contribution guide.
|
||||
|
||||
Build or test an individual component when it gives faster feedback:
|
||||
|
||||
```bash
|
||||
go build ./client
|
||||
go test ./client/...
|
||||
go test ./management/...
|
||||
go test ./signal/...
|
||||
go test ./relay/...
|
||||
```
|
||||
|
||||
Packages that use build tags, elevated privileges, concurrency, or operating-system-specific backends can need more than `go test ./...`. Read package comments, nearby tests, `AGENTS.md`, and the core [quality checks](https://github.com/netbirdio/netbird/blob/main/CONTRIBUTING.md#quality-checks) before deciding the test is complete.
|
||||
|
||||
<Warning>
|
||||
Starting a locally built NetBird client with elevated privileges can replace the running client and change routes, firewall rules, DNS settings, interfaces, and active connectivity. Use a VM or disposable test host, keep console or SSH access that does not depend on the NetBird path, and stop the test client before leaving the environment.
|
||||
</Warning>
|
||||
|
||||
## Desktop UI
|
||||
|
||||
The desktop application is built from `client/ui` in the core repository. Its current `Taskfile.yml` dispatches platform-specific Wails v3 builds.
|
||||
|
||||
```bash
|
||||
cd client/ui
|
||||
task build
|
||||
task dev
|
||||
```
|
||||
|
||||
Run the core Go checks when backend code changes. Exercise tray behavior, connection state, update flows, and platform permissions on every operating system affected by the change. A successful Wails build does not establish that native lifecycle behavior works.
|
||||
|
||||
## Web dashboard
|
||||
|
||||
The [`netbirdio/dashboard`](https://github.com/netbirdio/dashboard) package requires Node.js 20.9 or newer. Install locked dependencies and use the repository scripts:
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npm run dev
|
||||
npm run build
|
||||
npm run lint
|
||||
```
|
||||
|
||||
The repository also defines unit and Playwright suites. Select the checks that cover your change from its `package.json` and workflows. For changed UI flows, exercise empty, loading, error, permission-denied, and narrow-screen states, and include screenshots or a short recording when the interaction cannot be understood from the diff alone.
|
||||
|
||||
If API types or clients change, run the generator named by the dashboard repository and review its complete diff.
|
||||
|
||||
## Documentation site
|
||||
|
||||
The [`netbirdio/docs`](https://github.com/netbirdio/docs) site requires Node.js 20.9 or newer. Install the versions pinned in `package-lock.json`, then start the local preview:
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Before requesting review, run the same heading and production-build checks used by docs pull requests:
|
||||
|
||||
```bash
|
||||
npm run lint:mdx
|
||||
npm run build
|
||||
```
|
||||
|
||||
The docs repository also has a Codespell workflow. If you change JSX, JavaScript, navigation, or a component, run:
|
||||
|
||||
```bash
|
||||
npm run lint
|
||||
```
|
||||
|
||||
Keep these repository boundaries in mind:
|
||||
|
||||
- Add user-facing pages to <code className="break-all">src/components/NavigationDocs.jsx</code>; API navigation lives in `NavigationAPI.jsx`.
|
||||
- Add a permanent redirect in `next.config.mjs` when a published route moves.
|
||||
- Store images under `public/docs-static/img/<section>/` and reference them with `/docs-static/img/<section>/...` URLs.
|
||||
- Do not hand-edit generated API pages under `src/pages/ipa/resources`.
|
||||
- Use `npm install` instead of `npm ci` only when intentionally changing dependencies and updating `package-lock.json`.
|
||||
|
||||
Preview every changed route at desktop and narrow widths. Check heading order, links, copied commands, tables, light and dark themes, and whether every required instruction remains understandable without a screenshot.
|
||||
|
||||
## Mobile clients
|
||||
|
||||
Use the platform project files and CI versions in the target repository instead of assuming that core Go commands apply.
|
||||
|
||||
- [`netbirdio/android-client`](https://github.com/netbirdio/android-client) is an Android project. Check its current project files and workflows before selecting the JDK, Gradle task, emulator, or device matrix.
|
||||
- [`netbirdio/ios-client`](https://github.com/netbirdio/ios-client) uses Xcode and a `netbird-core` submodule. Clone with submodules, follow the current build scripts, and check signing and physical-device requirements before choosing a target.
|
||||
|
||||
Test VPN lifecycle behavior on the affected platforms where possible: fresh install, sign-in, connect, disconnect, reconnect after sleep or a network change, and upgrade from a previous release. Keep accounts, setup keys, signing material, and device identifiers out of logs and screenshots.
|
||||
|
||||
## Kubernetes operator
|
||||
|
||||
The [`netbirdio/kubernetes-operator`](https://github.com/netbirdio/kubernetes-operator) contribution guide and `Makefile` define the current workflow. Its main checks are:
|
||||
|
||||
```bash
|
||||
make lint
|
||||
make generate
|
||||
make test-unit
|
||||
```
|
||||
|
||||
Run the end-to-end suite for changes to reconciliation, finalizers, networking, installation, upgrades, or external integration:
|
||||
|
||||
```bash
|
||||
make test-e2e
|
||||
```
|
||||
|
||||
`make test-unit` uses an in-memory Kubernetes control plane. The end-to-end target builds an operator image and runs against a cluster, so use a disposable cluster and clean up namespaces, NetBird peers, setup keys, images, and other temporary resources afterward.
|
||||
|
||||
After API-type changes, review generated deepcopy and apply-configuration code, CRDs, chart CRDs, RBAC or manifests where affected, reference documentation, and test fixtures. Edit the API source and markers, not generated output.
|
||||
|
||||
## Terraform provider
|
||||
|
||||
The [`netbirdio/terraform-provider-netbird`](https://github.com/netbirdio/terraform-provider-netbird) repository documents its commands in `AGENTS.md` and `GNUmakefile`:
|
||||
|
||||
```bash
|
||||
make fmt
|
||||
make lint
|
||||
make test
|
||||
make build
|
||||
make generate
|
||||
```
|
||||
|
||||
`make test` runs the Go unit and integration tests without Docker or the Terraform CLI. Acceptance tests compile the `e2e`-tagged harness, start a NetBird deployment through Docker, and can create or change resources:
|
||||
|
||||
```bash
|
||||
make testacc
|
||||
```
|
||||
|
||||
The target sets `TF_ACC=1` and the `e2e` build tag itself. Use an isolated environment, keep credentials out of source and logs, and inspect the NetBird deployment for resources left by a failed test.
|
||||
|
||||
## Generated and synchronized files
|
||||
|
||||
Generated output belongs in review, but edit its source definition and use the repository's documented generator.
|
||||
|
||||
<div className="my-6 overflow-x-auto" role="region" aria-label="Generated files and source definitions" tabIndex={0}>
|
||||
|
||||
| Area | Edit | Regenerate and review |
|
||||
|---|---|---|
|
||||
| Core protocol definitions | `.proto` source files | Generated Go bindings and affected consumers |
|
||||
| Core management API | API implementation and schema sources | OpenAPI output, API clients, mocks, and dependent docs |
|
||||
| Dashboard API client | Its configured OpenAPI source | Generated client code and types |
|
||||
| Kubernetes APIs | `api/` types and markers | Deepcopy and apply-configuration code, CRDs, chart files, docs, and test fixtures |
|
||||
| Terraform reference docs | Provider schemas and examples | Generated files under `docs/` |
|
||||
| Documentation API pages | The core OpenAPI source and docs generator | `src/pages/ipa/resources` and API navigation changes |
|
||||
|
||||
</div>
|
||||
|
||||
Do not invoke an underlying tool with guessed flags. Generated changes should be reproducible from the same source revision as the pull request.
|
||||
|
||||
## Test cross-repository behavior
|
||||
|
||||
A passing build in one repository does not cover a contract shared with another. For related pull requests:
|
||||
|
||||
1. State the dependency and intended merge order in each pull request.
|
||||
2. Test compatible source revisions together.
|
||||
3. Record the versions or commits used without exposing credentials or private environment details.
|
||||
4. Verify backward compatibility when one side may ship first.
|
||||
5. Update user-facing documentation in the same release window as the behavior.
|
||||
|
||||
The [repository map](/contribute/repositories#changes-that-cross-repository-boundaries) lists common boundaries.
|
||||
|
||||
## Keep privileged tests contained
|
||||
|
||||
Prefer a VM, disposable CI runner, short-lived cluster, or isolated account for work that needs root, `NET_ADMIN`, host networking, TUN devices, firewall access, kernel modules, signing credentials, or real cloud resources.
|
||||
|
||||
Before a host-networking test, record the existing routes, DNS configuration, firewall state, interfaces, and active NetBird process. Keep a recovery path outside the NetBird connection. After the test, stop local clients, restore the original host configuration, remove temporary resources, and verify normal connectivity from a separate terminal or host.
|
||||
|
||||
## Review the final diff
|
||||
|
||||
Before handing off the work, follow the full [pull request review checklist](/contribute/pull-requests#review-the-final-diff), including repository status, generated output, credentials, verification evidence, and documentation.
|
||||
@@ -0,0 +1,90 @@
|
||||
import {Warning} from "@/components/mdx"
|
||||
import {Tiles} from "@/components/Tiles"
|
||||
|
||||
export const description =
|
||||
"Find a useful way to contribute to NetBird, choose the right repository, and prepare work that maintainers can review."
|
||||
|
||||
# Contribute to NetBird
|
||||
|
||||
You do not need to begin with a large code change. A clear bug report, a tested reproduction, a documentation correction, or a helpful answer in the community can remove a real obstacle for the next person. If you do want to write code, start by finding the repository that owns the behavior and agreeing on the problem before investing in a patch.
|
||||
|
||||
<Tiles
|
||||
items={[
|
||||
{
|
||||
href: "/contribute/repositories#build-the-product",
|
||||
name: "Build the product",
|
||||
description: "Work on the agent, services, networking, or desktop application.",
|
||||
},
|
||||
{
|
||||
href: "/contribute/repositories#improve-the-experience",
|
||||
name: "Improve the experience",
|
||||
description: "Contribute to the dashboard or a mobile client.",
|
||||
},
|
||||
{
|
||||
href: "/contribute/repositories#make-the-docs-clearer",
|
||||
name: "Make the docs clearer",
|
||||
description: "Fix a page in your browser or preview a larger docs change locally.",
|
||||
},
|
||||
{
|
||||
href: "/contribute/repositories#extend-the-ecosystem",
|
||||
name: "Extend the ecosystem",
|
||||
description: "Work on Kubernetes, Terraform, packaging, or a community project.",
|
||||
},
|
||||
]}
|
||||
/>
|
||||
|
||||
## Find a first task
|
||||
|
||||
Start with a problem you understand. The core repository's [`good first issue`](https://github.com/netbirdio/netbird/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good%20first%20issue%22) and [`help wanted`](https://github.com/netbirdio/netbird/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22help%20wanted%22) searches can point you toward scoped work. Read the issue and its latest comments before you claim it; an open label does not guarantee that the task is unassigned or that the proposed approach is still current.
|
||||
|
||||
A first contribution can also be one of these:
|
||||
|
||||
- Reproduce a report on a supported platform and add the version, configuration, exact steps, and observed result that were missing.
|
||||
- Turn a setup or usage question into a focused [Q&A discussion](https://github.com/netbirdio/netbird/discussions/categories/q-a-support), or answer one when you have verified the solution.
|
||||
- Share a concrete use case in [Slack](/slack-url) or the community so maintainers can understand where the current workflow falls short.
|
||||
- Correct a typo, stale link, unclear step, or unsupported claim in the documentation.
|
||||
- Help translate the desktop UI through [NetBird on Crowdin](https://crowdin.com/project/netbird); the core repository's locale files are synchronized from there rather than edited by hand.
|
||||
|
||||
For a bug, regression, feature, or integration idea in the core project, search [Discussions](https://github.com/netbirdio/netbird/discussions) before opening a new one. Use the category that matches the report and describe the problem, affected component, environment, expected behavior, and actual behavior. Never post a suspected vulnerability publicly; use the [private reporting process](/contribute/policies#report-a-vulnerability).
|
||||
|
||||
## Before you write code
|
||||
|
||||
Read the target repository's `CONTRIBUTING.md`, `AGENTS.md`, `CLAUDE.md`, pull request template, and workflow files when they exist. Repository-local instructions are authoritative: they define the accepted workflow, tool versions, generated files, test commands, title format, sign-off rules, and contribution agreements for that project.
|
||||
|
||||
The core [`netbirdio/netbird`](https://github.com/netbirdio/netbird) project is discussion-first. Except for trivial fixes, begin in the appropriate [GitHub Discussion](https://github.com/netbirdio/netbird/discussions/new/choose), wait while the report and direction are validated, and write code only after there is an agreed issue to link. Public APIs, protocols, existing behavior, peer connectivity, host networking, authentication and authorization, CLI or service configuration, persistence, and new features always need agreement before implementation. The [contribution policies](/contribute/policies#changes-that-need-an-agreed-issue) explain this boundary.
|
||||
|
||||
Small documentation corrections, typo and broken-link fixes, focused tests, and a one-line fix that already has an issue can normally go straight to a pull request. When you are unsure, ask in the target repository or on [Slack](/slack-url) before building a large patch.
|
||||
|
||||
<Warning>
|
||||
GitHub issues, discussions, pull requests, and build logs are public. Remove setup keys, tokens, private keys, customer data, internal hostnames, production addresses, and unredacted logs before posting. Report security findings privately.
|
||||
</Warning>
|
||||
|
||||
## A practical contribution flow
|
||||
|
||||
1. [Choose the repository and component](/contribute/repositories) that owns the change.
|
||||
2. Confirm the problem and the expected direction under that repository's rules.
|
||||
3. [Build and test the smallest useful change](/contribute/development), containing privileged networking work in a disposable environment.
|
||||
4. [Prepare a reviewable pull request](/contribute/pull-requests) with the linked issue, real verification, and one clear purpose.
|
||||
5. Respond to human and automated review, keeping the repository's local policy authoritative throughout.
|
||||
|
||||
## Choose where to contribute
|
||||
|
||||
The canonical [repository map](/contribute/repositories) groups projects by the kind of contribution you want to make and covers cross-repository changes.
|
||||
|
||||
## Open a reviewable pull request
|
||||
|
||||
Follow the complete [pull request workflow and review checklist](/contribute/pull-requests).
|
||||
|
||||
## Using AI tools
|
||||
|
||||
Coding assistants are allowed in the core project, but they do not change the contribution standard: you must understand every line, verify the result yourself, and answer review questions directly. Read the [tooling and authorship policy](/contribute/policies#using-ai-tools) and then follow the target repository's local rules.
|
||||
|
||||
## Documentation changes
|
||||
|
||||
Every published docs page includes **Edit on GitHub** near the bottom. Use it to open the source file for a typo, broken link, or small clarification, make the focused edit in GitHub, and propose the change as a pull request. Explain what was unclear and, for a technical correction, include the source or test that establishes the new behavior.
|
||||
|
||||
For a new page, navigation change, component edit, or larger rewrite, fork [`netbirdio/docs`](https://github.com/netbirdio/docs), preview the affected routes locally, and use the [documentation-site workflow](/contribute/development#documentation-site). Verify product behavior before changing commands, defaults, UI labels, ports, or compatibility claims. Do not hand-edit `src/pages/ipa/resources`; those API pages are generated from the core OpenAPI schema.
|
||||
|
||||
## Terms and conduct
|
||||
|
||||
Licenses, contribution agreements, sign-off requirements, and review rules can differ by repository. Read the target project's files rather than carrying a rule over from another NetBird repository. See [Contribution policies](/contribute/policies) for conduct, licensing, public-data, security, and authorship guidance.
|
||||
@@ -0,0 +1,88 @@
|
||||
import {Warning} from "@/components/mdx"
|
||||
|
||||
export const description =
|
||||
"Follow repository-local contribution rules, report vulnerabilities privately, and understand NetBird's conduct, licensing, and authorship expectations."
|
||||
|
||||
# Contribution policies
|
||||
|
||||
NetBird repositories do not all use the same intake, testing, commit, sign-off, or licensing rules. The files in the repository you are changing are authoritative. Read them before starting, and follow newer local requirements when this guide and a repository disagree.
|
||||
|
||||
## Report a vulnerability
|
||||
|
||||
**Do not open a public issue, discussion, or pull request for a suspected security vulnerability.** Public reports can expose the problem before a fix is available.
|
||||
|
||||
For open source NetBird code, use one of the private channels in the core [security policy](https://github.com/netbirdio/netbird/security/policy):
|
||||
|
||||
- [Open a private GitHub vulnerability report](https://github.com/netbirdio/netbird/security/advisories/new). This is the preferred route for repository findings.
|
||||
- Email [`security@netbird.io`](mailto:security@netbird.io).
|
||||
|
||||
If the finding affects NetBird Cloud or hosted infrastructure rather than the open source repository, use email. Include the affected component and version or commit, platform and deployment type, required attacker position or privileges, reproduction steps or a proof of concept when available, and the impact you observed. Partial reports are welcome; if you are unsure whether a finding is security-sensitive, send it privately and let the NetBird team assess it.
|
||||
|
||||
<Warning>
|
||||
Test only systems and data you are authorized to access. Do not access, alter, or exfiltrate another person's data while investigating a report, and give maintainers a reasonable opportunity to release a fix before public disclosure.
|
||||
</Warning>
|
||||
|
||||
## Keep public contributions safe to share
|
||||
|
||||
Issues, discussions, pull requests, comments, CI output, screenshots, and uploaded logs are normally public. Before posting, remove:
|
||||
|
||||
- setup keys, personal access tokens, API keys, session cookies, private keys, and identity-provider secrets;
|
||||
- customer names or data, private email addresses, internal hostnames, production IP addresses, and account identifiers;
|
||||
- unredacted diagnostics, configuration files, database content, or packet captures;
|
||||
- signing files, cloud credentials, and credentials embedded in command history.
|
||||
|
||||
Use sanitized examples and the private security route when redaction would hide the behavior that matters. A non-security bug in the core product belongs in the appropriate [GitHub Discussion](https://github.com/netbirdio/netbird/discussions/new/choose), not in a security report.
|
||||
|
||||
## Changes that need an agreed issue
|
||||
|
||||
The core project is discussion-first. For a non-trivial bug, regression, feature, enhancement, or integration idea, begin in [Discussions](https://github.com/netbirdio/netbird/discussions/new/choose), wait for validation and maintainer feedback, and then link the resulting agreed issue from the pull request.
|
||||
|
||||
The following core areas always need the design agreed before code is written:
|
||||
|
||||
- the public REST or management API, OpenAPI schema, and dashboard-facing contracts;
|
||||
- management, signal, relay, or client-daemon gRPC protocols;
|
||||
- behavior that existing deployments would experience differently after an upgrade;
|
||||
- peer connectivity, NAT traversal, relay selection, WireGuard or Rosenpass key handling;
|
||||
- routing, firewall, DNS, interface management, and other host integration;
|
||||
- authentication, authorization, identity integration, tokens, permissions, or cryptography;
|
||||
- CLI and service flags, configuration formats, and daemon IPC;
|
||||
- store models, database schemas, and migrations;
|
||||
- new features.
|
||||
|
||||
A typo, broken link, documentation correction, focused test, or one-line fix with an existing issue can normally go directly to a pull request. Other repositories may draw the boundary differently, so their local issue and discussion rules still take precedence.
|
||||
|
||||
## Using AI tools
|
||||
|
||||
The core project has no policy for or against using an AI coding agent. The author standard does not change with the tool:
|
||||
|
||||
- Give the tool the target repository's local instructions and agreed issue before it drafts a change.
|
||||
- Keep the diff small and single-purpose.
|
||||
- Review every generated line and remove unsupported claims, unused abstractions, and irrelevant prose.
|
||||
- Run the behavior and tests yourself; never invent command output or use CI as your first execution.
|
||||
- Answer review questions directly and be able to explain the implementation, risks, and tradeoffs.
|
||||
|
||||
Whatever produced the draft, the person opening the pull request owns every submitted line and its consequences. Maintainers can assess whether the contribution is understandable, maintainable, tested, and aligned with the project's security and design expectations.
|
||||
|
||||
Attribution policy varies. The core and Terraform provider repositories do not accept `Co-Authored-By` or tool-attribution trailers, but that rule must not be assumed for another repository. Check its local contribution and commit guidance.
|
||||
|
||||
## Licenses, agreements, and sign-offs
|
||||
|
||||
Read the target repository's `LICENSE`, contribution guide, and pull request template. Do not assume that one project's license, contributor agreement, Developer Certificate of Origin sign-off, or bot check applies across the NetBird organization.
|
||||
|
||||
The core [`netbirdio/netbird`](https://github.com/netbirdio/netbird) repository requires the [NetBird Contributor License Agreement](https://github.com/netbirdio/netbird/blob/main/CONTRIBUTOR_LICENSE_AGREEMENT.md). Its pull request template links the agreement, and the repository's CLA check determines whether a core contribution can be merged. Check the local process again when contributing elsewhere.
|
||||
|
||||
## Code of conduct
|
||||
|
||||
Participation in NetBird community spaces is governed by the [NetBird Code of Conduct](https://github.com/netbirdio/netbird/blob/main/CODE_OF_CONDUCT.md). Keep technical disagreement focused on the work, assume good faith while evidence is gathered, and treat contributors, users, and reviewers with respect.
|
||||
|
||||
The Code of Conduct lists [`community@netbird.io`](mailto:community@netbird.io) for reporting unacceptable behavior. Security vulnerabilities belong in the separate [private security process](#report-a-vulnerability).
|
||||
|
||||
## When policies differ
|
||||
|
||||
Use this order when two instructions appear to conflict:
|
||||
|
||||
1. The target repository's current policy, templates, and required checks.
|
||||
2. Maintainer direction on the issue or pull request.
|
||||
3. This cross-project contributor guide.
|
||||
|
||||
Ask before proceeding when the difference affects security, licensing, generated files, release ownership, a destructive test, or whether the project accepts the change. Do not weaken a local check or substitute another repository's process to make a contribution easier to submit.
|
||||
@@ -0,0 +1,111 @@
|
||||
import {Warning} from "@/components/mdx"
|
||||
|
||||
export const description =
|
||||
"Prepare a focused NetBird pull request with an agreed issue, local verification, a reviewable diff, and the repository's required metadata."
|
||||
|
||||
# Open a reviewable pull request
|
||||
|
||||
A good pull request lets a reviewer understand one problem, see why the approach fits, and verify what you actually ran. The target repository's contribution guide, pull request template, title checks, and workflows remain authoritative; use this page as a review path, not as a replacement for them.
|
||||
|
||||
## Start with the agreed work
|
||||
|
||||
For the core project, every non-trivial change begins with a validated discussion and an issue whose direction a maintainer has agreed. Link that issue in the pull request. A polished implementation does not replace the ticket-first requirement, especially for the [high-risk areas](/contribute/policies#changes-that-need-an-agreed-issue).
|
||||
|
||||
Other NetBird repositories have their own intake rules. For example, an operator or integration repository may require an issue first even when a similar change in the docs would not. Confirm the rule locally before opening the pull request.
|
||||
|
||||
## Keep one purpose
|
||||
|
||||
Keep a bug fix, refactor, feature, generated update, and unrelated cleanup in separate pull requests. A focused change is easier to test, review, release, and revert.
|
||||
|
||||
The core repository asks contributors to aim for fewer than roughly 400 hand-written changed lines across fewer than 20 files. Past about 1,000 lines or 50 files, expect a request to split the work unless the larger scope and sequence were agreed in the issue. Generated output, `go.sum`, and fixtures do not count toward that guideline, but they still need review.
|
||||
|
||||
If a protocol migration, cross-component rename, or other indivisible change cannot be small, agree on a series of independently buildable pull requests before implementation. Link the series and state the order.
|
||||
|
||||
## Run and verify the change
|
||||
|
||||
Build the affected components and exercise the behavior yourself. Do not use CI as the first test of code that will run as a privileged service or alter a user's network.
|
||||
|
||||
Use the [repository-specific build and test commands](/contribute/development). Record:
|
||||
|
||||
- the exact commands or manual scenarios you ran;
|
||||
- the operating systems, versions, commits, and configurations that matter;
|
||||
- the observed result and any important case you could not test;
|
||||
- cleanup performed after a privileged, acceptance, cluster, or cloud test.
|
||||
|
||||
For a bug fix, add a regression test when practical and establish that it fails for the original reason before applying the fix. For UI work, include screenshots or a short recording when layout and interaction are part of the result. Remove accounts, credentials, internal addresses, and device identifiers from all evidence.
|
||||
|
||||
## Fill in the local template
|
||||
|
||||
Do not delete the pull request template. Complete the fields the target repository asks for rather than replacing them with a generic narrative.
|
||||
|
||||
A core pull request must link the agreed issue, identify the kind of change, confirm local testing and a single purpose, and select whether documentation was updated or is not needed. When documentation is needed, open the corresponding [`netbirdio/docs`](https://github.com/netbirdio/docs) pull request and link it.
|
||||
|
||||
Explain the problem and the reasoning that the diff cannot show. Avoid a file-by-file walkthrough. The core guide asks for the description to stay under 1,000 words in addition to the template text.
|
||||
|
||||
## Use the repository's title and commit format
|
||||
|
||||
Core pull request titles and commit subjects begin with a bracketed component tag, for example:
|
||||
|
||||
```text
|
||||
[client] Handle a platform-specific route update
|
||||
[management,client] Add an agreed cross-component behavior
|
||||
```
|
||||
|
||||
The core repository's [`allowedTags` list](https://github.com/netbirdio/netbird/blob/main/.github/workflows/pr-title-check.yml) is the source of truth. Do not copy that list into another repository: the dashboard, operator, provider, docs, and mobile projects may use different scopes or no tag rule.
|
||||
|
||||
Keep commit subjects short and put non-obvious reasoning in the body. Follow local sign-off and attribution rules; they are not uniform across the NetBird organization.
|
||||
|
||||
## Review the final diff
|
||||
|
||||
From the repository root, inspect the state and the complete patch:
|
||||
|
||||
```bash
|
||||
git status --short
|
||||
git diff --check
|
||||
git diff --stat
|
||||
git diff
|
||||
```
|
||||
|
||||
Then confirm all of the following:
|
||||
|
||||
- The pull request solves one stated problem and contains no unrelated formatting or refactor.
|
||||
- Source, tests, docs, lockfiles, and generated output are present only when the change requires them.
|
||||
- Every generated file came from its source definition and documented generator.
|
||||
- Local environment files, copied logs, binaries, test manifests, editor files, and build output are absent.
|
||||
- No credential, setup key, token, private key, customer detail, internal hostname, production address, or unredacted diagnostic appears in the diff or test evidence.
|
||||
- Relevant formatting, lint, unit, integration, privileged, acceptance, and end-to-end checks were run, and any gap is stated honestly.
|
||||
- User-visible behavior has matching documentation, or the template explains why documentation is not needed.
|
||||
- Related cross-repository pull requests are linked with their required merge or release order.
|
||||
|
||||
For core Go changes, also check the code standards in the current contribution guide: keep functions single-purpose, prefer private functions and constants, document new public functions, test new public behavior, and comment on why a non-obvious choice exists rather than narrating the code.
|
||||
|
||||
## Get CI green before requesting review
|
||||
|
||||
Watch the checks after pushing and fix failures before asking a maintainer to review. If a check is still running or could not be run from a fork, report that status instead of calling the pull request green.
|
||||
|
||||
The core project currently runs human review alongside automated analysis. Read bot and scanner findings, then either fix each applicable problem or explain why it does not apply. Do not resolve a thread without a response, change correct code only to silence a false positive, or weaken a workflow, threshold, scanner, or lint rule to make a check pass. Treat security and dependency findings as real until you can show otherwise.
|
||||
|
||||
## Respond to review without hiding the changes
|
||||
|
||||
Answer review questions in your own words and push requested fixes as new commits while review is active. The core project squashes on merge, so rewriting history provides little benefit and makes follow-up review harder.
|
||||
|
||||
Avoid force-pushing a branch under review because it detaches line comments, discards the reviewer's changes-since-last-review view, and removes useful CI history. If a force-push is unavoidable to remove a secret or large binary, or to resolve a genuine history conflict, tell reviewers that their anchors moved.
|
||||
|
||||
Do not force-push away feedback, silently dismiss automated findings, or relay reviewer questions to a tool without understanding the answer. The person opening the pull request owns every line and must be able to explain it.
|
||||
|
||||
<Warning>
|
||||
If a secret reaches a commit or pull request, removing it in a later commit is not enough. Stop, follow the affected repository's incident or credential-rotation process, and tell maintainers privately before rewriting public history.
|
||||
</Warning>
|
||||
|
||||
## Before you request review
|
||||
|
||||
One final pass should answer yes to these questions:
|
||||
|
||||
1. Is there one clear purpose and, where required, an agreed issue?
|
||||
2. Did you run the changed behavior locally and record real results?
|
||||
3. Is CI green, or is every pending or unavailable check identified?
|
||||
4. Can a reviewer understand the risk, generated output, and cross-repository dependencies?
|
||||
5. Is user-facing documentation included or explicitly accounted for?
|
||||
6. Do you understand and accept responsibility for every line?
|
||||
|
||||
If the answer is no, keep the pull request in draft or return to the issue before asking for review.
|
||||
@@ -0,0 +1,120 @@
|
||||
import {Warning} from "@/components/mdx"
|
||||
|
||||
export const description =
|
||||
"Choose the NetBird repository and component that owns the product, experience, documentation, or integration you want to improve."
|
||||
|
||||
# Find the right NetBird repository
|
||||
|
||||
Start where the behavior is owned. A change that appears to be one dashboard control can also require a management API update, generated client changes, and documentation, so identify the boundaries before you open a pull request.
|
||||
|
||||
Repository-local instructions are authoritative. Read `CONTRIBUTING.md`, `AGENTS.md`, `CLAUDE.md`, pull request templates, and workflow files in the target repository before you start.
|
||||
|
||||
## Common contribution paths
|
||||
|
||||
Use these four paths to narrow the search. The detailed maps below explain the ownership boundaries.
|
||||
|
||||
- [Build the product](#build-the-product) for the agent, control plane services, networking, and desktop application.
|
||||
- [Improve the experience](#improve-the-experience) for the web dashboard and mobile clients.
|
||||
- [Make the docs clearer](#make-the-docs-clearer) for product guides, troubleshooting, API pages, navigation, and docs components.
|
||||
- [Extend the ecosystem](#extend-the-ecosystem) for operators, infrastructure as code, packaging, and community projects.
|
||||
|
||||
## Build the product
|
||||
|
||||
Most core product work belongs in [`netbirdio/netbird`](https://github.com/netbirdio/netbird). This repository contains the agent, CLI, desktop application, management and signaling services, relay, shared protocols, networking code, installers, and end-to-end tests.
|
||||
|
||||
### Inside the core repository
|
||||
|
||||
<div className="my-6 overflow-x-auto" role="region" aria-label="Core repository components" tabIndex={0}>
|
||||
|
||||
| Path | Owns |
|
||||
|---|---|
|
||||
| `client/`, `client/cmd/`, `client/server/` | Agent lifecycle, CLI, daemon, and background-service behavior |
|
||||
| `client/ui/` | The Wails and React desktop application |
|
||||
| `client/internal/routemanager/`, `route/` | Routing and route management across operating systems |
|
||||
| `client/firewall/` | Platform firewall backends and rule management |
|
||||
| `client/internal/dns/`, `dns/` | DNS management and resolver behavior |
|
||||
| `client/ssh/`, `client/mdm/`, `client/system/` | Built-in SSH, MDM-delivered policy handling, and host information |
|
||||
| `management/` | Accounts, users, peers, groups, Networks, Policies, setup keys, identity integration, persistence, and the management API |
|
||||
| `signal/` | Peer signaling and connection negotiation |
|
||||
| `relay/` | Encrypted traffic relay and relay protocol behavior |
|
||||
| `proxy/` | The identity-aware proxy used by Agent Network |
|
||||
| `client/proto/`, `shared/management/proto/`, `shared/signal/proto/`, `flow/` | Protocol definitions, generated bindings, and flow-event types |
|
||||
| `shared/` | Management, signal, relay, authentication, and API types shared across components |
|
||||
| `stun/`, `encryption/`, `sharedsock/`, `util/` | Shared connectivity, encryption, socket, and utility primitives |
|
||||
| `e2e/` | End-to-end suites and their shared test harness |
|
||||
| `infrastructure_files/`, `release_files/`, `tools/` | Self-hosting assets, release packaging, and development tooling |
|
||||
|
||||
</div>
|
||||
|
||||
Look at package-level tests and nearby files before changing shared code. A small edit to a protocol, API type, routing primitive, DNS package, authentication helper, or persistence model can affect several binaries and platforms.
|
||||
|
||||
## Improve the experience
|
||||
|
||||
<div className="my-6 overflow-x-auto" role="region" aria-label="Dashboard and mobile repositories" tabIndex={0}>
|
||||
|
||||
| Area | Repository | Typical changes |
|
||||
|---|---|---|
|
||||
| Web dashboard | [`netbirdio/dashboard`](https://github.com/netbirdio/dashboard) | Administration UI, API client usage, forms, tables, permissions, and account workflows |
|
||||
| Android client | [`netbirdio/android-client`](https://github.com/netbirdio/android-client) | Android application, VPN service, mobile UI, and Android-specific networking |
|
||||
| iOS and tvOS client | [`netbirdio/ios-client`](https://github.com/netbirdio/ios-client) | Apple-platform UI, network extension, core submodule integration, packaging, and release builds |
|
||||
|
||||
</div>
|
||||
|
||||
The desktop application is not in a separate UI repository. Its Wails and React source lives under `client/ui` in [`netbirdio/netbird`](https://github.com/netbirdio/netbird/tree/main/client/ui).
|
||||
|
||||
Mobile repositories combine platform code with core NetBird components. Read their project files, submodule instructions, signing requirements, and CI workflows before choosing a build or test matrix.
|
||||
|
||||
## Make the docs clearer
|
||||
|
||||
Product documentation lives in [`netbirdio/docs`](https://github.com/netbirdio/docs). It includes conceptual and task guides, troubleshooting, the API documentation site, navigation, and reusable MDX components.
|
||||
|
||||
For a typo, broken link, or small clarification, open the relevant page on [docs.netbird.io](https://docs.netbird.io), select **Edit on GitHub** near the bottom, and propose the focused change in your browser. For a larger contribution, fork the repository, create a branch, and follow the [documentation build and preview workflow](/contribute/development#documentation-site).
|
||||
|
||||
Technical docs changes need evidence. Check the current product source, UI, schema, or tested behavior before changing a command, option, default, UI label, port, platform limitation, or version boundary. API pages under `src/pages/ipa/resources` are generated; update their OpenAPI source and use the documented generator instead of editing the output directly.
|
||||
|
||||
## Extend the ecosystem
|
||||
|
||||
<div className="my-6 overflow-x-auto" role="region" aria-label="Ecosystem repositories" tabIndex={0}>
|
||||
|
||||
| Area | Repository | Typical changes |
|
||||
|---|---|---|
|
||||
| Kubernetes operator | [`netbirdio/kubernetes-operator`](https://github.com/netbirdio/kubernetes-operator) | Custom resources, controllers, generated manifests, Helm packaging, and end-to-end cluster behavior |
|
||||
| Terraform provider | [`netbirdio/terraform-provider-netbird`](https://github.com/netbirdio/terraform-provider-netbird) | Resources, data sources, provider schema, generated reference docs, and acceptance tests |
|
||||
| NetworkManager plugin | [`netbirdio/network-manager-vpn-plugin`](https://github.com/netbirdio/network-manager-vpn-plugin) | Linux NetworkManager integration, editor UI, D-Bus behavior, and packaging |
|
||||
| Helm charts | [`netbirdio/helms`](https://github.com/netbirdio/helms) | Kubernetes deployment templates and chart values |
|
||||
| Home Assistant add-on | [`netbirdio/addon-netbird`](https://github.com/netbirdio/addon-netbird) | Add-on packaging and Home Assistant deployment behavior |
|
||||
| Ansible collection | [`netbirdio/ansible-netbird`](https://github.com/netbirdio/ansible-netbird) | NetBird configuration through Ansible modules and roles |
|
||||
| Community projects list | [`netbirdio/awesome-netbird`](https://github.com/netbirdio/awesome-netbird) | Curated community tools, integrations, and learning resources |
|
||||
|
||||
</div>
|
||||
|
||||
For specialized SDKs, integrations, packaging, and experimental tools, browse the [`netbirdio` organization](https://github.com/netbirdio). Confirm that the repository is active, accepts the kind of contribution you plan to make, and is not a fork, mirror, generated artifact, or example repository.
|
||||
|
||||
<Warning>
|
||||
A repository name does not establish release ownership or contribution policy. Read its local files and recent activity before proposing a broad change, especially in packaging, fork, mirror, or example repositories.
|
||||
</Warning>
|
||||
|
||||
## Changes that cross repository boundaries
|
||||
|
||||
Plan related work together, but keep each pull request scoped to one repository:
|
||||
|
||||
- A management API change can require the core OpenAPI output, dashboard client, Terraform schema, and docs to change together.
|
||||
- A CLI or configuration change can affect installers, packaging, mobile clients, and documentation.
|
||||
- A Kubernetes custom resource change can require generated code, CRDs, RBAC, manifests, examples, and operator documentation.
|
||||
- A dashboard workflow can need core API support and a matching procedural update in the docs.
|
||||
- A release-format change can affect downstream package and deployment repositories even if their source code does not change.
|
||||
|
||||
Link related pull requests and state the expected merge or release order when one depends on another. Test compatible revisions together, and do not copy generated output across repositories without recording its source and generation command.
|
||||
|
||||
## Before you open a pull request
|
||||
|
||||
Confirm these points in the target repository:
|
||||
|
||||
1. The issue or discussion is current, the direction is agreed when required, and nobody else is already doing the work.
|
||||
2. The default branch and pull request base are correct.
|
||||
3. The repository accepts external changes in the area you plan to edit.
|
||||
4. You know which files are generated and which command updates them.
|
||||
5. You can run the relevant tests without exposing credentials or damaging your normal network environment.
|
||||
6. You understand the pull request template, title format, contribution agreement, license, and sign-off rules that apply there.
|
||||
|
||||
Next, use the [build and test guide](/contribute/development), then work through the [pull request checklist](/contribute/pull-requests).
|
||||
Reference in New Issue
Block a user