site: custom index docs #618

chriskim06 · 2020-07-01T02:41:27Z

Let me know what you guys think. Also what do I need to do to mark this as draft?

Related issue: #566

/area multi-index
/area docs

ahmetb · 2020-07-01T02:53:40Z

I'll make a pass by adding commits, stay tuned.

ahmetb · 2020-07-01T03:15:04Z

Just did a pass by:

merge 2 user guides into 1
remove some cmd outputs that weren't useful
rewrite some paragraphs
change titles to be task oriented "Using Custom Plugin Indexes" and "Hosting Custom Plugin Indexes"
emphasis on calling them "Custom Plugin Indexes" and not "custom indexes" which causes a new term to be coined.

ahmetb · 2020-07-01T03:15:57Z

Actually could not push the commit. @chriskim06 do you mind choosing "allow maintainers to push additional commits" on the right?

ahmetb · 2020-07-01T04:03:44Z

Preview:
https://deploy-preview-618--kubernetes-sigs-krew.netlify.app/docs/user-guide/custom-indexes/
https://deploy-preview-618--kubernetes-sigs-krew.netlify.app/docs/developer-guide/custom-indexes/

Signed-off-by: Ahmet Alp Balkan <ahmetb@google.com>

ahmetb · 2020-07-01T04:18:05Z

Pushed some more changes to https://deploy-preview-618--kubernetes-sigs-krew.netlify.app/docs/developer-guide/custom-indexes/

Signed-off-by: Ahmet Alp Balkan <ahmetb@google.com>

ahmetb · 2020-07-01T17:55:16Z

/lgtm
/approve
/hold

ahmetb · 2020-07-01T17:56:01Z

/lgtm cancel

we need to add draft: true to frontmatters

chriskim06 · 2020-07-01T18:01:09Z

Is that setting external to this PR?

ahmetb · 2020-07-01T18:18:33Z

No, you'll need to update the .md files you added and add the property to their header section.

corneliusweig

Reads pretty good. Just small nits from my side.

site/content/docs/user-guide/using-custom-indexes.md

site/content/docs/developer-guide/custom-indexes.md

corneliusweig · 2020-07-01T22:26:43Z

site/content/docs/developer-guide/custom-indexes.md

+## Duplicate plugin names
+
+Your custom index can contain plugins that have the same name as the ones in
+`krew-index`.
+
+Users of your index will need to install your plugin using the
+explicit `<INDEX>/<PLUGIN>` syntax. See the [user guide][ug].
+
+[ug]: {{< relref "../user-guide/using-custom-indexes.md">}}


This has considerable overlap with using-custom-indexes, and duplicates some information. Do we really need it?

(also the heading does not fit to the second paragraph)

I'm ok with whatever. I think it might be good to have it repeated here as a consideration for people writing plugins for custom indexes and to let them know that people will need to install their plugin differently.

Co-authored-by: Cornelius Weig <22861411+corneliusweig@users.noreply.github.com>

ahmetb · 2020-07-02T18:42:57Z

site/content/docs/user-guide/using-custom-indexes.md

+However, some plugin authors may choose to host their own indexes that contain
+their curation of kubectl plugins. These are called "custom plugin indexes".
+
+## Adding a custom index


I think the title isn’t good.
It would be better to explain in this section “The default index” and

how it can be removed

or pointed to another repo

and how plugins without an explicit index name mean “default”

I feel like the adding/removing/listing indexes sections are important to showcase the new index command right? I agree though that a section explaining the default index would be good, I can move the advanced usage section I had and change it to reflect the points you listed.

Yes, I think this should work well. You could also explain how plugin names are resolved. Iow, that a default/ prefix is added implicitly, if no index name is given. Then you could also explain how plugin name clashes are handled and remove the Duplicate plugin names section in the other page.

ahmetb · 2020-07-06T02:10:06Z

site/content/docs/user-guide/using-custom-indexes.md

+foo      https://github.com/foo/custom-index.git{{</output>}}
+```
+
+## The default index


Can we perhaps use code block notation for all “default”s in this paragraph?

ahmetb · 2020-07-06T02:10:18Z

site/content/docs/user-guide/using-custom-indexes.md

+
+## The default index
+
+When a plugin doesn't have an explicit `INDEX_NAME` prefix it refers to a plugin


ahmetb · 2020-07-06T02:11:01Z

site/content/docs/user-guide/using-custom-indexes.md

+with the same name across different indexes.
+
+Krew ships with [`krew-index`][ki] as the default index, but this can be removed
+by passing `default` to the remove command. Once this is removed, you can add


...Removed using the “kubectl krew index remove default” command

ahmetb · 2020-07-06T02:11:52Z

site/content/docs/user-guide/using-custom-indexes.md

+foo      https://github.com/foo/custom-index.git{{</output>}}
+```
+
+## The default index


