Skip to content

Commit 30815cd

Browse files
xrstfxrstf
committed
update readme
On-behalf-of: @SAP [email protected]
1 parent 22ec856 commit 30815cd

File tree

3 files changed

+148
-31
lines changed

3 files changed

+148
-31
lines changed

‎README.md‎

Lines changed: 64 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,77 @@
1-
## Code Generators for KCP-aware informers and listers
1+
## Code Generators for KCP-aware clients, informers and listers
22

3-
### Usage:
3+
This repository contains code generation tools analogous to the Kubernetes
4+
code-generator. It contains:
45

5-
```
6-
code-generator <command> [input-flags]
7-
```
8-
9-
where `<command>` can be one of:
10-
- lister
11-
- informer
6+
* `cluster-client-gen` to generate a cluster-aware clientset,
7+
* `cluster-informer-gen` to generate cluster-aware informers and
8+
* `cluster-lister-gen` to do the same for listers.
129

13-
It is possible to run the code generation for multiple components at once `code-generator lister,informer [input-flags]`
10+
Note that you need to have generated the versioned Kubernetes clientset and
11+
applyconfiguration packages already in order to generate and use cluster-aware
12+
code. Single-cluster listers and informers however are optional and the
13+
generator here can generate the necessary interfaces itself.
1414

15-
#### Input flags:
15+
### Usage
1616

17-
1. `--input-dir` - The directory path where APIs are defined. Make sure that the types are defined in `<inputDir>/pkg/apis/{$GROUP}/{$VERSION}`. For example, if your input apis are defined in `types.go` inside `examples/pkg/apis/apps/v1/types.go`, the input directory should be specified as `examples/pkg`. `{$GROUP}/{$VERSION}` is appended in the input path.
18-
**Note**: This is the relative path to the input directory where APIs live.
17+
It is strongly recommended to use the provided `cluster_codegen.sh`, which works
18+
very much like Kubernetes' `kube_codegen.sh`. A common way to acquire it is to
19+
have a synthetic Go dependency on `github.com/kcp-dev/code-generator/v3/cmd/cluster-client-gen`
20+
(often done in a `hack/tools.go`) and then call it like so in your project:
1921

