From 4428277fc68fc9bed2735d7895a080b63088d284 Mon Sep 17 00:00:00 2001 From: David Gamero Date: Wed, 21 Jan 2026 13:19:01 -0500 Subject: [PATCH 1/3] contributing info --- CONTRIBUTING.md | 28 +++++++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1ce66d7d71..8d581dfbca 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,19 +4,45 @@ 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. +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. ## 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 + 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). ### 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. + +## How it works + +### Generated Files + +``` +/+ + + src/ + + gen/ <<< Automatically generated with OpenAPIGenerator, don't edit manually in Pull Requests +``` + +This repo has a 2 tiered structure. The `/src/gen` repo contains code that is generated using the OpenAPI Generator [GitHub Repo](https://github.com/OpenAPITools/openapi-generator?tab=contributing-ov-file) [Docs](https://openapi-generator.tech/docs/generators/typescript). This code should not be modified manually as the changes will be overwritten by the generator. + +Improvements requiring changes to the generated code should be raised upstream in the OpenAPIGenerator repo. After they merge, update the sha in `/settings` and regenerate the project. Many changes can be made leveraging middleware to access or conditionally mutate requests without requiring changes to the generator itself. + +The generation uses inputs from the `/settings` file to configure refs used for generating the API, and pulls the spec from the [Kubernetes OpenAPI Spec](https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec) + +The OpenAPIGenerator config is in a shared repo for all kubernetes generated client configs at (kubernetes-client/gen](https://github.com/kubernetes-client/gen/blob/master/openapi/typescript.xml) + +Around this core of generated code in the `src/gen` folder, is the client layer that adds Kubernetes-specific features like kubeconfig auth, watches, serialization etc. Many of these functionalities attempt to bring parity with what kubectl offers, and expose higher-level ergonomics that require multiple REST calls to the kube-apiserver to create more convenient abstractions. + +For example: the `kubectl port-forward deploy/my-deployment` command does send a POST request to a .../deployments/... route, instead a pod is selected via listing and filtering, and then a POST to .../pods/.../portforward is sent. From 5ed860a39a3cf4d91a38863be5d7dad4a38b2a9b Mon Sep 17 00:00:00 2001 From: David Gamero Date: Wed, 21 Jan 2026 16:56:12 -0500 Subject: [PATCH 2/3] update contributingmd --- CONTRIBUTING.md | 117 ++++++++++++++++++++++++++++++++++++++++-------- README.md | 72 ++++++----------------------- 2 files changed, 112 insertions(+), 77 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8d581dfbca..7cc68a505d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,30 +4,47 @@ 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). +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 an issue +## 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 +## 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 assigns someone to review your PR. Check the full list of bot commands [here](https://prow.k8s.io/command-help). +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) -### Contact +For more detailed guidance, see the [Kubernetes contributor guide](https://github.com/kubernetes/community/blob/master/contributors/guide/README.md). -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. +## Architecture and Code Generation -## How it works +### Project Structure -### Generated Files +This repo has a 2-tiered structure: ``` /+ @@ -35,14 +52,78 @@ You can reach the maintainers of this project at [SIG API Machinery](https://git + gen/ <<< Automatically generated with OpenAPIGenerator, don't edit manually in Pull Requests ``` -This repo has a 2 tiered structure. The `/src/gen` repo contains code that is generated using the OpenAPI Generator [GitHub Repo](https://github.com/OpenAPITools/openapi-generator?tab=contributing-ov-file) [Docs](https://openapi-generator.tech/docs/generators/typescript). This code should not be modified manually as the changes will be overwritten by the generator. +The `/src/gen` folder contains code that 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 -Improvements requiring changes to the generated code should be raised upstream in the OpenAPIGenerator repo. After they merge, update the sha in `/settings` and regenerate the project. Many changes can be made leveraging middleware to access or conditionally mutate requests without requiring changes to the generator itself. +### Regenerating Code -The generation uses inputs from the `/settings` file to configure refs used for generating the API, and pulls the spec from the [Kubernetes OpenAPI Spec](https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec) +```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 +``` -The OpenAPIGenerator config is in a shared repo for all kubernetes generated client configs at (kubernetes-client/gen](https://github.com/kubernetes-client/gen/blob/master/openapi/typescript.xml) +## Contact -Around this core of generated code in the `src/gen` folder, is the client layer that adds Kubernetes-specific features like kubeconfig auth, watches, serialization etc. Many of these functionalities attempt to bring parity with what kubectl offers, and expose higher-level ergonomics that require multiple REST calls to the kube-apiserver to create more convenient abstractions. +You can reach the maintainers of this project at: -For example: the `kubectl port-forward deploy/my-deployment` command does send a POST request to a .../deployments/... route, instead a pod is selected via listing and filtering, and then a POST to .../pods/.../portforward is sent. +- [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 diff --git a/README.md b/README.md index bb97cd0ffe..7174df8e20 100644 --- a/README.md +++ b/README.md @@ -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: @@ -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. From db2cec16132f413b771fe1a2ad3c67f21a160fc0 Mon Sep 17 00:00:00 2001 From: David Gamero Date: Wed, 21 Jan 2026 17:05:21 -0500 Subject: [PATCH 3/3] remove ascii graphic --- CONTRIBUTING.md | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7cc68a505d..d548a493eb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -44,15 +44,9 @@ For more detailed guidance, see the [Kubernetes contributor guide](https://githu ### Project Structure -This repo has a 2-tiered structure: +This repo is built around a core of generated code that lives in the `/src/gen` directory -``` -/+ - + src/ - + gen/ <<< Automatically generated with OpenAPIGenerator, don't edit manually in Pull Requests -``` - -The `/src/gen` folder contains code that 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. +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