Rename the 'finally' key to 'final' in the specification and while still allowing 'finally' to help the users who already have this key as part of their specification #4086
Comments
|
@nikhil-thomas PTAL at this ^ issue, comment on the issue, and kindly tag others. This will help drive some discussion. Thank you! |
|
hey @Srivaralakshmi - thanks for opening this issue. The motivation for the term "finally" was inspiration from languages like python which have "try/catch/finally" syntax. This design doc has some more context around the design. What our current syntax is trying to say is:
It sounds like one thing we could certainly do in the short term is to consistently use "finally tasks" in our docs instead of sometimes saying "final tasks". Beyond that, could you explain a bit more about the problems this confusion is causing? If this is a matter of having to initially understand what 'finally' means, but users are able to use the feature after that, i'm not sure that's enough motivation to change the name of the field. But if we are seeing something like: folks are accidentally using |
bobcatfish
added
area/api
This commit changes all references to "final tasks" to "finally tasks". We were using a mix of "final tasks" and "finally tasks" to refer to these tasks, so this commit is making us consistently use one version. However "finally tasks" is less grammatically correct that "final tasks" because finally is an adverb - "finally tasks" only makes sense if "finally tasks" is considered short for "finally tasks in a pipeline". Another option sould be to go the other way and always use "final tasks" (and never say "finally tasks"). However if we do this, @Srivaralakshmi pointed out in tektoncd#4086 that this may make it confusing in that reading something like 'the final tasks' may make a user expect to see a seciton in the pipeline called `final` instead of the actual section `finally`. We have another option which is to consider `finally`- an adverb - a bad name for that section of the Pipeline spec and change it to `final`. My understanding of the syntax is a bit different, e.g.: ```yaml spec: tasks: - name: tests taskRef: name: integration-test finally: - name: cleanup-test taskRef: name: cleanup ``` I understand the finally section to be saying: once all of the above is done, finally run clean-test, and not to say "cleanup-test is a finally kind of task". However that would be a big change (tho pre-v1 would be the time to do it!) and `finally` is consistent with how this kind of functionality is expressed in languages like Python. The last option would be to support both final and finally but that feels to me like it would be even more confusing.
This commit changes all references to "final tasks" and "finally tasks" to `finally` tasks". We were using a mix of "final tasks" and "finally tasks" to refer to these tasks, so this commit is making us consistently use one version. "finally tasks" is less grammatically correct that "final tasks" because finally is an adverb - "finally tasks" only makes sense if "finally tasks" is considered short for "finally tasks in a pipeline". We're working around this by using code block syntax to indicate that `finally` is a symbol in the Pipeline spec, and not just the adverb "finally". Another option sould be to go the other way and always use "final tasks" (and never say "finally tasks"). However if we do this, @Srivaralakshmi pointed out in tektoncd#4086 that this may make it confusing in that reading something like 'the final tasks' may make a user expect to see a seciton in the pipeline called `final` instead of the actual section `finally`. We have another option which is to consider `finally`- an adverb - a bad name for that section of the Pipeline spec and change it to `final`. My understanding of the syntax is a bit different, e.g.: ```yaml spec: tasks: - name: tests taskRef: name: integration-test final: - name: cleanup-test taskRef: name: cleanup ``` However that would be a big change (tho pre-v1 would be the time to do it!) and `finally` is consistent with how this kind of functionality is expressed in languages like Python. (Also I understand the finally section to be saying: once all of the above is done, finally run clean-test, and not to say "cleanup-test is a finally kind of task".) The last option would be to support both final and finally but that feels to me like it would be even more confusing.
Having the term " Another option would be to always use a roundabout way of referring to this, such as "tasks in the |
That sounds like a viable option to me. |
|
@rkratky and @afrittoli Thank you very much for the response and support. |
|
@bobcatfish Thanks for the response and also for adding this issue to the API working group agenda. FYI, I do not have access to this document; have sent a request. |
|
@Srivaralakshmi to get access to the doc you need to join the tekton-dev mailing list, more info on how to do that at https://github.com/tektoncd/community/blob/main/contact.md#mailing-list 🙏 |
|
There as some discussion in the API working group today (notes here) - seems like the general sentiment is to stick with |
|
@bobcatfish Thanks for the update. |
This commit changes all references to "final tasks" and "finally tasks" to `finally` tasks". We were using a mix of "final tasks" and "finally tasks" to refer to these tasks, so this commit is making us consistently use one version. "finally tasks" is less grammatically correct that "final tasks" because finally is an adverb - "finally tasks" only makes sense if "finally tasks" is considered short for "finally tasks in a pipeline". We're working around this by using code block syntax to indicate that `finally` is a symbol in the Pipeline spec, and not just the adverb "finally". Another option sould be to go the other way and always use "final tasks" (and never say "finally tasks"). However if we do this, @Srivaralakshmi pointed out in tektoncd#4086 that this may make it confusing in that reading something like 'the final tasks' may make a user expect to see a seciton in the pipeline called `final` instead of the actual section `finally`. We have another option which is to consider `finally`- an adverb - a bad name for that section of the Pipeline spec and change it to `final`. My understanding of the syntax is a bit different, e.g.: ```yaml spec: tasks: - name: tests taskRef: name: integration-test final: - name: cleanup-test taskRef: name: cleanup ``` However that would be a big change (tho pre-v1 would be the time to do it!) and `finally` is consistent with how this kind of functionality is expressed in languages like Python. (Also I understand the finally section to be saying: once all of the above is done, finally run clean-test, and not to say "cleanup-test is a finally kind of task".) The last option would be to support both final and finally but that feels to me like it would be even more confusing.
This commit changes all references to "final tasks" and "finally tasks" to `finally` tasks". We were using a mix of "final tasks" and "finally tasks" to refer to these tasks, so this commit is making us consistently use one version. "finally tasks" is less grammatically correct that "final tasks" because finally is an adverb - "finally tasks" only makes sense if "finally tasks" is considered short for "finally tasks in a pipeline". We're working around this by using code block syntax to indicate that `finally` is a symbol in the Pipeline spec, and not just the adverb "finally". Another option sould be to go the other way and always use "final tasks" (and never say "finally tasks"). However if we do this, @Srivaralakshmi pointed out in #4086 that this may make it confusing in that reading something like 'the final tasks' may make a user expect to see a seciton in the pipeline called `final` instead of the actual section `finally`. We have another option which is to consider `finally`- an adverb - a bad name for that section of the Pipeline spec and change it to `final`. My understanding of the syntax is a bit different, e.g.: ```yaml spec: tasks: - name: tests taskRef: name: integration-test final: - name: cleanup-test taskRef: name: cleanup ``` However that would be a big change (tho pre-v1 would be the time to do it!) and `finally` is consistent with how this kind of functionality is expressed in languages like Python. (Also I understand the finally section to be saying: once all of the above is done, finally run clean-test, and not to say "cleanup-test is a finally kind of task".) The last option would be to support both final and finally but that feels to me like it would be even more confusing.
|
fixed in #4090 /close |
|
@jerop: Closing this issue. In response to this:
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. |
Expected behaviour:
finalin the specification: https://github.com/tektoncd/pipeline/blob/main/docs/pipelines.md#adding-finally-to-the-pipelinefinallytofinal, continue to allow thefinallykey to accommodate the users who already have thefinallykey as part of their specification.Actual behaviour: At present the name used to represent the final set of tasks at the end of the pipeline is represented as
finallyin the specification: https://github.com/tektoncd/pipeline/blob/main/docs/pipelines.md#adding-finally-to-the-pipelineReason for this proposal:
finaltasks and notfinallytasks. We need to use one terminology consistently. Also the terminology must be correct both technically and from the language perspective as well.The text was updated successfully, but these errors were encountered: