Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

upgrade Blackfriday to v2 and re-implement render #112731

Merged
merged 3 commits into from Sep 29, 2022
Merged

upgrade Blackfriday to v2 and re-implement render #112731

merged 3 commits into from Sep 29, 2022

Conversation

pacoxu
Copy link
Member

@pacoxu pacoxu commented Sep 26, 2022 •
edited

What type of PR is this?

/kind feature
/sig cli

What this PR does / why we need it:

Which issue(s) this PR fixes:

Fixes #112717

Special notes for your reviewer:

github.com/russross/blackfriday/v2 is already used in other components.
github.com/russross/blackfriday is removed with this PR.

Does this PR introduce a user-facing change?

switch kubectl to use `github.com/russross/blackfriday/v2`

@k8s-ci-robot
Copy link
Contributor

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

@k8s-ci-robot k8s-ci-robot added do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. release-note Denotes a PR that will be considered when it comes time to generate release notes. kind/feature Categorizes issue or PR as related to a new feature. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. sig/cli Categorizes an issue or PR as relevant to SIG CLI. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Sep 26, 2022
@k8s-ci-robot k8s-ci-robot added the area/dependency Issues or PRs related to dependency changes label Sep 26, 2022
@k8s-ci-robot k8s-ci-robot requested review from soltysh and a team September 26, 2022 09:13
@k8s-ci-robot k8s-ci-robot added area/kubectl needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. labels Sep 26, 2022
@k8s-ci-robot
Copy link
Contributor

@pacoxu: This issue is currently awaiting triage.

If a SIG or subproject determines this is a relevant issue, they will accept it by applying the triage/accepted label and provide further guidance.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

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.

@k8s-ci-robot k8s-ci-robot added the needs-priority Indicates a PR lacks a `priority/foo` label and requires one. label Sep 26, 2022
@pacoxu pacoxu marked this pull request as ready for review September 26, 2022 09:13
@k8s-ci-robot k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Sep 26, 2022
@liggitt
Copy link
Member

liggitt commented Sep 26, 2022

