How to manage lifted codes

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
• How to write lifted comments
• 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.
• 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:

// +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:

| 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

// +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:

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

// +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:

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

// +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:

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