mik-laj commented on a change in pull request #9320: URL: https://github.com/apache/airflow/pull/9320#discussion_r440586097
########## File path: CONTRIBUTING.rst ########## @@ -542,8 +542,48 @@ We support the following types of tests: For details on running different types of Airflow tests, see `TESTING.rst <TESTING.rst>`_. + +Naming Conventions for provider packages +======================================== + +In Airflow 2.0 we standardized and enforced naming for provider packages, modules and classes. +those rules (introduced as AIP-21) were not only introduced but enforced using automated checks +that verify if the naming conventions are followed. Here is a brief summary of the rules, for +detailed discussion you can go to [AIP-21 Changes in import paths](https://cwiki.apache.org/confluence/display/AIRFLOW/AIP-21%3A+Changes+in+import+paths) + +The rules are as follows: + +* Provider packages are all placed in 'airflow.providers' +* Providers are usually direct sub-packages of the 'airflow.providers' package but in some cases they can be + further split into sub-packages (for example 'apache' package has 'cassandra', 'druid' ... providers ) out + of which several different provider packages are produced (apache.cassandra, apache.druid). This is + case when the providers are connected under common umbrella but very loosely coupled on the code level. +* In some cases the package can have sub-packages but they are all delivered as single provider + package (for example 'google' package contains 'ads', 'cloud' etc. sub-packages). This is in case + the providers are connected under common umbrella and they are also tightly coupled on the code level. +* Typical structure of provider package: + * example_dags -> example DAGs are stored here (used for documentation and System Tests) + * hooks -> hooks are stored here + * operators -> operators are stored here + * sensors -> sensors are stored here + * secrets -> secret backends are stored here + * transfers -> transfer operators are stored here +* Module names do not contain word "hooks" , "operators" etc. The right type comes from + the package. For example 'hooks.datastore' module contains DataStore hook and 'operators.datastore' + contains DataStore operators. +* Class names contain 'Operator', 'Hook', 'Sensor' - for example DataStoreHook, DataStoreExportOperator +* Operator name usually follows the convention: <Subject><Action>Operator (DataStoreExportOperator) is a good Review comment: ```suggestion * Operator name usually follows the convention: <Subject><Action><Entity>Operator (BigQueryExecuteQueryOperator) is a good ``` It is not a good idea to use the verb alone. Here is an example: https://github.com/apache/airflow/pull/9314 We had CloudBuildCreate to create Build, and then it turned out that the service has grown and you can also create BuildTriggey, so we created a new operator CloudBuildCreateBuildTrigger. If we do not have a noun, the operator's name has become ambiguous. ---------------------------------------------------------------- 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: [email protected]
