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

Self describing Pipeline and Task Definitions #993

Closed
objectiveous opened this issue Jun 19, 2019 · 9 comments · Fixed by #2089
Closed

Self describing Pipeline and Task Definitions #993

objectiveous opened this issue Jun 19, 2019 · 9 comments · Fixed by #2089
Assignees
@piyush-garg
Labels
design This task is about creating and discussing a design help wanted Denotes an issue that needs help from a contributor. Must meet "help wanted" guidelines. kind/design Categorizes issue or PR as related to design.
Milestone
Formerly Pipeline...

Comments

@objectiveous
Copy link

Overview

A number of teams are building catalogs of Pipelines and Tasks for the purpose of reuse. Many of these catalog have usage documentation that exists separate from the the actual Pipeline/Task definition.

Proposal

Make usage documentation a fist class concern of Tasks. Perhaps by enhancing task definitions or maybe by introducing a new Kind (TaskInfo?).

Example Scenario

Consider a team that uses a tekton catalog to populate the Design Pallet of CI/CD GUI tool. Having populated a Design Pallet, users may want to Inspect a task to lean more about it's Inputs, Outputs, version number, intended use, etc.
@bobcatfish
Copy link
Collaborator

This would be great to see! In the catalog repo we're ending up with a lot of docs in the associated readmes (e.g. https://github.com/tektoncd/catalog/tree/master/golang#golangci-lint) but I agree it would be way better to see this in the Tasks and Pipelines themselves!

Also maybe related: tektoncd/catalog#7

@bobcatfish bobcatfish added design This task is about creating and discussing a design help wanted Denotes an issue that needs help from a contributor. Must meet "help wanted" guidelines. kind/design Categorizes issue or PR as related to design. maybe-next-milestone For consideration when planning the next milestone labels Jun 19, 2019
@bobcatfish
Copy link
Collaborator

I want to add here that PipelineResources should have descriptions too!

@bobcatfish bobcatfish added this to the Pipelines 0.8 🐱 milestone Sep 6, 2019
@bobcatfish bobcatfish removed the maybe-next-milestone For consideration when planning the next milestone label Sep 9, 2019
@bobcatfish bobcatfish modified the milestones: Pipelines 0.9 🐱, Pipelines 1.1 / Post-beta 🐱 Oct 30, 2019
@vdemeester vdemeester mentioned this issue Jan 20, 2020
Closed
@vdemeester vdemeester modified the milestones: Pipelines 1.1 / Post-beta 🐱, Pipelines 1.0/beta 🐱 (0.11) Jan 20, 2020
@vdemeester
Copy link
Member

vdemeester commented Jan 20, 2020 •
edited
Loading