20-
2. `--output-dir` - The directory where output clients are to be generated. It defaults to the `output` folder under current working directory.
21-
- Listers are output to `<outputDir>/listers/${GROUP}/${VERSION}/${TYPE}.go`
22-
- Individual informers are output to `<outputDir>/informers/externalversions/${GROUP}/${VERSION}/${TYPE}.go`
22+
```bash
23+
# Often you would want to generate both the regular Kubernetes clientset and
24+
# the cluster-aware clienset.
2325

24-
3. `--clientset-api-path` - The path to where `clientset` generated by `k8s.io/code-gen` is present.
26+
CODEGEN_PKG="$(go list -f '{{.Dir}}' -m k8s.io/code-generator)"
27+
CLUSTER_CODEGEN_PKG="$(go list -f '{{.Dir}}' -m github.com/kcp-dev/code-generator/v3)"
2528

26-
4. `--group-versions` - List of group versions in the format `group:version`. Define multiple groups by specifying the flag again. For example, the inputs can be:
27-
- `--group-version="apps:v1"`
28-
- `--group-versions="rbac:v1" --group-versions="apps:v1"`
29-
- `--group-version="rbac:v1,v2"`
29+
source "$CODEGEN_PKG/kube_codegen.sh"
30+
source "$CLUSTER_CODEGEN_PKG/cluster_codegen.sh"
3031

31-
5. `--go-header-file` - Path to the header file.
32+
# Now you can call kube::codegen:: and cluster::codegen:: functions.
3233

33-
Example:
34-
To run it locally and see how it works, use the following command:
34+
kube::codegen::gen_client \
35+
--boilerplate hack/boilerplate/examples/boilerplate.generatego.txt \
36+
--output-dir pkg/generated \
37+
--output-pkg acme.corp/pkg/generated \
38+
--with-applyconfig \
39+
--applyconfig-name applyconfigurations \
40+
--with-watch \
41+
./pkg/apis
3542

43+
cluster::codegen::gen_client \
44+
--boilerplate hack/boilerplate/examples/boilerplate.generatego.txt \
45+
--output-dir pkg/clients \
46+
--output-pkg acme.corp/pkg/clients \
47+
--with-watch \
48+
--single-cluster-versioned-clientset-pkg acme.corp/pkg/generated/clientset/versioned \
49+
--single-cluster-applyconfigurations-pkg acme.corp/pkg/generated/applyconfigurations \
50+
--single-cluster-listers-pkg acme.corp/pkg/generated/listers \
51+
--single-cluster-informers-pkg acme.corp/pkg/generated/informers/externalversions \
52+
pkg/apis
3653
```
37-
go run main.go informer,lister --go-header-file testdata/header.txt
38-
--clientset-api-path=github.com/kcp-dev/code-generator/testdata/pkg/generated/clientset/versioned
39-
--input-dir testdata/pkg/apis
40-
--output-dir testdata/pkg --group-versions example:v1
41-
```
4254

43-
creates output folders in `testdata/pkg/informers` and `testdata/pkg/listers`.
55+
Please refer to the [cluster_codegen.sh](./cluster_codegen.sh) for more information
56+
on the available command line flags.
57+
58+
## Contributing
59+
60+
We ❤️ our contributors! If you're interested in helping us out, please check out [contributing to kcp](https://docs.kcp.io/kcp/main/contributing/).
61+
62+
This community has a [Code of Conduct](./code-of-conduct.md). Please make sure to follow it.
63+
64+
## Getting in touch
65+
66+
There are several ways to communicate with us:
67+
68+
- The [`#kcp-dev` channel](https://app.slack.com/client/T09NY5SBT/C021U8WSAFK) in the [Kubernetes Slack workspace](https://slack.k8s.io).
69+
- Our mailing lists:
70+
- [kcp-dev](https://groups.google.com/g/kcp-dev) for development discussions.
71+
- [kcp-users](https://groups.google.com/g/kcp-users) for discussions among users and potential users.
72+
- By joining the kcp-dev mailing list, you should receive an invite to our bi-weekly community meetings.
73+
- See recordings of past community meetings on [YouTube](https://www.youtube.com/channel/UCfP_yS5uYix0ppSbm2ltS5Q).
74+
- The next community meeting dates are available via our [CNCF community group](https://community.cncf.io/kcp/).
75+
- Check the [community meeting notes document](https://docs.google.com/document/d/1PrEhbmq1WfxFv1fTikDBZzXEIJkUWVHdqDFxaY1Ply4) for future and past meeting agendas.
76+
- Browse the [shared Google Drive](https://drive.google.com/drive/folders/1FN7AZ_Q1CQor6eK0gpuKwdGFNwYI517M?usp=sharing) to share design docs, notes, etc.
77+
- Members of the kcp-dev mailing list can view this drive.

‎code-of-conduct.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
This project is following the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md).
2+
3+
# Community Code of Conduct
4+
5+
As contributors, maintainers, and participants in the CNCF community, and in the interest of fostering
6+
an open and welcoming community, we pledge to respect all people who participate or contribute
7+
through reporting issues, posting feature requests, updating documentation,
8+
submitting pull requests or patches, attending conferences or events, or engaging in other community or project activities.
9+
10+
We are committed to making participation in the CNCF community a harassment-free experience for everyone, regardless of age, body size, caste, disability, ethnicity, level of experience, family status, gender, gender identity and expression, marital status, military or veteran status, nationality, personal appearance, race, religion, sexual orientation, socieconomic status, tribe, or any other dimension of diversity.
11+
12+
## Scope
13+
14+
This code of conduct applies:
15+
* within project and community spaces,
16+
* in other spaces when an individual CNCF community participant's words or actions are directed at or are about a CNCF project, the CNCF community, or another CNCF community participant.
17+
18+
### CNCF Events
19+
20+
CNCF events that are produced by the Linux Foundation with professional events staff are governed by the Linux Foundation [Events Code of Conduct](https://events.linuxfoundation.org/code-of-conduct/) available on the event page. This is designed to be used in conjunction with the CNCF Code of Conduct.
21+
22+
## Our Standards
23+
24+
The CNCF Community is open, inclusive and respectful. Every member of our community has the right to have their identity respected.
25+
26+
Examples of behavior that contributes to a positive environment include but are not limited to:
27+
28+
* Demonstrating empathy and kindness toward other people
29+
* Being respectful of differing opinions, viewpoints, and experiences
30+
* Giving and gracefully accepting constructive feedback
31+
* Accepting responsibility and apologizing to those affected by our mistakes,
32+
and learning from the experience
33+
* Focusing on what is best not just for us as individuals, but for the
34+
overall community
35+
* Using welcoming and inclusive language
36+
37+
38+
Examples of unacceptable behavior include but are not limited to:
39+
40+
* The use of sexualized language or imagery
41+
* Trolling, insulting or derogatory comments, and personal or political attacks
42+
* Public or private harassment in any form
43+
* Publishing others' private information, such as a physical or email
44+
address, without their explicit permission
45+
* Violence, threatening violence, or encouraging others to engage in violent behavior
46+
* Stalking or following someone without their consent
47+
* Unwelcome physical contact
48+
* Unwelcome sexual or romantic attention or advances
49+
* Other conduct which could reasonably be considered inappropriate in a
50+
professional setting
51+
52+
The following behaviors are also prohibited:
53+
* Providing knowingly false or misleading information in connection with a Code of Conduct investigation or otherwise intentionally tampering with an investigation.
54+
* Retaliating against a person because they reported an incident or provided information about an incident as a witness.
55+
56+
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct.
57+
By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect
58+
of managing a CNCF project.
59+
Project maintainers who do not follow or enforce the Code of Conduct may be temporarily or permanently removed from the project team.
60+
61+
## Reporting
62+
63+
For incidents occurring in the Kubernetes community, contact the [Kubernetes Code of Conduct Committee](https://git.k8s.io/community/committee-code-of-conduct) via <[email protected]>. You can expect a response within three business days.
64+
65+
For other projects, or for incidents that are project-agnostic or impact multiple CNCF projects, please contact the [CNCF Code of Conduct Committee](https://www.cncf.io/conduct/committee/) via [email protected]. Alternatively, you can contact any of the individual members of the [CNCF Code of Conduct Committee](https://www.cncf.io/conduct/committee/) to submit your report. For more detailed instructions on how to submit a report, including how to submit a report anonymously, please see our [Incident Resolution Procedures](https://www.cncf.io/conduct/procedures/). You can expect a response within three business days.
66+
67+
For incidents occurring at CNCF event that is produced by the Linux Foundation, please contact [email protected].
68+
69+
## Enforcement
70+
71+
Upon review and investigation of a reported incident, the CoC response team that has jurisdiction will determine what action is appropriate based on this Code of Conduct and its related documentation.
72+
73+
For information about which Code of Conduct incidents are handled by project leadership, which incidents are handled by the CNCF Code of Conduct Committee, and which incidents are handled by the Linux Foundation (including its events team), see our [Jurisdiction Policy](https://www.cncf.io/conduct/jurisdiction/).
74+
75+
## Amendments
76+
77+
Consistent with the CNCF Charter, any substantive changes to this Code of Conduct must be approved by the Technical Oversight Committee.
78+
79+
## Acknowledgements
80+
81+
This Code of Conduct is adapted from the Contributor Covenant
82+
(http://contributor-covenant.org), version 2.0 available at
83+
http://contributor-covenant.org/version/2/0/code_of_conduct/

‎pkg/imports/kcptracker.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,7 +70,7 @@ func goTrackerLocalName(tracker namer.ImportTracker, localPkg string, t types.Na
7070

7171
if _, found := tracker.PathOf(name); found || name == localLeaf {
7272
// This name collides with some other package.
73-
// Or, this name is tne same name as the local package,
73+
// Or, this name is the same name as the local package,
7474
// which we avoid because it can be confusing. For example,
7575
// if the local package is v1, we to avoid importing
7676
// another package using the v1 name, and instead import

0 commit comments

Comments
 (0)