# kepctl Command Design Document

`kepctl` can follow either the form `kepctl <subject> <verb>` as in, `kepctl release generate`, or it can follow the `kepctl <verb> <subject>` form. We should be consistent across all commands to make it easier for users to pick up the tool. Currently, we have mostly followed the `kepctl <verb>` structure, but as the tool has largely only delt with KEP documents, it has not included a subject. As we add `receipts`, this becomes more of an issue.

## User Types

* Kubernetes contributor who wants to create a new KEP, or a KEP author. The KEP author would like help with creation of the KEP structure from a template and help with validation of the content they author.
* SIG Chair / Tech Lead. This user would like to use kepctl to quickly find KEPs that they need to reviewm both merged and those that are open as pull requests. Additionally, they would like to easily find new KEPs for their SIG. To support the opt-in nature of the `receipts` process, they would also like to use the tool to help plan contents for a release and to create the required `receipt` documents.
* PRR Approver. This user would like the ability to find and review KEPs that have been assigned to them for PRR Review
* Release Enhancements Team Member. This user would like to use the tool to view and manage the contents of a given release, based on the `receipt` documents that have been submitted by SIG Chair/TLs.

## Commands (current)

### kepctl create

The `kepctl create` command is currently used to create a new KEP from the `NNNN-kep-template` folder. This generates a new folder and does minimal updating of the documents, based on the flags provided.

Examples:
  kepctl create sig-architecture/000-mykep

Flags:
      --authors stringArray        Authors
      --gh-token-path string       Path to a file with a GitHub API token
  -h, --help                       help for create
      --prr-approver stringArray   PRR Approver
      --repo-path string           Path to kubernetes/enhancements
      --reviewers stringArray      Reviewers
      --sigs stringArray           Participating SIGs
  -s, --state string               KEP State (default "provisional")
      --title string               KEP Title
      --type string                KEP Type (default "feature")
      

### kepctl query

The `kepctl query` command provivdes a limited set of query options to select against PRs and merged KEPS.

Examples:
  kepctl query --sig architecture --status provisional --include-prs

Flags:
      --gh-token-path string   Path to a file with a GitHub API token
  -h, --help                   help for query
      --include-prs            Include PRs in the results
      --output string          Output format. Can be [table json yaml] (default "table")
      --prr strings            Prod Readiness Approver
      --repo-path string       Path to kubernetes/enhancements
      --sig strings            SIG
      --stage strings          Stage
      --status strings         Status

### kepctl promote

The `kepctl promote` command currently updates an existing KEP to change milestone fields.

Usage:
  kepctl promote [KEP] [flags]

Examples:
  kepctl promote sig-architecture/000-mykep --stage beta --release v1.20

Flags:
      --gh-token-path string   Path to a file with a GitHub API token
  -h, --help                   help for promote
  -r, --release string         Target Release
      --repo-path string       Path to kubernetes/enhancements
  -s, --stage string           KEP Stage

## New Functionality for Receipts

### Create a Release

To support the receipts process, we need the ability to scaffold a release directory inside the enhancement repo. This would generate a directory structure:

$ kepctl create release v1.21
$ tree releases
releases
└── v1.21
    ├─  OWNERS
    ├── accepted
    ├── at-risk
    ├── exception
    ├── proposed
    └── removed

This could opti take an owners file as an argument

### Genrate a Release Manifest

With the above tree structure and a set of receipts generated, the enhancements team (or automation) would periodically generate a manifest to capture the state of the release. This oculd be done with a `create`, `generate`, `plan` or `report` verb. TBD

This would identify at risk and ready enhancements

### Create A Receipt

The existing `promote` command can be adapted to generate a receipt, in addition to generating automated updates to the KEP metadata to reflect the new release target. We could also add a separate command, `kepctl create receipt`, that could be used to allow people to do these as two steps. This would also allow for the two commands to be combined into a wrapper command that does both.

## Stephen's braindump at Jeremy

**n.b. I'm already hacking on a bunch of the foundation for this in https://github.com/kubernetes/enhancements/pull/2387.**

To tease you a little on what I'm thinking:

- `Document` is an interface with `Validate()`
- `Proposal` is a document
- `Receipt` is a document
- `PRRApproval` (or whatever we call it) is a document

These can be represented in `Document`s:

- `Person` (or whatever) is type `string` (approver, reviewer, PRR approver)
- `Group` is type `string` (`owning-sig`, `participating-groups`)

`Document` has `Parse()` as well

Parse the same way all the time; no need to check structure... it either is a `Document` type or not.
Then run the `Document`-specific `Validate()` implementation

Another: `kepify` becomes some subcommand of `kepctl`... maybe `kepctl dump --output json` or something
(Ignore me; now I'm just braindumping so I have it written down later)
Net new command: `kepctl plan`

Runs over a directory to determine:

- the next things we have to inform people about
- tell Enhancements + PRR what's missing

Imaginary usage: `kepctl plan --milestone v1.22`

Output:

[SIG Architecture] KEP 85 is targeted as `Beta` for v1.22, but does not have a PRR approval file logged.

Stop manual-ey things:

- Use https://github.com/yuin/goldmark to scrape markdown
- Don't write our own validation logic: https://github.com/go-playground/validator
- (maybe) Write an old KEP into the new directory format (field fixes and all that)

Also:
- Detach document errors from the actual data