TEP-0114: Updating runs.md Documentation

[vsinghai]

Changes

Prior to this commit, the previous iteration
of the runs.md doc had some fields missing from
the API and the level of detail and clarification.

In this commit, we aim to clarify the API and update
it to make sure it is clear, upto date, and has useful
examples.

Fixes issue #5158

/cc @jerop
/kind documentation

Submitter Checklist

As the author of this PR, please check off the items in this checklist:

• Has Docs included if any changes are user facing
• Has Tests included if any functionality added or changed
• Follows the commit message standard
• Meets the Tekton contributor standards (including
  functionality, content, code)
• Has a kind label. You can add one by adding a comment on this PR that contains /kind <type>. Valid types are bug, cleanup, design, documentation, feature, flake, misc, question, tep
• Release notes block below has been updated with any user facing changes (API changes, bug fixes, changes requiring upgrade notices or deprecation warnings)
• Release notes contains the string "action required" if the change requires additional action from users switching to the new release

Release Notes

NONE

[tekton-robot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign jerop after the PR has been reviewed.
You can assign the PR to them by writing /assign @jerop in a comment when ready.

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

Needs approval from an approver in each of these files:

• OWNERS

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

[tekton-robot]

Hi @vsinghai. Thanks for your PR.

I'm waiting for a tektoncd 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.

[vsinghai]

/hold

[lbernick]

/ok-to-test

[lbernick]

Thanks Varun! This is great to have, but I don't think we should close #5158 when this is merged (I think "fixes #" in your PR description will result in that happening).

I think there's a lot more documentation for runs that would be nice to have, such as realistic examples of ci/cd pipelines containing runs and links to useful existing custom tasks. @jerop maybe worth updating the issue with some ideas, and possibly @geriom you might have some thoughts here as well? Might be out of scope for this PR-- I can see in the PR description you're planning to add some examples?

[lbernick]

I think a few of these links are broken.

[lbernick]

Suggested change

	- [`retries`](#) - Specifies propagating retries count to custom tasks.
	- [`retries`](#) - Specifies the number of times the `Run` should retry, if the custom task controller supports retries.

[vsinghai]

Thanks for the feedback @lbernick! There is still currently a lot that I have left to do for this PR, including (but not limited to) having examples for the custom fields and providing more clarity to the API. The reason I created a PR was so that @jerop can just look over the incremental progress that I am making to make sure we are on the same path regarding how to fix #5158, and is also why I have the PR on hold. I apologize for the confusion.

[lbernick]

no problem, thanks for the explanation! I think creating a draft PR can be useful in situations like these- it lets reviewers know that it's still a WIP (hold does this to some extent but I wasn't sure why the PR was on hold)

[tekton-robot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale with a justification.
Stale issues rot after an additional 30d of inactivity and eventually close.
If this issue is safe to close now please do so with /close with a justification.
If this issue should be exempted, mark the issue as frozen with /lifecycle frozen with a justification.

/lifecycle stale

Send feedback to tektoncd/plumbing.