Skip to content

Latest commit

 

History

History
123 lines (75 loc) · 4.45 KB

CONTRIBUTING.md

File metadata and controls

123 lines (75 loc) · 4.45 KB

Contributing

Thanks for taking the time to join our community and start contributing!

Please remember to read and observe the Code of Conduct.

Getting Started

Prerequisites

All dependencies of this project are expressed in its package.json file. Before you start developing, ensure that you have NPM installed, then run:

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 the Cloud Native Computing Foundation (CNCF) CLA.

Reporting Issues

If you have any problem with the package or any suggestions, please file an issue.

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

For more detailed guidance, see the Kubernetes contributor guide.

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. This code should not be modified manually as changes will be overwritten by the generator.

Generated Code

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
  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

npm run generate

Building 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:

Linting

Run npm run lint or install an editor plugin.

Testing

Tests are written using the node:test test runner and node:assert assertion library. See config_test.ts for an example.

To run tests:

npm test

Contact

You can reach the maintainers of this project at: