115 lines
5.7 KiB
Markdown
115 lines
5.7 KiB
Markdown
# Overview
|
||
This document explains how lifted code is managed.
|
||
A common user case for this task is developer lifting code from other repositories to `pkg/util/lifted` directory.
|
||
|
||
- [Steps of lifting code](#steps-of-lifting-code)
|
||
- [How to write lifted comments](#how-to-write-lifted-comments)
|
||
- [Examples](#examples)
|
||
|
||
## Steps of lifting code
|
||
- Copy code from another repository and save it to a go file under `pkg/util/lifted`.
|
||
- Optionally change the lifted code.
|
||
- Add lifted comments for the code [as guided](#how-to-write-lifted-comments).
|
||
- Run `hack/update-lifted.sh` to update the lifted doc `pkg/util/lifted/doc.go`.
|
||
|
||
## How to write lifted comments
|
||
Lifted comments shall be placed just before the lifted code (could be a func, type, var or const). Only empty lines and comments are allowed between lifted comments and lifted code.
|
||
|
||
Lifted comments are composed by one or multi comment lines, each in the format of `+lifted:KEY[=VALUE]`. Value is optional for some keys.
|
||
|
||
Valid keys are as follow：
|
||
|
||
- source:
|
||
|
||
Key `source` is required. Its value indicates where the code is lifted from.
|
||
|
||
- changed:
|
||
|
||
Key `changed` is optional. It indicates whether the code is changed. Value is optional (`true` or `false`, defaults to `true`). Not adding this key or setting it to `false` means no code change.
|
||
|
||
## Examples
|
||
### Lifting function
|
||
|
||
Lift function `IsQuotaHugePageResourceName` to `corehelpers.go`:
|
||
|
||
```go
|
||
// +lifted:source=https://github.com/kubernetes/kubernetes/blob/release-1.23/pkg/apis/core/helper/helpers.go#L57-L61
|
||
|
||
// IsQuotaHugePageResourceName returns true if the resource name has the quota
|
||
// related huge page resource prefix.
|
||
func IsQuotaHugePageResourceName(name corev1.ResourceName) bool {
|
||
return strings.HasPrefix(string(name), corev1.ResourceHugePagesPrefix) || strings.HasPrefix(string(name), corev1.ResourceRequestsHugePagesPrefix)
|
||
}
|
||
```
|
||
|
||
Added in `doc.go`:
|
||
|
||
```markdown
|
||
| lifted file | source file | const/var/type/func | changed |
|
||
|--------------------------|-------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|---------|
|
||
| corehelpers.go | https://github.com/kubernetes/kubernetes/blob/release-1.23/pkg/apis/core/helper/helpers.go#L57-L61 | func IsQuotaHugePageResourceName | N |
|
||
```
|
||
|
||
### Changed lifting function
|
||
|
||
Lift and change function `GetNewReplicaSet` to `deployment.go`
|
||
|
||
```go
|
||
// +lifted:source=https://github.com/kubernetes/kubernetes/blob/release-1.22/pkg/controller/deployment/util/deployment_util.go#L536-L544
|
||
// +lifted:changed
|
||
|
||
// GetNewReplicaSet returns a replica set that matches the intent of the given deployment; get ReplicaSetList from client interface.
|
||
// Returns nil if the new replica set doesn't exist yet.
|
||
func GetNewReplicaSet(deployment *appsv1.Deployment, f ReplicaSetListFunc) (*appsv1.ReplicaSet, error) {
|
||
rsList, err := ListReplicaSetsByDeployment(deployment, f)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
return FindNewReplicaSet(deployment, rsList), nil
|
||
}
|
||
```
|
||
|
||
Added in `doc.go`:
|
||
|
||
```markdown
|
||
| lifted file | source file | const/var/type/func | changed |
|
||
|--------------------------|-------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|---------|
|
||
| deployment.go | https://github.com/kubernetes/kubernetes/blob/release-1.22/pkg/controller/deployment/util/deployment_util.go#L536-L544 | func GetNewReplicaSet | Y |
|
||
```
|
||
|
||
### Lifting const
|
||
|
||
Lift const `isNegativeErrorMsg` to `corevalidation.go `:
|
||
|
||
```go
|
||
// +lifted:source=https://github.com/kubernetes/kubernetes/blob/release-1.22/pkg/apis/core/validation/validation.go#L59
|
||
const isNegativeErrorMsg string = apimachineryvalidation.IsNegativeErrorMsg
|
||
```
|
||
|
||
Added in `doc.go`:
|
||
|
||
```markdown
|
||
| lifted file | source file | const/var/type/func | changed |
|
||
|--------------------------|-------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|---------|
|
||
| corevalidation.go | https://github.com/kubernetes/kubernetes/blob/release-1.22/pkg/apis/core/validation/validation.go#L59 | const isNegativeErrorMsg | N |
|
||
```
|
||
|
||
### Lifting type
|
||
|
||
Lift type `Visitor` to `visitpod.go`:
|
||
|
||
```go
|
||
// +lifted:source=https://github.com/kubernetes/kubernetes/blob/release-1.23/pkg/api/v1/pod/util.go#L82-L83
|
||
|
||
// Visitor is called with each object name, and returns true if visiting should continue
|
||
type Visitor func(name string) (shouldContinue bool)
|
||
```
|
||
|
||
Added in `doc.go`:
|
||
|
||
```markdown
|
||
| lifted file | source file | const/var/type/func | changed |
|
||
|--------------------------|-------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------|---------|
|
||
| visitpod.go | https://github.com/kubernetes/kubernetes/blob/release-1.23/pkg/api/v1/pod/util.go#L82-L83 | type Visitor | N |
|
||
```
|