[GitHub] [airflow] kaxil commented on a change in pull request #4932: [AIRFLOW-3611] Breeze

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

kaxil commented on a change in pull request #4932: [AIRFLOW-3611] Breeze
URL: https://github.com/apache/airflow/pull/4932#discussion_r317285661
 
 

 ##########
 File path: BREEZE.rst
 ##########
 @@ -0,0 +1,753 @@
+ .. 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.
+
+.. raw:: html
+
+   <p align="center">
+     <img src="images/AirflowBreeze_logo.png" alt="Airflow Breeze Logo"/>
+   </p>
+
+
+Table of Contents
+=================
+
+* `Airflow Breeze <#airflow-breeze>`_
+* `Installation <#installation>`_
+* `Setting up autocomplete <#setting-up-autocomplete>`_
+* `Using the Airflow Breeze environment <#using-the-airflow-breeze-environment>`_
+    - `Entering the environment <#entering-the-environment>`_
+    - `Running tests in Airflow Breeze <#running-tests-in-airflow-breeze>`_
+    - `Debugging with ipdb <#debugging-with-ipdb>`_
+    - `Airflow directory structure in Docker <#airflow-directory-structure-inside-docker>`_
+    - `Port forwarding <#port-forwarding>`_
+* `Using your host IDE <#using-your-host-ide>`_
+    - `Configuring local virtualenv <#configuring-local-virtualenv>`_
+    - `Running unit tests via IDE <#running-unit-tests-via-ide>`_
+    - `Debugging Airflow Breeze Tests in IDE <#debugging-airflow-breeze-tests-in-ide>`_
+* `Running commands via Airflow Breeze <#running-commands-via-airflow-breeze>`_
+    - `Running static code checks <#running-static-code-checks>`_
+    - `Building the documentation <#building-the-documentation>`_
+    - `Running tests <#running-tests>`_
+    - `Running commands inside Docker <#running-commands-inside-docker>`_
+    - `Running Docker Compose commands <#running-docker-compose-commands>`_
+    - `Convenience scripts <#convenience-scripts>`_
+* `Keeping images up-to-date <#keeping-images-up-to-date>`_
+    - `Updating dependencies <#updating-dependencies>`_
+    - `Pulling the images <#pulling-the-images>`_
+* `Airflow Breeze flags <#airflow-breeze-flags>`_
+
+Airflow Breeze
+==============
+
+Airflow Breeze is an easy-to-use integration test environment managed via
+`Docker Compose <https://docs.docker.com/compose/>`_ .
+The environment is easy to use locally and it is also used by Airflow's CI Travis tests.
+
+It's called **Airflow Breeze** as in "It's a *Breeze* to develop Airflow"
+
+The advantages and disadvantages of using the environment vs. other ways of testing Airflow
+are described in `CONTRIBUTING.md <CONTRIBUTING.md#integration-test-development-environment>`_.
+
+Here is the short 10 minute video about Airflow Breeze
+
+.. image:: http://img.youtube.com/vi/ffKFHV6f3PQ/0.jpg
+   :width: 480px
+   :height: 360px
+   :scale: 100 %
+   :alt: Airflow Breeze Simplified Development Workflow
+   :align: center
+   :target: http://www.youtube.com/watch?v=ffKFHV6f3PQ
+
+
+Installation
+============
+
+Prerequisites for the installation:
+
+
+*
+  If you are on MacOS you need gnu getopt to get Airflow Breeze running. Typically
+  uou need to run ``brew install gnu-getopt`` and then follow instructions (you need
+  to link the gnu getopt version to become first on the PATH).
+
+*
+  Latest stable Docker Community Edition installed and on the PATH. It should be
+  configured to be able to run ``docker`` commands directly and not only via root user
+
+
+  * your user should be in ``docker`` group.
+    See `Docker installation guide <https://docs.docker.com/install/>`_
+
+*
+  Latest stable Docker Compose installed and on the PATH. It should be
+  configured to be able to run ``docker-compose`` command.
+  See `Docker compose installation guide <https://docs.docker.com/compose/install/>`_
+
+*
+  in case of MacOS you need ``gstat`` installed via brew or port. The stat command from MacOS
+  is very old and poor. The best way to install it is via ``brew install coreutils``
+
+
+Your entry point for Airflow Breeze is `./breeze <./breeze>`_
+script. You can run it with ``-h`` option to see the list of available flags.
+You can add the checked out airflow repository to your PATH to run breeze
+without the ./ and from any directory if you have only one airflow directory checked out.
+
+See `Airflow Breeze flags <#airflow-breeze-flags>`_ for details.
+
+First time you run `./breeze <./breeze>`_ script, it will pull and build local version of docker images.
+It will pull latest Airflow CI images from `Apache Airflow DockerHub <https://hub.docker.com/r/apache/airflow>`_
+and use them to build your local docker images. It will use latest sources from your source code.
+Further on ``breeze`` uses md5sum calculation and Docker caching mechanisms to only rebuild what is needed.
+Airflow Breeze will detect if Docker images need to be rebuilt and ask you for confirmation.
+
+Setting up autocomplete
+=======================
+
+The ``breeze`` command comes with built-in bash/zsh autocomplete. When you start typing
+`./breeze <./breeze>`_ command you can use <TAB> to show all the available switches
+nd to get autocompletion on typical values of parameters that you can use.
+
+You can setup auto-complete automatically by running this command (-a is shortcut for --setup-autocomplete):
+
+.. code-block:: bash
+
+   ./breeze --setup-autocomplete
 
 Review comment:
   Awesome

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