Add support for using arbitrary Go template when generating markdown.

[j0n3lson]

What type of PR is this?

/kind feature

What this PR does / why we need it:

Adds the ability to render notes in markdown using a user-supplied template. A default template is supplied with this PR and is used by default when neither a template string or template file are specified.

This makes the tool less opinionated about the output format and gives the user a bit more control over the output. Wanting to customize the markdown output seems like a common use-case for this tool.

Additionally, users would not need to create wrappers around kubernetes/release just to customize their output (e.g. release-notes -> JSON -> Go template -> Desired output).

Which issue(s) this PR fixes:

Partially addresses urfave/cli#965

Special notes for your reviewer:

This idea was originally suggested by @saschagrunert.

Does this PR introduce a user-facing change?:

Adds a new option for the `--format=go-template:path/to/template.file` which allows a user to specify an arbitrary go-template file. The default format is `--format=go-template:default` and will render the release notes in markdown format. A `--format="markdown"` form is accepted but deprecated.

[k8s-ci-robot]

Thanks for your pull request. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please follow instructions at https://git.k8s.io/community/CLA.md#the-contributor-license-agreement to sign the CLA.

It may take a couple minutes for the CLA signature to be fully registered; after that, please reply here with a new comment and we'll verify. Thanks.

---

• If you've already signed a CLA, it's possible we don't have your GitHub username or you're using a different email address. Check your existing CLA data and verify that your email is set on your git commits.
• If you signed the CLA as a corporation, please sign in with your organization's credentials at https://identity.linuxfoundation.org/projects/cncf to be authorized.
• If you have done the above and are still having issues with the CLA being reported as unsigned, please log a ticket with the Linux Foundation Helpdesk: https://support.linuxfoundation.org/
• Should you encounter any issues with the Linux Foundation Helpdesk, send a message to the backup e-mail support address at: login-issues@jira.linuxfoundation.org

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. I understand the commands that are listed here.

[k8s-ci-robot]

Welcome @j0n3lson!

It looks like this is your first PR to kubernetes/release 🎉. 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/release 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]

Hi @j0n3lson. 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.

[j0n3lson]

/assign @saschagrunert

[j0n3lson]

/check-cla
/cc @lynncyrin

[k8s-ci-robot]

@j0n3lson: GitHub didn't allow me to request PR reviews from the following users: lynncyrin.

Note that only kubernetes members and repo collaborators can review this PR, and authors cannot review their own PRs.

In response to this:

/check-cla
/cc @lynncyrin

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.

[coilysiren]

In case it's helpful for +1 person reinforcing this point: me and @saschagrunert are looking to use the k8s release notes generator for urfave/cli! @j0n3lson has been doing a bunch of legwork to make that happen 🙏

[j0n3lson]

/check-cla

[saschagrunert]

Awesome, thanks. 🙏 This will help us to spread the tool around the world.

@j0n3lson can you please sign the CNCF CLA here.

/ok-to-test
/cc @justaugustus this is a great opportunity to bring the tool into use-cases outside of the k8s ecosystem. 😇

[saschagrunert]

Generally LGTM, I would recommend in going from markdown template to go template file to have it a bit more generic. Later on we could also add support for template strings, but this seems out of scope for now.

[saschagrunert]

/assign @justaugustus @hoegaarden @cpanato @hasheddan

asking kindly for review

[coilysiren]

I was reminded of this while writing up my most recent release 😄 urfave/cli#1077

[j0n3lson]

I'll try to get back to this FR this week. Thanks for being patient with me :)

[justaugustus]

Thanks @j0n3lson! Keep us posted. :)

[j0n3lson]

Quick update:

• I rebased and also added capability to render the downloads table (previous revision did not have it)

Working on:

• I'm trying to incorporate Sort release notes by Kind(s) instead of SIG(s) #923 which changed the structure of the Document type somewhat
• Also need to incorporate Add dedicated release notes section for 'action required' notes #1073 which updated the output.

Thinking about:

• Golden file testing. The document_test.go file doesn't have much testing. I thought it'd be great to do an end-to-end test for rendering using a test repo. We could compare the output against a golden file that we check in.

Hoping to finish up with this soon. Sorry for the long wait :)

[j0n3lson]

@saschagrunert @justaugustus

Could you have a look. I updated the reviewer notes with some specific questions I had. My test are failing because ValidateAndFinish() has a cyclomatic complexity score of 31. I could fix it but didn't want to expand the scope here.

[saschagrunert]

@saschagrunert @justaugustus

Could you have a look. I updated the reviewer notes with some specific questions I had. My test are failing because ValidateAndFinish() has a cyclomatic complexity score of 31. I could fix it but didn't want to expand the scope here.

We could either reduce the cyclomatic complexity (I can do that as a follow up as well) or you add something like this to .golangci.yml:

linters-settings:
  gocyclo:
    min-complexity: 35

[saschagrunert]

I was thinking about something like this too, we couple a var to two different functionalities (rendering and revision retrieval), which seems kinda bad. Let's stick to the TODO for now and follow-up later on this.

[j0n3lson]

I think I answered my own question about whether they're guaranteed to be set:

The default value for Options.DiscoverMode is RevisionDiscoveryModeNONE which means that either or both Options.StartRev and Options.EndRev can be empty.

With existing implementation will see an error if Options.ReleaseTars is given and the above is true (createDownloadsTable() will raise the error). This revision maintains that behavior though (FetchMetadata() will raise the error instead).

[j0n3lson]

@saschagrunert @justaugustus
Could you have a look. I updated the reviewer notes with some specific questions I had. My test are failing because ValidateAndFinish() has a cyclomatic complexity score of 31. I could fix it but didn't want to expand the scope here.

We could either reduce the cyclomatic complexity (I can do that as a follow up as well) or you add something like this to .golangci.yml:

linters-settings:
  gocyclo:
    min-complexity: 35

Bumped the min-complexity per your suggestion.

[saschagrunert]

/lgtm

[saschagrunert]

PTAL @justaugustus @hasheddan

[justaugustus]

Bumped the min-complexity per your suggestion.

@j0n3lson -- Can you remove that change and instead add:

//nolint:gocyclo

above the function?
Also, add a TODO to remind us to address the complexity.

Average cyclo is much lower and we should encourage less complex functions by having the linter fail.

[justaugustus]

In retrospect, this has been open for a while, so let's merge and iterate.
Thanks for your work on this, @j0n3lson!

/lgtm
/approve
/hold cancel

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: j0n3lson, justaugustus, saschagrunert

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 [justaugustus]

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

[coilysiren]

👀 🚀 !