This section should ideally come after installing plugins from custom indexes (keep in mind most people might not care about the default index nuances)

ahmetb · 2020-07-08T19:28:02Z

/lgtm
/approve

k8s-ci-robot · 2020-07-08T19:28:11Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: ahmetb, chriskim06

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:

~~OWNERS~~ [ahmetb]

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

ahmetb · 2020-07-08T19:42:49Z

/hold cancel

chriskim06 added 5 commits June 29, 2020 09:01

Add initial docs for multi index feature

e9ace5b

Add developer guide doc on custom indexes

94e4758

Add formatting around krew-index

fffbd8c

Small tweaks

51c49e9

Add note about duplicate plugin names

24eae27

k8s-ci-robot added area/multi-index area/docs cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. labels Jul 1, 2020

k8s-ci-robot requested review from corneliusweig and soltysh July 1, 2020 02:41

k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Jul 1, 2020

chriskim06 changed the title ~~site: Custom index docs~~ site: custom index docs Jul 1, 2020

chriskim06 mentioned this pull request Jul 1, 2020

Implement custom plugin indexes #566

Closed

22 tasks

combine user guides, rephrase

2a8633c

Signed-off-by: Ahmet Alp Balkan <ahmetb@google.com>

ahmetb force-pushed the custom-index-docs branch from daab67f to 2a8633c Compare July 1, 2020 04:07

Fix small typo

d7f23b8

Extend the developer guide

684e67a

Signed-off-by: Ahmet Alp Balkan <ahmetb@google.com>

ahmetb force-pushed the custom-index-docs branch from 2d995f7 to 684e67a Compare July 1, 2020 04:19

Fix typo

6d8c13c

k8s-ci-robot assigned ahmetb Jul 1, 2020

k8s-ci-robot added lgtm "Looks good to me", indicates that a PR is ready to be merged. approved Indicates a PR has been approved by an approver from all required OWNERS files. labels Jul 1, 2020

ahmetb added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Jul 1, 2020

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jul 1, 2020

Set as draft

2fc3e5d

corneliusweig reviewed Jul 1, 2020

View reviewed changes

chriskim06 and others added 3 commits July 1, 2020 15:53

Update site/content/docs/user-guide/using-custom-indexes.md

e50dc2a

Co-authored-by: Cornelius Weig <22861411+corneliusweig@users.noreply.github.com>

Update custom plugin install section of guide

9fe055e

Add advanced usage section on removing default index

b19fac7

ahmetb reviewed Jul 2, 2020

View reviewed changes

Add section on the default index

d5bcefb

ahmetb reviewed Jul 6, 2020

View reviewed changes

Code review changes

e4a9adb

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jul 8, 2020

k8s-ci-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Jul 8, 2020

k8s-ci-robot merged commit e6d7fb6 into kubernetes-sigs:master Jul 8, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

site: custom index docs #618

site: custom index docs #618

chriskim06 commented Jul 1, 2020

ahmetb commented Jul 1, 2020

ahmetb commented Jul 1, 2020

ahmetb commented Jul 1, 2020

ahmetb commented Jul 1, 2020 •

edited

Loading

ahmetb commented Jul 1, 2020 •

edited

Loading

ahmetb commented Jul 1, 2020 •

edited

Loading

ahmetb commented Jul 1, 2020

chriskim06 commented Jul 1, 2020

ahmetb commented Jul 1, 2020

corneliusweig left a comment

corneliusweig Jul 1, 2020

chriskim06 Jul 1, 2020

ahmetb Jul 2, 2020

chriskim06 Jul 5, 2020

corneliusweig Jul 5, 2020

ahmetb Jul 6, 2020

ahmetb Jul 6, 2020

ahmetb Jul 6, 2020

ahmetb Jul 6, 2020

ahmetb commented Jul 8, 2020

k8s-ci-robot commented Jul 8, 2020

ahmetb commented Jul 8, 2020


		## The default index

		When a plugin doesn't have an explicit `INDEX_NAME` prefix it refers to a plugin

site: custom index docs #618

site: custom index docs #618

Conversation

chriskim06 commented Jul 1, 2020

ahmetb commented Jul 1, 2020

ahmetb commented Jul 1, 2020

ahmetb commented Jul 1, 2020

ahmetb commented Jul 1, 2020 • edited Loading

ahmetb commented Jul 1, 2020 • edited Loading

ahmetb commented Jul 1, 2020 • edited Loading

ahmetb commented Jul 1, 2020

chriskim06 commented Jul 1, 2020

ahmetb commented Jul 1, 2020

corneliusweig left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ahmetb commented Jul 8, 2020

k8s-ci-robot commented Jul 8, 2020

ahmetb commented Jul 8, 2020

ahmetb commented Jul 1, 2020 •

edited

Loading

ahmetb commented Jul 1, 2020 •

edited

Loading

ahmetb commented Jul 1, 2020 •

edited

Loading