Added ADR document describing why the notion of dialects was introduced in the common sql provider

[dabla]

Added ADR document describing why the notion of dialects was introduced in the common sql provider.

---

^ Add meaningful description above
Read the Pull Request Guidelines for more information.
In case of fundamental code changes, an Airflow Improvement Proposal (AIP) is needed.
In case of a new dependency, check compliance with the ASF 3rd Party License Policy.
In case of backwards incompatible changes please leave a note in a newsfragment file, named {pr_number}.significant.rst or {issue_number}.significant.rst, in newsfragments.

[dabla]

@potiuk @jscheffl As promised a document describing the dialects in common sql provider. If any remarks or improvements are necessary please let me know.

[eladkal]

NIce! I think we are also missing user facing docs about what dialects are and how to use them (ADR is for Airflow developers to document our design choices but it's not really a user facing doc)

[dabla]

NIce! I think we are also missing user facing docs about what dialects are and how to use them (ADR is for Airflow developers to document our design choices but it's not really a user facing doc)

Where should I put those user facing docs? Is that under docs/apache-airflow-providers-common-sql? Should I create a new dialects.rst document?

[eladkal]

Where should I put those user facing docs? Is that under docs/apache-airflow-providers-common-sql? Should I create a new dialects.rst document?

Yes. You dont have to create new .rst
Depends on the scope of what you write. If its 1-2 pargraphs it might fit in the current rst we have.
However you may want to mention in the providers we have dedicated dialect how to use it and link to the doc in common.sql so there may be need for doc changea in several providers

[eladkal]

@dabla do you intend to add the docs in this PR?

[dabla]

@dabla do you intend to add the docs in this PR?

I just committed a new dialects.rst and adapted the index.rst this morning, what do you think about it?

[jscheffl]

Sorry, "late to the party" now digging through my backlog... wanted to review earlier.

I really like this and the description.

For the docs build problem I see two options: (1) [not sure if this really works] outside the TOC create a small RST just with the heading and pointing to the other doctree - or (2) if you want to have exactly the same doc in each provider then use a symlink in GIT such that the RST is maintained in one place and each doctree has the same. (As long as we not move the providers the symlink is working in Sphinx)

Can you add some example the the dialects.rst or is this already contained in the implementation PR?

[dabla]

Sorry, "late to the party" now digging through my backlog... wanted to review earlier.

I really like this and the description.

For the docs build problem I see two options: (1) [not sure if this really works] outside the TOC create a small RST just with the heading and pointing to the other doctree - or (2) if you want to have exactly the same doc in each provider then use a symlink in GIT such that the RST is maintained in one place and each doctree has the same. (As long as we not move the providers the symlink is working in Sphinx)

Can you add some example the the dialects.rst or is this already contained in the implementation PR?

Will look into it. I also opened another PR related to this which fixes an issue with reserved words and special characters using the dialects.

[dabla]

Sorry, "late to the party" now digging through my backlog... wanted to review earlier.

I really like this and the description.

For the docs build problem I see two options: (1) [not sure if this really works] outside the TOC create a small RST just with the heading and pointing to the other doctree - or (2) if you want to have exactly the same doc in each provider then use a symlink in GIT such that the RST is maintained in one place and each doctree has the same. (As long as we not move the providers the symlink is working in Sphinx)

Can you add some example the the dialects.rst or is this already contained in the implementation PR?

Not that found of symlinks, dunno how git will handle those. Aren't http references an option? I saw it's also used within rst.

For example (won't exist atm ofc):

https://airflow.apache.org/docs/apache-airflow-providers-common-sql/stable/dialects.html

[dabla]

@eladkal I've duplicated the dialects document in each provider, we can sort it out later as you mentioned