Incomplete or outdated documentation

Oct 13, 2025 by talynt.org 90 views

Introduction

Kestra is a powerful workflow engine that allows users to create, manage, and execute complex workflows. However, with the constant evolution of technology and changing requirements, some features and properties in Kestra may become deprecated. In this article, we will discuss an issue where some deprecation notices do not appear in the embedded doc for the io.kestra.plugin.scripts.python.Script task.

Describe the Issue

The issue at hand is that the deprecation notice icon appears for some properties but not for all, while the validator tags the flow with a warning since it uses a deprecated property. This inconsistency can lead to confusion and make it difficult for users to identify deprecated properties.

Example of Deprecation Notice

For instance, in the io.kestra.plugin.scripts.python.Script task, the deprecation notice icon appears for some properties like OutputDirectory, but not for all. This is shown in the following image:

Environment

The issue was encountered in the following environment:

Kestra Version: 0.21.5

Causes of the Issue

There could be several reasons why some deprecation notices do not appear in the embedded doc. Some possible causes include:

Incomplete or outdated documentation: If the documentation is incomplete or outdated, it may not reflect the current state of the properties and their deprecation status.
Incorrect configuration: If the configuration of the Kestra instance is incorrect, it may lead to inconsistent behavior, including the failure of deprecation notices to appear.
Bug in the Kestra engine: It is possible that there is a bug in the Kestra engine that is causing the deprecation notices to not appear.

Impact of the Issue

The issue of deprecation notices not appearing in the embedded doc can have significant consequences, including:

Confusion and frustration: Users may become confused and frustrated when they encounter deprecated properties without clear indication of their deprecation status.
Inconsistent behavior: The inconsistent behavior can lead to errors and unexpected outcomes, which can be difficult to debug and resolve.
Security risks: In some cases, deprecated properties may pose security risks if they are not properly handled.

Solution to the Issue

To resolve the issue, the following steps can be taken:

Update the documentation: Ensure that the documentation is up-to-date and reflects the current state of the properties and their deprecation status.
Verify the configuration: Verify that the configuration of the Kestra instance is correct and consistent.
Report the bug: If the issue is caused by a bug in the Kestra engine, report it to the Kestra team and wait for a fix.

Best Practices for Avoiding Similar Issues

To avoid similar issues in the future, follow these best practices:

Regularly review and update documentation: Regularly review and update the documentation to ensure that it reflects the current state of the properties and their deprecation status.
Verify configuration: Verify the configuration of the Kestra instance regularly to ensure that it is correct and consistent.
Monitor for bugs: Monitor for bugs in the Kestra engine and report them to the Kestra team as soon as possible.

Conclusion

Q: What is the deprecation notice in Kestra?

A: The deprecation notice in Kestra is a warning that indicates a property or feature is no longer supported and may be removed in a future version.

Q: Why is the deprecation notice not appearing in the embedded doc?

A: The deprecation notice may not appear in the embedded doc due to incomplete or outdated documentation, incorrect configuration, or a bug in the Kestra engine.

Q: What are the consequences of deprecation notices not appearing in the embedded doc?

A: The consequences of deprecation notices not appearing in the embedded doc can include confusion and frustration, inconsistent behavior, and security risks.

Q: How can I resolve the issue of deprecation notices not appearing in the embedded doc?

A: To resolve the issue, update the documentation, verify the configuration, and report the bug to the Kestra team.

Q: What are the best practices for avoiding similar issues in the future?

A: The best practices for avoiding similar issues in the future include regularly reviewing and updating documentation, verifying configuration, and monitoring for bugs.

Q: Can I customize the deprecation notice in Kestra?

A: Yes, you can customize the deprecation notice in Kestra by modifying the configuration or using a custom plugin.

Q: How can I get notified when a property or feature is deprecated?

A: You can get notified when a property or feature is deprecated by enabling the deprecation notification feature in the Kestra configuration.

Q: What is the impact of using deprecated properties or features in Kestra?

A: The impact of using deprecated properties or features in Kestra can include inconsistent behavior, security risks, and potential errors.

Q: Can I use deprecated properties or features in Kestra if I know what I'm doing?

A: While it is possible to use deprecated properties or features in Kestra if you know what you're doing, it is not recommended as it can lead to inconsistent behavior and security risks.

Q: How can I report a bug in the Kestra engine?

A: You can report a bug in the Kestra engine by submitting a ticket to the Kestra team or by using the Kestra community forum.

Q: What is the process for updating the documentation in Kestra?

A: The process for updating the documentation in Kestra involves submitting a pull request to the Kestra documentation repository or by using the Kestra community forum.

Q: Can I customize the documentation in Kestra?

A: Yes, you can customize the documentation in Kestra by modifying the documentation templates or by using a custom plugin.

Q: How can I get help with Kestra?

A: You can get help with Kestra by using the Kestra community forum, submitting a ticket to the Kestra team, or by using the Kestra documentation.