[GitHub] [superset] geido commented on pull request #18229: chore: POC for referencing Github code in Docusaurus

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

geido commented on pull request #18229:
URL: https://github.com/apache/superset/pull/18229#issuecomment-1025797159


   > I like the direction, but I am afraid about the maintenance of that solution in long term. We have a hard-coded commit ID (or git tag) and a hard-coded line number. This can be easily outdated:
   > 
   > * the example will be updated and the commit IT will not be updated to point to the new code,
   > * the reference will be updated with the new code, but the lines will not be changed, e.g. extended with an additional enter added.
   > 
   > As for the first case, we may use the version identifier (git tag) instead of commit in the future. However, then the second case is then even more likely.
   > 
   > To reduce this case scenario Apache Airflow uses comments in the referenced file ( https://github.com/apache/airflow/blob/main/docs/apache-airflow/tutorial_taskflow_api.rst ), predicable comment structure (tags eg. for examples is added before this is required in the documentation). It allows also check that references on CI.
   
   Hey @ad-m you are perfectly right and we also share these concerns. However, for the time being, we are happy with this solution as the code references that we are looking to add do not change very often. We definitely would like to think of longer-term solutions and the Airflow solution seems well structured. I am pinging @villebro who also has some ideas on this topic.


-- 
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.

To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@superset.apache.org
For additional commands, e-mail: notifications-help@superset.apache.org