Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update PipelineRun API documentation #4657

Closed
lbernick opened this issue Mar 8, 2022 · 6 comments · Fixed by #4853
Closed

Update PipelineRun API documentation #4657

lbernick opened this issue Mar 8, 2022 · 6 comments · Fixed by #4853
Assignees
@ssunitaa
Labels
good first issue Denotes an issue ready for a new contributor, according to the "help wanted" guidelines. help wanted Denotes an issue that needs help from a contributor. Must meet "help wanted" guidelines. kind/documentation Categorizes issue or PR as related to documentation.

Comments

@lbernick
Copy link
Member

lbernick commented Mar 8, 2022

Similar to #4601. We should update the PipelineRun API docs to reflect all existing fields.

/kind documentation
/help-wanted
/good-first-issue
@tekton-robot
Copy link
Collaborator

@lbernick:
This request has been marked as suitable for new contributors.

Please ensure the request meets the requirements listed here.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-good-first-issue command.

In response to this:

Similar to #4601. We should update the PipelineRun API docs to reflect all existing fields.

/kind documentation
/help-wanted
/good-first-issue

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.

@tekton-robot tekton-robot added kind/documentation Categorizes issue or PR as related to documentation. good first issue Denotes an issue ready for a new contributor, according to the "help wanted" guidelines. help wanted Denotes an issue that needs help from a contributor. Must meet "help wanted" guidelines. labels Mar 8, 2022
@lbernick lbernick moved this to Todo in Pipelines V1 Mar 8, 2022
@ssunitaa
Copy link

Hi there,

I am a technical writer with 12 years experience. I am currently learning to do API documentation. Please let me know how can I help in this documentation.

Thanks!

@jerop
Copy link
Member

jerop commented Mar 15, 2022

@ssunitaa welcome to the Tekton community and thank you for volunteering to help! 😀

We need help updating the PipelineRun API definition in the docs to match the definition in the code. I updated the Pipeline API definition in #4601 - hoping that this can be a good example, but feel free to ask any questions.

We also have a bunch of prioritized documentation work - https://github.com/orgs/tektoncd/projects/10/views/6 - that'd help us work towards V1 release. We'd appreciate any help on these issues if you have some time.

You may also be interested in joining the Tekton Documentation Working Group - cc @geriom.

@ssunitaa
Copy link

ssunitaa commented Mar 15, 2022 via email

@jerop
Copy link
Member

jerop commented Mar 15, 2022

@ssunitaa - thank YOU!

  1. we can communicate here for visibility with the other contributors and owners who can help too, feel free to send me a message on slack too if you prefer
  2. it's mostly adding the supported fields at the top level and adding links to the relevant docs for the fields - we also have autogenerated API spec

abayer added a commit to abayer/tektoncd-pipeline that referenced this issue Mar 23, 2022
@abayer
[TEP-0100] Fields/flags/docs for embedded TaskRun and Run statuses in…
df1e8aa 
… PipelineRuns

See https://github.com/tektoncd/community/blob/main/teps/0100-embedded-taskruns-and-runs-status-in-pipelineruns.md

This adds new choices for how `TaskRun` and `Run` statuses are stored/referenced in `PipelineRun`
statuses, depending on how the new feature flag, `embedded-status` is set:
* `full` - the current default, with the `TaskRun` and `Run` statuses embedded in full.
* `minimal` - instead of storing the full embedded statuses, information is stored about the task's
   version, kind, `PipelineTask` name, and the underlying name of the `TaskRun` or `Run`. This can be
   used to look up the `TaskRun` or `Run` itself and get the full status from there. Information
   which is specific to the `PipelineRun`, namely condition checks status and when expressions which
   may have blocked creation of an actual `TaskRun` or `Run` are stored as well.
* `both` - both the full embedded `TaskRun` and `Run` statuses and the minimal references are stored.

The condition check information will be removed from the minimal references once the now-deprecated
condition check functionality is removed from Tekton Pipeline.

