potiuk commented on a change in pull request #13767:
URL: https://github.com/apache/airflow/pull/13767#discussion_r561720939
##########
File path: dev/provider_packages/PROVIDER_INDEX_TEMPLATE.rst.jinja2
##########
@@ -0,0 +1,84 @@
+{#
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+ NOTE! THIS FILE IS AUTOMATICALLY GENERATED AND WILL BE
+ OVERWRITTEN WHEN PREPARING PACKAGES.
+
+ IF YOU WANT TO MODIFY IT, YOU SHOULD MODIFY THE TEMPLATE
+ `PROVIDER_INDEX_TEMPLATE.rst.jinja2` IN the `provider_packages` DIRECTORY
+
+#}
+
+Package {{ PACKAGE_PIP_NAME }}
+------------------------------------------------------
+
+Release: {{ RELEASE }}{{ VERSION_SUFFIX }}
+
+Provider package
+----------------
+
+This is a provider package for ``{{PROVIDER_PACKAGE_ID}}`` provider. All
classes for this provider package
+are in ``{{FULL_PACKAGE_NAME}}`` python package.
+
+Installation
+------------
+
+.. note::
+
+ On November 2020, new version of PIP (20.3) has been released with a new,
2020 resolver. This resolver
+ does not yet work with Apache Airflow and might lead to errors in
installation - depends on your choice
+ of extras. In order to install Airflow you need to either downgrade pip to
version 20.2.4
+ ``pip install --upgrade pip==20.2.4`` or, in case you use Pip 20.3, you
need to add option
+ ``--use-deprecated legacy-resolver`` to your pip install command.
+
+
+You can install this package on top of an existing airflow 2.* installation via
+``pip install {{PACKAGE_PIP_NAME}}``
+{%- if PIP_REQUIREMENTS %}
+
+PIP requirements
+----------------
+
+{{ PIP_REQUIREMENTS_TABLE_RST | safe}}
+{%- endif %}
+{%- if CROSS_PROVIDERS_DEPENDENCIES %}
+
+Cross provider package dependencies
+-----------------------------------
+
+Those are dependencies that might be needed in order to use all the features
of the package.
+You need to install the specified backport providers package in order to use
them.
+
+You can install such cross-provider dependencies when installing from PyPI.
For example:
+
+.. code-block:: bash
+
+ pip install {{ PACKAGE_PIP_NAME }}[{{ CROSS_PROVIDERS_DEPENDENCIES[0] }}]
+
+
+{{ CROSS_PROVIDERS_DEPENDENCIES_TABLE_RST | safe }}
+
+{%- endif %}
Review comment:
Just one comment here @kaxil @mik-laj about the naming/change process.
I am not totally against naming it UPDATING.md, but I think we are confusing
a bit airflow and providers release cycle. I think we should get the naming
right and content of this "manually written" parts.
I believe most of provider releases will be incremental updates - new
hooks/operators added basically or new (backwards-compatible) changes in the
operators. The changes that we have now in Google Providers are exception
rather than rule. We only need to add the "upgrading" guide because we make
backwards-incompatible changes due to 2.0 APIs. In vast majority of cases
people should be able to do 'pip install --upgrade
`apache-airflow-providers-<NN>` and there should be no need to follow any
"updating" guide. This is the main premise of semver, which communicates
breaking changes. The only time where we need to add "updating" information is
when we go 1.0.0 -> 2.0.0 etc.
Now - this means that vast majority of changes will be simply "new operator
"xxx" added". That's why I think CHANGELOG.rst is a good name, and this is also
a good name for the Heading in the docs.
While idally indeed we should be able to automaticaly get it from semantic
commits (and I am more and more convinced that we should switch to those), this
is a decision that will time to discuss and vote and apply and it will take
some time for people to adjust to, and we can do it as a follow-up. For now I
think this will be very little overhead if we just agree between committers,
that every time a new stuff is added to provider, we ask the PR author to add
entry in the CHANELOG.md and provider.yaml:
1) Add new version in provider.yaml patchelevel number (for bugfixes) or
minor version (for features)
2) Add a line in CHANGELOG.txt to describe the change added.
I think this makes it nicely distributed among the PR authors, and decreases
a lot the work needed by release manager (@kaxil :) - then PR authors and
commiters will take care about updating the versions and the role of release
manager will be just to review whether everything was included. Remember that
release manager will have to sometimes release 10-20 providers at a time and
mostly providers that the release manager knows very little about, so the less
work is put on the shoulders of that person, the better.
Let me know WDYT @kaxil @mik-laj and @ashb (I am mentioning @ashb here for
the release management part mainly).
----------------------------------------------------------------
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]
