Skip to content

add contributing.md repo links, cleanup #2751

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
k8s-ci-robot merged 3 commits into from
Jan 22, 2026
+124 −69
Merged

add contributing.md repo links, cleanup #2751

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4428277
contributing info
davidgamero Jan 21, 2026
5ed860a
update contributingmd
davidgamero Jan 21, 2026
db2cec1
remove ascii graphic
davidgamero Jan 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
121 changes: 111 additions & 10 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,120 @@ Thanks for taking the time to join our community and start contributing!

Please remember to read and observe the [Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).

This project accepts contribution via github [pull requests](https://help.github.com/articles/about-pull-requests/). This document outlines the process to help get your contribution accepted. Please also read the [Kubernetes contributor guide](https://github.com/kubernetes/community/blob/master/contributors/guide/README.md) which provides detailed instructions on how to get your ideas and bug fixes seen and accepted.
## Getting Started

### Prerequisites

All dependencies of this project are expressed in its [`package.json` file](package.json). Before you start developing, ensure that you have [NPM](https://www.npmjs.com/) installed, then run:

```console
npm install
```

### Development Workflow

1. Fork this repo
2. Create a feature branch
3. Make your changes (see sections below for development guidelines)
4. Test your changes (`npm test`)
5. Ensure code is formatted (`npm run format`) and passes linting (`npm run lint`)
6. Submit a pull request

## Sign the Contributor License Agreement
We'd love to accept your patches! Before we can accept them you need to sign Cloud Native Computing Foundation (CNCF) [CLA](https://github.com/kubernetes/community/blob/master/CLA.md).

## Reporting an issue
We'd love to accept your patches! Before we can accept them you need to sign the Cloud Native Computing Foundation (CNCF) [CLA](https://github.com/kubernetes/community/blob/master/CLA.md).

## Reporting Issues

If you have any problem with the package or any suggestions, please file an [issue](https://github.com/kubernetes-client/javascript/issues).

## Contributing a Patch
1. Submit an issue describing your proposed change to the repo.
2. Fork this repo, develop and test your code changes.
3. Submit a pull request.
4. The bot will automatically assigns someone to review your PR. Check the full list of bot commands [here](https://prow.k8s.io/command-help).
## Submitting a Pull Request

1. Submit an issue describing your proposed change to the repo
2. Fork this repo, develop and test your code changes
3. Submit a pull request
4. The bot will automatically assign someone to review your PR. Check the full list of bot commands [here](https://prow.k8s.io/command-help)

For more detailed guidance, see the [Kubernetes contributor guide](https://github.com/kubernetes/community/blob/master/contributors/guide/README.md).

## Architecture and Code Generation

### Project Structure

This repo is built around a core of generated code that lives in the `/src/gen` directory

The `/src/gen` folder's contents is generated using the [OpenAPI Generator](https://github.com/OpenAPITools/openapi-generator). This code should **not be modified manually** as changes will be overwritten by the generator.

### Generated Code

- **Generator**: Uses [OpenAPI Generator](https://openapi-generator.tech/docs/generators/typescript) with TypeScript configuration
- **Spec Source**: Pulls from the [Kubernetes OpenAPI Spec](https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec)
- **Configuration**: Shared config at [kubernetes-client/gen](https://github.com/kubernetes-client/gen/blob/master/openapi/typescript.xml)
- **Settings**: Generation inputs are configured in the `/settings` file

### Client Layer

Around the core generated code in `src/gen`, the client layer adds Kubernetes-specific features:

- Kubeconfig authentication
- Watch functionality
- Serialization
- Higher-level ergonomics requiring multiple REST calls

These functionalities provide parity with kubectl and expose convenient abstractions. For example, `kubectl port-forward deploy/my-deployment` doesn't POST to a `.../deployments/...` route. Instead, a pod is selected via listing and filtering, then a POST to `.../pods/.../portforward` is sent.

### Making Changes to Generated Code

If improvements require changes to the generated code:

1. Raise the issue upstream in the [OpenAPIGenerator repo](https://github.com/OpenAPITools/openapi-generator?tab=contributing-ov-file)
2. After they merge, update the sha in `/settings`
3. Regenerate the project using `npm run generate`

Many changes can be made using middleware to access or conditionally mutate requests without modifying the generator.

## Development Tasks

### Regenerating Code

```console
npm run generate
```

### Building Documentation

Documentation is generated via typedoc:

```console
npm run docs
```

To view the generated documentation, open `docs/index.html`

### Formatting

Run `npm run format` or install an editor plugin like:

- [Prettier for VS Code](https://github.com/prettier/prettier-vscode)
- [EditorConfig](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig)

### Linting

Run `npm run lint` or install an editor plugin.

## Testing

Tests are written using the [`node:test`](https://nodejs.org/api/test.html) test runner and [`node:assert`](https://nodejs.org/api/assert.html) assertion library. See [`config_test.ts`](./src/config_test.ts) for an example.

To run tests:

```console
npm test
```

## Contact

You can reach the maintainers of this project at:

### Contact
You can reach the maintainers of this project at [SIG API Machinery](https://github.com/kubernetes/community/tree/master/sig-api-machinery) or on the [#kubernetes-client](https://kubernetes.slack.com/messages/kubernetes-client) channel on the Kubernetes slack.
- [SIG API Machinery](https://github.com/kubernetes/community/tree/master/sig-api-machinery)
- [#kubernetes-client](https://kubernetes.slack.com/messages/kubernetes-client) channel on Kubernetes Slack
72 changes: 13 additions & 59 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -114,17 +114,17 @@ We switched from `request` to `fetch` as the HTTP(S) backend for the `1.0.0` rel

Generally speaking newer clients will work with older Kubernetes, but compatibility isn't 100% guaranteed.

| client version | older versions | 1.28 | 1.29 | 1.30 | 1.31 | 1.32 | 1.33|1.34|
| -------------- | -------------- | ---- | ---- | ---- | ---- | ---- |----|----|
| 0.19.x | - | ✓ | x | x | x | x | x | x |
| 0.20.x | - | + | ✓ | x | x | x | x | x |
| 0.21.x | - | + | + | ✓ | x | x | x | x |
| 0.22.x | - | + | + | + | ✓ | x | x | x |
| 1.0.x | - | + | + | + | + | ✓ | x | x |
| 1.1.x | - | + | + | + | + | ✓ | x | x |
| 1.2.x | - | + | + | + | + | + | ✓ | x |
| 1.3.x | - | + | + | + | + | + | ✓ | x |
| 1.4.x | - | + | + | + | + | + | + | ✓|
| client version | older versions | 1.28 | 1.29 | 1.30 | 1.31 | 1.32 | 1.33 | 1.34 |
| -------------- | -------------- | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
| 0.19.x | - | ✓ | x | x | x | x | x | x |
| 0.20.x | - | + | ✓ | x | x | x | x | x |
| 0.21.x | - | + | + | ✓ | x | x | x | x |
| 0.22.x | - | + | + | + | ✓ | x | x | x |
| 1.0.x | - | + | + | + | + | ✓ | x | x |
| 1.1.x | - | + | + | + | + | ✓ | x | x |
| 1.2.x | - | + | + | + | + | + | ✓ | x |
| 1.3.x | - | + | + | + | + | + | ✓ | x |
| 1.4.x | - | + | + | + | + | + | + | ✓ |

Key:

Expand All @@ -147,52 +147,6 @@ Key:

- In scenarios where multiple headers with the same key are required in a request, such as `Impersonate-Group`, avoid using `fetch`. Fetch will merge the values into a single header key, with the values as a single string vs a list of strings, `Impersonate-Group: "group1,group2"`. The workaround is to use a low-level library such as `https` to make the request. Refer to issue [#2474](https://github.com/kubernetes-client/javascript/issues/2474) for more details.

# Development
# Contributing

All dependencies of this project are expressed in its
[`package.json` file](package.json). Before you start developing, ensure
that you have [NPM](https://www.npmjs.com/) installed, then run:

```console
npm install
```

## (re) Generating code

```console
npm run generate
```

## Documentation

Documentation is generated via typedoc:

```
npm run docs
```

To view the generated documentation, open `docs/index.html`

## Formatting

Run `npm run format` or install an editor plugin like https://github.com/prettier/prettier-vscode and https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig

## Linting

Run `npm run lint` or install an editor plugin.

# Testing

Tests are written using the [`node:test`](https://nodejs.org/api/test.html) test runner and
[`node:assert`](https://nodejs.org/api/assert.html) assertion library. See
[`config_test.ts`](./src/config_test.ts) for an example.

To run tests, execute the following:

```console
npm test
```

## Contributing

Please see [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on how to contribute.
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and contribution guidelines.