diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1ce66d7d71..d548a493eb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 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.