Moved it to beta as I feel it can be a small change (doesn't even need to be an API change), and it would be a really really nice to have for beta.

We could use standard annotation (like tekton.dev/description or something) so that the cli (see tektoncd/cli#625 or the dashboard or any consumer could display those)

@piyush-garg
Copy link
Contributor

/assign

@piyush-garg
Copy link
Contributor

@bobcatfish @vdemeester

What should we add regarding this in pipelines? Should we add an optional Description field in TaskSpec? Or any other approach?

@siamaksade
Copy link

siamaksade commented Feb 13, 2020 •
edited
Loading

+1 on adding Description to TaskSpec and PipelineSpec

piyush-garg added a commit to piyush-garg/pipeline that referenced this issue Feb 24, 2020
@piyush-garg
Add description field to spec
27528c0 
This will add a description field to the spec of
pipeline, task pipeline resource ond condition
so that it can be used to provide the description
of these and can also be used by UI to show description

Fix tektoncd#993
@piyush-garg piyush-garg mentioned this issue Feb 24, 2020
Merged
3 tasks
piyush-garg added a commit to piyush-garg/pipeline that referenced this issue Mar 3, 2020
@piyush-garg
Add information about description annotation
d4977c3 
This will add information about tekton.dev/description
annotation which can be added to pipeline, task, resource
clustertask and condition so that it can be used to
provide the description of these and can also be used
by UI to show description.

Add docs and also add default empty value annotation
behaviour.

Fix tektoncd#993
piyush-garg added a commit to piyush-garg/pipeline that referenced this issue Mar 3, 2020
@piyush-garg
Add information about description annotation
0f6eb6c 
This will add information about tekton.dev/description
annotation which can be added to pipeline, task, resource
clustertask and condition so that it can be used to
provide the description of these and can also be used
by UI to show description.

Add docs and also add default empty value annotation
behaviour.

Fix tektoncd#993
@bobcatfish
Copy link
Collaborator

bobcatfish commented Mar 3, 2020 •
edited
Loading

hey there! i think this is being discussed in slack also but I noticed that #2089 is doing this via annotation, i dont quit understand why we chose annotation vs. a field in the spec?

i would prefer adding a field to the spec if possible, a couple reasons: [edit fixed very confusing typo thanks @sbwsg !!!]

  • other fields like this would be done via spec (e.g. description of a param)
  • adding it to the spec makes it part of the API - imo using the annotation is a kubernetes specific thing, i think we still want to at least entertain the possibility of supporting a non k8s use case

@vdemeester
Copy link
Member

Fair enouhg, let's go with the field. I don't have such a strong opinion 😅
@piyush-garg will update his PR 😉

@piyush-garg
Copy link
Contributor

Thanks @vdemeester @bobcatfish for reviews. I will update the PR today

piyush-garg added a commit to piyush-garg/pipeline that referenced this issue Mar 4, 2020
@piyush-garg
Add description field to Spec
fa0387a 
This will add description field to spec
of pipeline, task, clustertask, resource and condition

This can be used to provide description and
can further used in CLI and UI.

Add docs and tests

Fix tektoncd#993
piyush-garg added a commit to piyush-garg/pipeline that referenced this issue Mar 9, 2020
@piyush-garg
Add description field to Spec
c66810e 
This will add description field to spec
of pipeline, task, clustertask, resource and condition

This can be used to provide description and
can further used in CLI and UI.

Add docs and tests

Fix tektoncd#993
piyush-garg added a commit to piyush-garg/pipeline that referenced this issue Mar 9, 2020
@piyush-garg
Add description field to Spec
3d9646a 
This will add description field to spec
of pipeline, task, clustertask, resource and condition

This can be used to provide description and
can further used in CLI and UI.

Add docs and tests

Fix tektoncd#993
piyush-garg added a commit to piyush-garg/pipeline that referenced this issue Mar 9, 2020
@piyush-garg
Add description field to Spec
79484d5 
This will add description field to spec
of pipeline, task, clustertask, resource and condition

This can be used to provide description and
can further used in CLI and UI.

Add docs and tests

Fix tektoncd#993
tekton-robot pushed a commit that referenced this issue Mar 9, 2020
@piyush-garg @tekton-robot
Add description field to Spec
a109d07 
This will add description field to spec
of pipeline, task, clustertask, resource and condition

This can be used to provide description and
can further used in CLI and UI.

Add docs and tests

Fix #993
@AlanGreene AlanGreene mentioned this issue Mar 9, 2020
Closed
5 tasks
tekton-robot pushed a commit that referenced this issue Mar 10, 2020
@piyush-garg @tekton-robot
Add description field to Spec
5d4117e 
This will add description field to spec
of pipeline, task, clustertask, resource and condition

This can be used to provide description and
can further used in CLI and UI.

Add docs and tests

Fix #993

(cherry picked from commit a109d07)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@piyush-garg piyush-garg

Labels
design This task is about creating and discussing a design help wanted Denotes an issue that needs help from a contributor. Must meet "help wanted" guidelines. kind/design Categorizes issue or PR as related to design.
Projects
None yet
Milestone
Formerly Pipelines 1.0/beta 🐱
Development

Successfully merging a pull request may close this issue.

Add description field to Spec piyush-garg/pipeline
5 participants
@vdemeester @objectiveous @bobcatfish @siamaksade @piyush-garg