As described in https://github.com/tektoncd/community/blob/main/teps/0100-embedded-taskruns-and-runs-status-in-pipelineruns.md#beta-api,
9 months after this change has been released in `v1beta1`, the default value for the
`embedded-status` feature flag will be changed from `full` to `minimal`, and a few months after
that, the `embedded-status` feature flag will be removed entirely and only the `minimal` behavior
will remain.

Note that this also may address tektoncd#4657, since I had to add documentation for `PipelineRunStatus`,
and while I was there, I added some missing top-level fields to the `PipelineRun` definition.

The actual implementation will follow this PR.

Signed-off-by: Andrew Bayer <[email protected]>
@abayer abayer mentioned this issue Mar 23, 2022
Merged
5 tasks
abayer added a commit to abayer/tektoncd-pipeline that referenced this issue Mar 23, 2022
@abayer
[TEP-0100] Fields/flags/docs for embedded TaskRun and Run statuses in…
e2b4d76 
… PipelineRuns

See https://github.com/tektoncd/community/blob/main/teps/0100-embedded-taskruns-and-runs-status-in-pipelineruns.md

This adds new choices for how `TaskRun` and `Run` statuses are stored/referenced in `PipelineRun`
statuses, depending on how the new feature flag, `embedded-status` is set:
* `full` - the current default, with the `TaskRun` and `Run` statuses embedded in full.
* `minimal` - instead of storing the full embedded statuses, information is stored about the task's
   version, kind, `PipelineTask` name, and the underlying name of the `TaskRun` or `Run`. This can be
   used to look up the `TaskRun` or `Run` itself and get the full status from there. Information
   which is specific to the `PipelineRun`, namely condition checks status and when expressions which
   may have blocked creation of an actual `TaskRun` or `Run` are stored as well.
* `both` - both the full embedded `TaskRun` and `Run` statuses and the minimal references are stored.

The condition check information will be removed from the minimal references once the now-deprecated
condition check functionality is removed from Tekton Pipeline.

As described in https://github.com/tektoncd/community/blob/main/teps/0100-embedded-taskruns-and-runs-status-in-pipelineruns.md#beta-api,
9 months after this change has been released in `v1beta1`, the default value for the
`embedded-status` feature flag will be changed from `full` to `minimal`, and a few months after
that, the `embedded-status` feature flag will be removed entirely and only the `minimal` behavior
will remain.

Note that this also may address tektoncd#4657, since I had to add documentation for `PipelineRunStatus`,
and while I was there, I added some missing top-level fields to the `PipelineRun` definition.

The actual implementation will follow this PR.

Signed-off-by: Andrew Bayer <[email protected]>
abayer added a commit to abayer/tektoncd-pipeline that referenced this issue Mar 24, 2022
@abayer
[TEP-0100] Fields/flags/docs for embedded TaskRun and Run statuses in…
8573baa 
… PipelineRuns

See https://github.com/tektoncd/community/blob/main/teps/0100-embedded-taskruns-and-runs-status-in-pipelineruns.md

This adds new choices for how `TaskRun` and `Run` statuses are stored/referenced in `PipelineRun`
statuses, depending on how the new feature flag, `embedded-status` is set:
* `full` - the current default, with the `TaskRun` and `Run` statuses embedded in full.
* `minimal` - instead of storing the full embedded statuses, information is stored about the task's
   version, kind, `PipelineTask` name, and the underlying name of the `TaskRun` or `Run`. This can be
   used to look up the `TaskRun` or `Run` itself and get the full status from there. Information
   which is specific to the `PipelineRun`, namely condition checks status and when expressions which
   may have blocked creation of an actual `TaskRun` or `Run` are stored as well.
* `both` - both the full embedded `TaskRun` and `Run` statuses and the minimal references are stored.

The condition check information will be removed from the minimal references once the now-deprecated
condition check functionality is removed from Tekton Pipeline.

