Skip to content

Commit 7e629ec

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #2751 from davidgamero/david/repo-info-update
add contributing.md repo links, cleanup
2 parents 25dc02b + db2cec1 commit 7e629ec

2 files changed

Lines changed: 124 additions & 69 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 111 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,120 @@ Thanks for taking the time to join our community and start contributing!
44

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

7-
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.
7+
## Getting Started
8+
9+
### Prerequisites
10+
11+
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:
12+
13+
```console
14+
npm install
15+
```
16+
17+
### Development Workflow
18+
19+
1. Fork this repo
20+
2. Create a feature branch
21+
3. Make your changes (see sections below for development guidelines)
22+
4. Test your changes (`npm test`)
23+
5. Ensure code is formatted (`npm run format`) and passes linting (`npm run lint`)
24+
6. Submit a pull request
825

926
## Sign the Contributor License Agreement
10-
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).
1127

12-
## Reporting an issue
28+
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).
29+
30+
## Reporting Issues
31+
1332
If you have any problem with the package or any suggestions, please file an [issue](https://github.com/kubernetes-client/javascript/issues).
1433

15-
## Contributing a Patch
16-
1. Submit an issue describing your proposed change to the repo.
17-
2. Fork this repo, develop and test your code changes.
18-
3. Submit a pull request.
19-
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).
34+
## Submitting a Pull Request
35+
36+
1. Submit an issue describing your proposed change to the repo
37+
2. Fork this repo, develop and test your code changes
38+
3. Submit a pull request
39+
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)
40+
41+
For more detailed guidance, see the [Kubernetes contributor guide](https://github.com/kubernetes/community/blob/master/contributors/guide/README.md).
42+
43+
## Architecture and Code Generation
44+
45+
### Project Structure
46+
47+
This repo is built around a core of generated code that lives in the `/src/gen` directory
48+
49+
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.
50+
51+
### Generated Code
52+
53+
- **Generator**: Uses [OpenAPI Generator](https://openapi-generator.tech/docs/generators/typescript) with TypeScript configuration
54+
- **Spec Source**: Pulls from the [Kubernetes OpenAPI Spec](https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec)
55+
- **Configuration**: Shared config at [kubernetes-client/gen](https://github.com/kubernetes-client/gen/blob/master/openapi/typescript.xml)
56+
- **Settings**: Generation inputs are configured in the `/settings` file
57+
58+
### Client Layer
59+
60+
Around the core generated code in `src/gen`, the client layer adds Kubernetes-specific features:
61+
62+
- Kubeconfig authentication
63+
- Watch functionality
64+
- Serialization
65+
- Higher-level ergonomics requiring multiple REST calls
66+
67+
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.
68+
69+
### Making Changes to Generated Code
70+
71+
If improvements require changes to the generated code:
72+
73+
1. Raise the issue upstream in the [OpenAPIGenerator repo](https://github.com/OpenAPITools/openapi-generator?tab=contributing-ov-file)
74+
2. After they merge, update the sha in `/settings`
75+
3. Regenerate the project using `npm run generate`
76+
77+
Many changes can be made using middleware to access or conditionally mutate requests without modifying the generator.
78+
79+
## Development Tasks
80+
81+
### Regenerating Code
82+
83+
```console
84+
npm run generate
85+
```
86+
87+
### Building Documentation
88+
89+
Documentation is generated via typedoc:
90+
91+
```console
92+
npm run docs
93+
```
94+
95+
To view the generated documentation, open `docs/index.html`
96+
97+
### Formatting
98+
99+
Run `npm run format` or install an editor plugin like:
100+
101+
- [Prettier for VS Code](https://github.com/prettier/prettier-vscode)
102+
- [EditorConfig](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig)
103+
104+
### Linting
105+
106+
Run `npm run lint` or install an editor plugin.
107+
108+
## Testing
109+
110+
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.
111+
112+
To run tests:
113+
114+
```console
115+
npm test
116+
```
117+
118+
## Contact
119+
120+
You can reach the maintainers of this project at:
20121

21-
### Contact
22-
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.
122+
- [SIG API Machinery](https://github.com/kubernetes/community/tree/master/sig-api-machinery)
123+
- [#kubernetes-client](https://kubernetes.slack.com/messages/kubernetes-client) channel on Kubernetes Slack

‎README.md‎

Lines changed: 13 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -114,17 +114,17 @@ We switched from `request` to `fetch` as the HTTP(S) backend for the `1.0.0` rel
114114

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

117-
| client version | older versions | 1.28 | 1.29 | 1.30 | 1.31 | 1.32 | 1.33|1.34|
118-
| -------------- | -------------- | ---- | ---- | ---- | ---- | ---- |----|----|
119-
| 0.19.x | - | ✓ | x | x | x | x | x | x |
120-
| 0.20.x | - | + | ✓ | x | x | x | x | x |
121-
| 0.21.x | - | + | + | ✓ | x | x | x | x |
122-
| 0.22.x | - | + | + | + | ✓ | x | x | x |
123-
| 1.0.x | - | + | + | + | + | ✓ | x | x |
124-
| 1.1.x | - | + | + | + | + | ✓ | x | x |
125-
| 1.2.x | - | + | + | + | + | + | ✓ | x |
126-
| 1.3.x | - | + | + | + | + | + | ✓ | x |
127-
| 1.4.x | - | + | + | + | + | + | + | ✓|
117+
| client version | older versions | 1.28 | 1.29 | 1.30 | 1.31 | 1.32 | 1.33 | 1.34 |
118+
| -------------- | -------------- | ---- | ---- | ---- | ---- | ---- | ---- | ---- |
119+
| 0.19.x | - | ✓ | x | x | x | x | x | x |
120+
| 0.20.x | - | + | ✓ | x | x | x | x | x |
121+
| 0.21.x | - | + | + | ✓ | x | x | x | x |
122+
| 0.22.x | - | + | + | + | ✓ | x | x | x |
123+
| 1.0.x | - | + | + | + | + | ✓ | x | x |
124+
| 1.1.x | - | + | + | + | + | ✓ | x | x |
125+
| 1.2.x | - | + | + | + | + | + | ✓ | x |
126+
| 1.3.x | - | + | + | + | + | + | ✓ | x |
127+
| 1.4.x | - | + | + | + | + | + | + | ✓ |
128128

129129
Key:
130130

@@ -147,52 +147,6 @@ Key:
147147

148148
- 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.
149149

150-
# Development
150+
# Contributing
151151

152-
All dependencies of this project are expressed in its
153-
[`package.json` file](package.json). Before you start developing, ensure
154-
that you have [NPM](https://www.npmjs.com/) installed, then run:
155-
156-
```console
157-
npm install
158-
```
159-
160-
## (re) Generating code
161-
162-
```console
163-
npm run generate
164-
```
165-
166-
## Documentation
167-
168-
Documentation is generated via typedoc:
169-
170-
```
171-
npm run docs
172-
```
173-
174-
To view the generated documentation, open `docs/index.html`
175-
176-
## Formatting
177-
178-
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
179-
180-
## Linting
181-
182-
Run `npm run lint` or install an editor plugin.
183-
184-
# Testing
185-
186-
Tests are written using the [`node:test`](https://nodejs.org/api/test.html) test runner and
187-
[`node:assert`](https://nodejs.org/api/assert.html) assertion library. See
188-
[`config_test.ts`](./src/config_test.ts) for an example.
189-
190-
To run tests, execute the following:
191-
192-
```console
193-
npm test
194-
```
195-
196-
## Contributing
197-
198-
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for instructions on how to contribute.
152+
Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and contribution guidelines.

0 commit comments

Comments
 (0)