Docs: Add TaskRun Status documentation section by HamzaMateen · Pull Request #7147 · tektoncd/pipeline

HamzaMateen · 2023-09-25T11:39:23Z

[Issue Link: #5720]

Description:

This PR addresses the issue by adding a new section to the docs/taskruns.md file to document the fields in TaskRun status. The structure of the new section closely follows that of the PipelineRun status documentation, with Required and Optional sections.

Changes Made:

Added a new section to docs/taskruns.md for TaskRun Status documentation.
Documented the key fields in TaskRun status, including their descriptions and significance.
Ensured consistency and clarity in the documentation, aligning it with the existing PipelineRun documentation style.

Files Changed

docs/taskruns.md

Testing Done:

Verified the changes by building the documentation locally and reviewing the updated taskruns.md file. Ensured that the new section follows the established documentation structure.

Screenshots:

N/A

Checklist:

I have followed the guidelines in contributing.md for documentation contributions.
I have linked this PR to the related issue (#<issue_number>).
The documentation changes are technically accurate and easy to understand.
I have tested the changes locally and ensured they display correctly in the documentation.
I have reviewed and proofread the documentation to eliminate errors or inconsistencies.
All commits are signed-off (verified using git commit -s).
The PR is ready for review and merge.

Fixes #5720

Release Notes

NONE

tekton-robot · 2023-09-25T11:39:32Z

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

Details

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.

HamzaMateen · 2023-09-25T11:40:45Z

/kind documentation

afrittoli · 2023-09-25T14:45:13Z

/ok-to-test

afrittoli · 2023-09-27T12:54:36Z

docs/taskruns.md

+    - `RefSource`: the source from where a remote `Task` definition was fetched.
+    - `FeatureFlags`: Identifies the feature flags used during the `TaskRun`.
+  - `Step` - Reports the results of running a `step` in a `Task`.
+  - `Retries` - Contains the history of `TaskRun`'s `status` in case of a retry in order to keep record of failures. 


I think this is retriesStatus

afrittoli · 2023-09-27T12:54:55Z

docs/taskruns.md

+- Optional:
+  - `taskResults`- Describes the results of this `task`.
+
+  - `Provenance` - Provenance contains metadata about resources used in the `TaskRun` such as the source from where a remote `task` definition was fetched. It carries minimum amount of metadata in `TaskRun` `status` so that `Tekton Chains` can utilize it for provenance, its two subfields are:


provenance (lower case)

The go types are upper case, but the yaml/json rendering is lower case. Same goes for refSource, featureFlags, sidecars, etc...

this comment made everything clear.
I couldn't think through this naming used, now I have some idea. thanks

afrittoli

Thanks for this!
It looks mostly good - I left a couple of comments.

afrittoli · 2023-09-27T12:55:52Z

docs/taskruns.md

+- Optional:
+  - `taskResults`- Describes the results of this `task`.
+
+  - `Provenance` - Provenance contains metadata about resources used in the `TaskRun` such as the source from where a remote `task` definition was fetched. It carries minimum amount of metadata in `TaskRun` `status` so that `Tekton Chains` can utilize it for provenance, its two subfields are:


The go types are upper case, but the yaml/json rendering is lower case. Same goes for refSource, featureFlags, sidecars, etc...

afrittoli · 2023-09-27T12:57:28Z

docs/taskruns.md

+The `TaskRun`'s  `status` field can contain the following fields:
+
+- Required:
+  - `status` - The most relevant information about the TaskRun's state. This field includes:


NIT: I think the "most relevant" comment is not necessary, but it's also ok to keep

afrittoli · 2023-09-27T12:59:37Z

docs/taskruns.md

+### The `status` field
+The `TaskRun`'s  `status` field can contain the following fields:
+
+- Required:


podName is missing in the "Required" section

When I generated the API spec using Swagger, I found out that podName was required but default so I skipped it. I will add it in my next edition. Thanks

afrittoli · 2023-09-27T13:07:20Z

docs/taskruns.md

+  - [`taskSpec`](tasks.md#configuring-a-task) - `TaskSpec` defines the desired state of the `Task` executed via the `TaskRun`.
+
+- Optional:
+  - `taskResults`- Describes the results of this `task`.


This should be results.
NIT: I would say "contains" instead of "describes" - there is no description really. it's their names and values

afrittoli · 2023-09-27T13:20:07Z

docs/taskruns.md

+    - `FeatureFlags`: Identifies the feature flags used during the `TaskRun`.
+  - `Step` - Reports the results of running a `step` in a `Task`.
+  - `Retries` - Contains the history of `TaskRun`'s `status` in case of a retry in order to keep record of failures. 
+  - [`Sidecar`](tasks.md#using-a-sidecar-in-a-task) - Reports the results of running a `sidecar` in a `Task`.


sidecars (plural). This is the comment in the code:

The list has one entry per sidecar in the manifest. Each entry represents the imageid of the corresponding sidecar.

can you please elaborate a bit more on this? should I write this line instead of the one already there?

I just wanted to point out that it can be multiple sidecars, so maybe you could reuse part of that wording

afrittoli · 2023-09-27T13:21:23Z

docs/taskruns.md

+  - `completionTime` - The time at which the `TaskRun` finished executing, conforms to [RFC3339](https://tools.ietf.org/html/rfc3339) format.
+  - [`taskSpec`](tasks.md#configuring-a-task) - `TaskSpec` defines the desired state of the `Task` executed via the `TaskRun`.
+
+- Optional:


spanContext is missing in this list

afrittoli · 2023-09-27T13:23:27Z

docs/taskruns.md

 specifying a `ServiceAccount` object name in the `serviceAccountName` field in your `TaskRun`
 definition. If you do not explicitly specify this, the `TaskRun` executes with the credentials
-specified in the `configmap-defaults` `ConfigMap`. If this default is not specified, `TaskRuns`
+specified in the `configmap-defaults` `ConfigMap`. If this defaulPipelineRunt is not specified, `TaskRuns`


I guess this was changed by mistake?

HamzaMateen · 2023-09-27T14:47:23Z

I will edit this PR and send my changes as soon as I am done with them. Thanks for your thorough review, appreciated!

In response to feedback received on PR tektoncd#7147, this commit addresses the following changes: - Updated the TaskRun status documentation based on reviewer comments. - Clarified descriptions for certain fields to improve understanding. - Ensured consistency in formatting and terminology throughout the TaskRun status section. - Fixed some typos in corresponding PipelineRuns section for consistency. Files Changed: taskruns.md pipelineruns.md These changes enhance the clarity and completeness of the TaskRun status documentation, providing users with accurate and detailed information. Fixes tektoncd#5720

afrittoli

Thank you for the updates, it lgtm!

tekton-robot · 2023-10-02T19:27:51Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: afrittoli

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

The pull request process is described here

Details

Needs approval from an approver in each of these files:

~~OWNERS~~ [afrittoli]

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

Yongxuanzhang · 2023-10-02T19:59:48Z

docs/taskruns.md

+  - [`taskSpec`](tasks.md#configuring-a-task) - `TaskSpec` defines the desired state of the `Task` executed via the `TaskRun`.
+
+- Optional:
+  - `taskResults`- Contains the results of this `task`.


I think this should be just results?

pipeline/pkg/apis/pipeline/v1/taskrun_types.go

Line 228 in 0a4357a

Results []TaskRunResult `json:"results,omitempty"`

Ohh, I will update it again. Thanks!

Thanks! lmk when it's updated and we can merge this

Update done! (the commit message isn't very accurate) but I didn't see the point of changing it for just a typo.

Update done! (the commit message isn't very accurate) but I didn't see the point of changing it for just a typo.

Thanks! Would you mind squashing the 3 commits? This should be the one last thing to merge it.

In response to feedback received on PR tektoncd#7147, this commit addresses the following changes: - Updated the TaskRun status documentation based on reviewer comments. - Clarified descriptions for certain fields to improve understanding. - Ensured consistency in formatting and terminology throughout the TaskRun status section. - Fixed some typos in corresponding PipelineRuns section for consistency. Files Changed: taskruns.md pipelineruns.md Fixes: tektoncd#5720

In response to issue tektoncd#5720, this commit adds a new section to the docs/taskruns.md file to document the fields in TaskRun status in detail. The new section follows a similar structure to the PipelineRun status documentation and is divided into Required and Optional sections. - The Required section provides a comprehensive list of essential fields in TaskRun status, offering users insights into the key aspects of a TaskRun's state. - The Optional section complements the Required section by listing additional fields that provide more context and flexibility for TaskRuns. This addition enhances the documentation and helps users understand the details of TaskRun status, aligning it with the structure and clarity of PipelineRun documentation. Files changed: 1. taskruns.md 2. pipelineruns.md Fixes: tektoncd#5720

Yongxuanzhang · 2023-10-03T19:51:11Z

/lgtm

tekton-robot requested review from lbernick and pritidesai September 25, 2023 11:39

tekton-robot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Sep 25, 2023

afrittoli reviewed Sep 27, 2023

View reviewed changes

afrittoli changed the title ~~WIP docs: Add TaskRun Status documentation section~~ Docs: Add TaskRun Status documentation section Oct 2, 2023

tekton-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Oct 2, 2023

afrittoli approved these changes Oct 2, 2023

View reviewed changes

tekton-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Oct 2, 2023

Yongxuanzhang reviewed Oct 2, 2023

View reviewed changes

HamzaMateen force-pushed the docs/taskruns-status-section branch from 931abae to 13996e7 Compare October 3, 2023 19:40

tekton-robot assigned Yongxuanzhang Oct 3, 2023

tekton-robot added the lgtm Indicates that a PR is ready to be merged. label Oct 3, 2023

tekton-robot merged commit fd4cb46 into tektoncd:main Oct 3, 2023

afrittoli added the hacktoberfest-accepted Categorizes PRs as one accepted Hacktoberfest 2021 label Oct 4, 2023

Conversation

HamzaMateen commented Sep 25, 2023 • edited by afrittoli Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Release Notes

Uh oh!

tekton-robot commented Sep 25, 2023

Uh oh!

HamzaMateen commented Sep 25, 2023

Uh oh!

afrittoli commented Sep 25, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

afrittoli left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

HamzaMateen commented Sep 27, 2023

Uh oh!

afrittoli left a comment

Choose a reason for hiding this comment

Uh oh!

tekton-robot commented Oct 2, 2023

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Yongxuanzhang Oct 3, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Yongxuanzhang commented Oct 3, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

HamzaMateen commented Sep 25, 2023 •

edited by afrittoli

Loading

Yongxuanzhang Oct 3, 2023 •

edited

Loading