As described in https://github.com/tektoncd/community/blob/main/teps/0100-embedded-taskruns-and-runs-status-in-pipelineruns.md#beta-api,
9 months after this change has been released in `v1beta1`, the default value for the
`embedded-status` feature flag will be changed from `full` to `minimal`, and a few months after
that, the `embedded-status` feature flag will be removed entirely and only the `minimal` behavior
will remain.

Note that this also may address tektoncd#4657, since I had to add documentation for `PipelineRunStatus`,
and while I was there, I added some missing top-level fields to the `PipelineRun` definition.

The actual implementation will follow this PR.

Signed-off-by: Andrew Bayer <[email protected]>
abayer added a commit to abayer/tektoncd-pipeline that referenced this issue Mar 24, 2022
@abayer
[TEP-0100] Fields/flags/docs for embedded TaskRun and Run statuses in…
08ac11e 
… PipelineRuns

See https://github.com/tektoncd/community/blob/main/teps/0100-embedded-taskruns-and-runs-status-in-pipelineruns.md

This adds new choices for how `TaskRun` and `Run` statuses are stored/referenced in `PipelineRun`
statuses, depending on how the new feature flag, `embedded-status` is set:
* `full` - the current default, with the `TaskRun` and `Run` statuses embedded in full.
* `minimal` - instead of storing the full embedded statuses, information is stored about the task's
   version, kind, `PipelineTask` name, and the underlying name of the `TaskRun` or `Run`. This can be
   used to look up the `TaskRun` or `Run` itself and get the full status from there. Information
   which is specific to the `PipelineRun`, namely condition checks status and when expressions which
   may have blocked creation of an actual `TaskRun` or `Run` are stored as well.
* `both` - both the full embedded `TaskRun` and `Run` statuses and the minimal references are stored.

The condition check information will be removed from the minimal references once the now-deprecated
condition check functionality is removed from Tekton Pipeline.

As described in https://github.com/tektoncd/community/blob/main/teps/0100-embedded-taskruns-and-runs-status-in-pipelineruns.md#beta-api,
9 months after this change has been released in `v1beta1`, the default value for the
`embedded-status` feature flag will be changed from `full` to `minimal`, and a few months after
that, the `embedded-status` feature flag will be removed entirely and only the `minimal` behavior
will remain.

Note that this also may address tektoncd#4657, since I had to add documentation for `PipelineRunStatus`,
and while I was there, I added some missing top-level fields to the `PipelineRun` definition.

The actual implementation will follow this PR.

Signed-off-by: Andrew Bayer <[email protected]>
abayer added a commit to abayer/tektoncd-pipeline that referenced this issue Mar 24, 2022
@abayer
[TEP-0100] Fields/flags/docs for embedded TaskRun and Run statuses in…
e02670d 
… PipelineRuns

See https://github.com/tektoncd/community/blob/main/teps/0100-embedded-taskruns-and-runs-status-in-pipelineruns.md

This adds new choices for how `TaskRun` and `Run` statuses are stored/referenced in `PipelineRun`
statuses, depending on how the new feature flag, `embedded-status` is set:
* `full` - the current default, with the `TaskRun` and `Run` statuses embedded in full.
* `minimal` - instead of storing the full embedded statuses, information is stored about the task's
   version, kind, `PipelineTask` name, and the underlying name of the `TaskRun` or `Run`. This can be
   used to look up the `TaskRun` or `Run` itself and get the full status from there. Information
   which is specific to the `PipelineRun`, namely condition checks status and when expressions which
   may have blocked creation of an actual `TaskRun` or `Run` are stored as well.
* `both` - both the full embedded `TaskRun` and `Run` statuses and the minimal references are stored.

The condition check information will be removed from the minimal references once the now-deprecated
condition check functionality is removed from Tekton Pipeline.

