[GitHub] [airflow] baolsen commented on a change in pull request #6999: [AIRFLOW-XXXX] Clarify wait_for_downstream and execution_date

[GitBox <gi...@apache.org>]

baolsen commented on a change in pull request #6999: [AIRFLOW-XXXX] Clarify wait_for_downstream and execution_date
URL: https://github.com/apache/airflow/pull/6999#discussion_r362704684
 
 

 ##########
 File path: docs/tutorial.rst
 ##########
 @@ -313,8 +315,16 @@ to track the progress. ``airflow webserver`` will start a web server if you
 are interested in tracking the progress visually as your backfill progresses.
 
 Note that if you use ``depends_on_past=True``, individual task instances
-will depend on the success of the preceding task instance, except for the
-start_date specified itself, for which this dependency is disregarded.
+will depend on the success of their previous task instance (that is, previous
 
 Review comment:
   Thanks for the feedback. 
   
   So I wasn't 100% decided between "preceding" vs "previous", but decided to change it to previous because "previous" is the word used elsewhere in the documentation and code to refer to "past instances". 
   I learned yesterday that the two words have very similar definition and can be used interchangeably :). 
   
   It can be confusing to a developer. "previous + next" usually go together as concepts and refer to objects that are linked somehow, yet in this context the tasks that are linked are actually called "upstream/downstream". 
   
   However, across the code we have used "previous" to refer to "past instances" of tasks and dag runs, meaning perhaps it is more natural to refer to "previous" things rather than "past"/"preceding"/"prior" things.
   
   I've just found the Concepts section and I think it would be good to add some definitions here. As a new user is can be really confusing to understand upstream/downstream vs previous/next execution. Execution_date isn't even mentioned in Concepts at all - I'll see if I can add something.
   

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services