where is this kubectl output used? is there any way to verify the updated output with the new implementation (alternatively, if it's not used, can we drop this impl altogether)

@pacoxu
Copy link
Member Author

pacoxu commented Sep 27, 2022

where is this kubectl output used? is there any way to verify the updated output with the new implementation (alternatively, if it's not used, can we drop this impl altogether)

Currently, all kubectl commands will use it like below. templates.LongDesc.

	applyLong = templates.LongDesc(i18n.T(`
		Apply a configuration to a resource by file name or stdin.

https://github.com/kubernetes/kubernetes/search?q=templates.LongDesc
I did some tests locally, for instance, ./kubectl get -h. With default blackfriday v2 HTML render, there will be many <p> for lines.

kubeadm has some similar test cases in

kubernetes/cmd/kubeadm/app/cmd/util/documentation_test.go

Lines 23 to 84 in ea07644

func TestLongDesc(t *testing.T) {
tests := []struct {
desc string
in string
out string
}{
{
desc: "Empty input produces empty output",
in: "",
out: "",
},
{
desc: "Single line text is preserved as is",
in: "Some text",
out: "Some text",
},
{
desc: "Consecutive new lines are combined into a single paragraph",
in: "Line1\nLine2",
out: "Line1 Line2",
},
{
desc: "Leading and trailing spaces are stripped (single line)",
in: "\t \nThe text line \n \t",
out: "The text line",
},
{
desc: "Leading and trailing spaces are stripped (multi line)",
in: "\t \nLine1\nLine2 \n \t",
out: "Line1 Line2",
},
{
desc: "Multiple paragraphs are separated by a single empty line",
in: "Paragraph1\n\nParagraph2\n\n\nParagraph3",
out: "Paragraph1\n\nParagraph2\n\nParagraph3",
},
{
desc: "Indentation is not preserved",
in: "\tParagraph1Line1\n\tParagraph1Line2\n\n Paragraph2Line1\n Paragraph2Line2",
out: "Paragraph1Line1 Paragraph1Line2\n\nParagraph2Line1 Paragraph2Line2",
},
{
desc: "Double spaced line breaks",
in: "Line1 \nLine2",
out: "Line1\nLine2",
},
{
desc: "Double spaced line breaks don't preserve indentation",
in: "\tLine1 \n\tLine2",
out: "Line1\nLine2",
},
}
for _, test := range tests {
t.Run(test.desc, func(t *testing.T) {
got := LongDesc(test.in)
if got != test.out {
t.Errorf("expected(%d):\n%s\n=====\ngot(%d):\n%s\n", len(test.out), test.out, len(got), got)
}
})
}
}

We may follow that to add some unit tests if needed. Let me add some test cases.
/hold

@k8s-ci-robot k8s-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Sep 27, 2022
@pacoxu
Copy link
Member Author

pacoxu commented Sep 27, 2022 •
edited

/hold cancel
I added some test cases in staging/src/k8s.io/kubectl/pkg/util/templates/normalizers_test.go for this.

kubectl taint --help and kubectl config --help may be the simplest test cases for this change.

@k8s-ci-robot k8s-ci-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Sep 27, 2022
liggitt
liggitt reviewed Sep 27, 2022
View reviewed changes
staging/src/k8s.io/kubectl/pkg/util/templates/normalizers.go
@@ -70,7 +70,7 @@ type normalizer struct {

func (s normalizer) markdown() normalizer {
bytes := []byte(s.string)
formatted := blackfriday.Markdown(bytes, &ASCIIRenderer{Indentation: Indentation}, blackfriday.EXTENSION_NO_INTRA_EMPHASIS)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

was whatever prompted use of EXTENSION_NO_INTRA_EMPHASIS tested, since it doesn't look like we're using it in v2

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked an example ./kubectl apply edit-last-applied --help and there is no difference.

kubernetes/staging/src/k8s.io/kubectl/pkg/cmd/apply/apply_edit_last_applied.go

Lines 31 to 50 in c18c244

applyEditLastAppliedLong = templates.LongDesc(i18n.T(`
Edit the latest last-applied-configuration annotations of resources from the default editor.
The edit-last-applied command allows you to directly edit any API resource you can retrieve via the
command-line tools. It will open the editor defined by your KUBE_EDITOR, or EDITOR
environment variables, or fall back to 'vi' for Linux or 'notepad' for Windows.
You can edit multiple objects, although changes are applied one at a time. The command
accepts file names as well as command-line arguments, although the files you point to must
be previously saved versions of resources.
The default format is YAML. To edit in JSON, specify "-o json".
The flag --windows-line-endings can be used to force Windows line endings,
otherwise the default for your operating system will be used.
In the event an error occurs while updating, a temporary file will be created on disk
that contains your unapplied changes. The most common error when updating a resource
is another editor changing the resource on the server. When this occurs, you will have
to apply your changes to the newer version of the resource, or update your temporary
saved copy to include the latest resource version.`))

Some old issues before that may be related: spf13/cobra#518.

To keep it consistent, we can use blackfriday.WithExtensions(blackfriday.NoIntraEmphasis) instead. Updated.

@pacoxu pacoxu force-pushed the blackfriday-v2 branch 2 times, most recently from 7253978 to 6e567dc Compare September 27, 2022 18:30
@liggitt
Copy link
Member

liggitt commented Sep 29, 2022

/lgtm
/approve

@k8s-ci-robot k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Sep 29, 2022
@k8s-ci-robot
Copy link
Contributor

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: liggitt, pacoxu

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:

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

@k8s-ci-robot k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Sep 29, 2022
@k8s-ci-robot k8s-ci-robot merged commit 8d1ba6a into kubernetes:master Sep 29, 2022
@k8s-ci-robot k8s-ci-robot added this to the v1.26 milestone Sep 29, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@liggitt liggitt liggitt left review comments

@logicalhan logicalhan Awaiting requested review from logicalhan

@soltysh soltysh Awaiting requested review from soltysh

@dougsland dougsland Awaiting requested review from dougsland

Assignees

@liggitt liggitt

Labels
approved Indicates a PR has been approved by an approver from all required OWNERS files. area/dependency Issues or PRs related to dependency changes area/kubectl cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. kind/feature Categorizes issue or PR as related to a new feature. lgtm "Looks good to me", indicates that a PR is ready to be merged. needs-priority Indicates a PR lacks a `priority/foo` label and requires one. needs-triage Indicates an issue or PR lacks a `triage/foo` label and requires one. release-note Denotes a PR that will be considered when it comes time to generate release notes. sig/cli Categorizes an issue or PR as relevant to SIG CLI. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.
Projects
None yet
Milestone
v1.26
Development

Successfully merging this pull request may close these issues.

Switch kubectl to use github.com/russross/blackfriday/v2
3 participants
@pacoxu @k8s-ci-robot @liggitt