As described in https://github.com/tektoncd/community/blob/main/teps/0100-embedded-taskruns-and-runs-status-in-pipelineruns.md#beta-api,
9 months after this change has been released in `v1beta1`, the default value for the
`embedded-status` feature flag will be changed from `full` to `minimal`, and a few months after
that, the `embedded-status` feature flag will be removed entirely and only the `minimal` behavior
will remain.

Note that this also may address tektoncd#4657, since I had to add documentation for `PipelineRunStatus`,
and while I was there, I added some missing top-level fields to the `PipelineRun` definition.

The actual implementation will follow this PR.

Signed-off-by: Andrew Bayer <[email protected]>
tekton-robot pushed a commit that referenced this issue Mar 25, 2022
@abayer @tekton-robot
[TEP-0100] Fields/flags/docs for embedded TaskRun and Run statuses in…
bfff75b 
… PipelineRuns

See https://github.com/tektoncd/community/blob/main/teps/0100-embedded-taskruns-and-runs-status-in-pipelineruns.md

This adds new choices for how `TaskRun` and `Run` statuses are stored/referenced in `PipelineRun`
statuses, depending on how the new feature flag, `embedded-status` is set:
* `full` - the current default, with the `TaskRun` and `Run` statuses embedded in full.
* `minimal` - instead of storing the full embedded statuses, information is stored about the task's
   version, kind, `PipelineTask` name, and the underlying name of the `TaskRun` or `Run`. This can be
   used to look up the `TaskRun` or `Run` itself and get the full status from there. Information
   which is specific to the `PipelineRun`, namely condition checks status and when expressions which
   may have blocked creation of an actual `TaskRun` or `Run` are stored as well.
* `both` - both the full embedded `TaskRun` and `Run` statuses and the minimal references are stored.

The condition check information will be removed from the minimal references once the now-deprecated
condition check functionality is removed from Tekton Pipeline.

As described in https://github.com/tektoncd/community/blob/main/teps/0100-embedded-taskruns-and-runs-status-in-pipelineruns.md#beta-api,
9 months after this change has been released in `v1beta1`, the default value for the
`embedded-status` feature flag will be changed from `full` to `minimal`, and a few months after
that, the `embedded-status` feature flag will be removed entirely and only the `minimal` behavior
will remain.

Note that this also may address #4657, since I had to add documentation for `PipelineRunStatus`,
and while I was there, I added some missing top-level fields to the `PipelineRun` definition.

The actual implementation will follow this PR.

Signed-off-by: Andrew Bayer <[email protected]>
@ssunitaa
Copy link

ssunitaa commented Apr 1, 2022

/assign ssunitaa

vsinghai pushed a commit to vsinghai/pipeline that referenced this issue May 10, 2022
Add missing field to pipelineruns doc
0fce65b 
The status field was not mentioned in the Configuring a PipelineRun section.
This commit adds the missing status field and links to the cancelling a
pipelinerun subsection.

Fixes tektoncd#4657
@vsinghai vsinghai mentioned this issue May 10, 2022
Merged
5 tasks
Repository owner moved this from Todo to Done in Pipelines V1 May 11, 2022
tekton-robot pushed a commit that referenced this issue May 11, 2022
@tekton-robot
Add missing field to pipelineruns doc
33e3a55 
The status field was not mentioned in the Configuring a PipelineRun section.
This commit adds the missing status field and links to the cancelling a
pipelinerun subsection.

Fixes #4657
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@ssunitaa ssunitaa

Labels
good first issue Denotes an issue ready for a new contributor, according to the "help wanted" guidelines. help wanted Denotes an issue that needs help from a contributor. Must meet "help wanted" guidelines. kind/documentation Categorizes issue or PR as related to documentation.
Projects
Pipelines V1
Status: Done
Milestone
No milestone
Development

Successfully merging a pull request may close this issue.

Add missing field to pipelineruns doc vsinghai/pipeline
4 participants
@jerop @lbernick @tekton-robot @ssunitaa