Add missing word to ServiceSpec doc #97896

brpratt · 2021-01-10T23:29:47Z

What type of PR is this?

/kind documentation

What this PR does / why we need it:

The description for externalName in ServiceSpec ends rather abruptly:

Must be a lowercase RFC-1123 hostname (https://tools.ietf.org/html/rfc1123) and requires Type to be

This PR adds the missing ExternalName to the end of this description.

Must be a lowercase RFC-1123 hostname (https://tools.ietf.org/html/rfc1123) and requires Type to be ExternalName

Which issue(s) this PR fixes:

Fixes #

Special notes for your reviewer:

Does this PR introduce a user-facing change?:

NONE

Additional documentation e.g., KEPs (Kubernetes Enhancement Proposals), usage docs, etc.:

k8s-ci-robot · 2021-01-10T23:29:55Z

Welcome @brpratt!

It looks like this is your first PR to kubernetes/kubernetes 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes/kubernetes has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

k8s-ci-robot · 2021-01-10T23:29:55Z

Hi @brpratt. Thanks for your PR.

I'm waiting for a kubernetes member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

fejta-bot · 2021-01-10T23:59:20Z

This PR may require API review.

If so, when the changes are ready, complete the pre-review checklist and request an API review.

Status of requested reviews is tracked in the API Review project.

tengqm · 2021-01-11T11:34:02Z

/ok-to-test

tengqm · 2021-01-11T11:35:14Z

staging/src/k8s.io/api/core/v1/types.go

@@ -4150,7 +4150,7 @@ type ServiceSpec struct {
 	// externalName is the external reference that discovery mechanisms will
 	// return as an alias for this service (e.g. a DNS CNAME record). No
 	// proxying will be involved.  Must be a lowercase RFC-1123 hostname
-	// (https://tools.ietf.org/html/rfc1123) and requires Type to be
+	// (https://tools.ietf.org/html/rfc1123) and requires Type to be ExternalName


Suggested change

// (https://tools.ietf.org/html/rfc1123) and requires Type to be ExternalName

// (https://tools.ietf.org/html/rfc1123) and requires `type` to be "ExternalName".

I will make the suggested change and regenerate the other files.

Is there a convention doc I can reference that explains how to annotate these comments? From the suggestion, it appears as though field names should be surrounded by backticks and field values are surrounded by double quotes. I noticed that this convention isn't followed for many other field descriptions.

For example, should similar changes be made in the comment for the HealthCheckNodePort field in ServiceSpec?

The rule of thumb is that the comments are used to generate user-facing documents. Users will see field names encoded in the JSON (OpenAPI spec), not the Golang field name. That is the reason we need to change "Type" to type. The ExternalName is a string value to be assigned to the type field, adding the double quotes is for clarification.

brpratt · 2021-01-11T21:42:30Z

/test pull-kubernetes-e2e-gce-ubuntu-containerd

aojea · 2021-01-12T10:26:54Z

staging/src/k8s.io/api/core/v1/types.go

@@ -4150,7 +4150,7 @@ type ServiceSpec struct {
 	// externalName is the external reference that discovery mechanisms will
 	// return as an alias for this service (e.g. a DNS CNAME record). No
 	// proxying will be involved.  Must be a lowercase RFC-1123 hostname
-	// (https://tools.ietf.org/html/rfc1123) and requires Type to be
+	// (https://tools.ietf.org/html/rfc1123) and requires `type` to be "ExternalName".


I couldn't´t find any other place on the files that uses backticks for type , should we keep it as is?

I added backticks per this suggestion:

#97896 (comment)

Indeed, I can't find many usages of backticks in this file, but I didn't know if using backticks to annotate field names was a new convention.

ups sorry, I missed it, my fault, scratch my comment please

ehashman · 2021-01-14T00:06:53Z

/sig api-machinery

fedebongio · 2021-01-14T21:10:53Z

/assign @lavalamp
/triage accepted

lavalamp · 2021-01-14T21:46:39Z

/lgtm
/approve

k8s-ci-robot · 2021-01-14T21:47:16Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: brpratt, lavalamp

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~api/OWNERS~~ [lavalamp]
~~staging/src/k8s.io/api/OWNERS~~ [lavalamp]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

fejta-bot · 2021-01-15T00:54:29Z

/retest
This bot automatically retries jobs that failed/flaked on approved PRs (send feedback to fejta).

Review the full test history for this PR.

Silence the bot with an /lgtm cancel or /hold comment for consistent failures.

fejta-bot · 2021-01-15T05:27:29Z

/retest
This bot automatically retries jobs that failed/flaked on approved PRs (send feedback to fejta).

Review the full test history for this PR.

Silence the bot with an /lgtm cancel or /hold comment for consistent failures.

k8s-ci-robot added needs-priority Indicates a PR lacks a `priority/foo` label and requires one. needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Jan 10, 2021

k8s-ci-robot requested review from caesarxuchao and davidopp January 10, 2021 23:30

k8s-ci-robot added the kind/api-change Categorizes issue or PR as related to adding, removing, or otherwise changing an API label Jan 10, 2021

k8s-ci-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Jan 11, 2021

tengqm reviewed Jan 11, 2021

View reviewed changes

add missing ExternalName to doc

5c82e44

brpratt force-pushed the fix-external-name-doc branch from a9560e9 to 5c82e44 Compare January 11, 2021 19:25

aojea reviewed Jan 12, 2021

View reviewed changes

k8s-ci-robot added sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. and removed do-not-merge/needs-sig Indicates an issue or PR lacks a `sig/foo` label and requires one. labels Jan 14, 2021

k8s-ci-robot assigned lavalamp Jan 14, 2021

k8s-ci-robot added triage/accepted Indicates an issue or PR is ready to be actively worked on. and removed needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. labels Jan 14, 2021

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jan 14, 2021

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Jan 14, 2021

k8s-ci-robot merged commit 083290d into kubernetes:master Jan 15, 2021

k8s-ci-robot added this to the v1.21 milestone Jan 15, 2021

brpratt deleted the fix-external-name-doc branch February 17, 2022 01:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add missing word to ServiceSpec doc #97896

Add missing word to ServiceSpec doc #97896

brpratt commented Jan 10, 2021

k8s-ci-robot commented Jan 10, 2021

k8s-ci-robot commented Jan 10, 2021

fejta-bot commented Jan 10, 2021

tengqm commented Jan 11, 2021

tengqm Jan 11, 2021 •

edited

Loading

brpratt Jan 11, 2021

tengqm Jan 12, 2021

brpratt commented Jan 11, 2021

aojea Jan 12, 2021 •

edited

Loading

brpratt Jan 12, 2021

aojea Jan 12, 2021 •

edited

Loading

ehashman commented Jan 14, 2021

fedebongio commented Jan 14, 2021

lavalamp commented Jan 14, 2021

k8s-ci-robot commented Jan 14, 2021

fejta-bot commented Jan 15, 2021

fejta-bot commented Jan 15, 2021

	// (https://tools.ietf.org/html/rfc1123) and requires Type to be ExternalName
	// (https://tools.ietf.org/html/rfc1123) and requires `type` to be "ExternalName".

Add missing word to ServiceSpec doc #97896

Add missing word to ServiceSpec doc #97896

Conversation

brpratt commented Jan 10, 2021

k8s-ci-robot commented Jan 10, 2021

k8s-ci-robot commented Jan 10, 2021

fejta-bot commented Jan 10, 2021

tengqm commented Jan 11, 2021

tengqm Jan 11, 2021 • edited Loading

Choose a reason for hiding this comment

brpratt Jan 11, 2021

Choose a reason for hiding this comment

tengqm Jan 12, 2021

Choose a reason for hiding this comment

brpratt commented Jan 11, 2021

aojea Jan 12, 2021 • edited Loading

Choose a reason for hiding this comment

brpratt Jan 12, 2021

Choose a reason for hiding this comment

aojea Jan 12, 2021 • edited Loading

Choose a reason for hiding this comment

ehashman commented Jan 14, 2021

fedebongio commented Jan 14, 2021

lavalamp commented Jan 14, 2021

k8s-ci-robot commented Jan 14, 2021

fejta-bot commented Jan 15, 2021

fejta-bot commented Jan 15, 2021

tengqm Jan 11, 2021 •

edited

Loading

aojea Jan 12, 2021 •

edited

Loading

aojea Jan 12, 2021 •

edited

Loading