zhongjiajie commented on a change in pull request #4827: [AIRFLOW-XXX] Add contribute guide to docs URL: https://github.com/apache/airflow/pull/4827#discussion_r270330903
########## File path: docs/contributing.rst ########## @@ -0,0 +1,479 @@ +.. 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. + +Developer's Guide +================= + +Contributions are welcome and are greatly appreciated! Every +little bit helps, and credit will always be given. + +.. contents:: + :local: + +Types of Contributions +---------------------- + +Report Bugs +^^^^^^^^^^^ + +Report bugs through `Apache Jira <https://issues.apache.org/jira/browse/AIRFLOW>`__ + +Please report relevant information and preferably code that exhibits +the problem. + +Fix Bugs +^^^^^^^^ + +Look through the Jira issues for bugs. Anything is open to whoever wants +to implement it. + +Implement Features +^^^^^^^^^^^^^^^^^^ + +Look through the `Apache Jira <https://issues.apache.org/jira/browse/AIRFLOW>`__ for features. Any unassigned "Improvement" issue is open to whoever wants to implement it. + +We've created the operators, hooks, macros and executors we needed, but we +made sure that this part of Airflow is extensible. New operators, +hooks, macros and executors are very welcomed! + +Improve Documentation +^^^^^^^^^^^^^^^^^^^^^ + +Airflow could always use better documentation, +whether as part of the official Airflow docs, +in docstrings, ``docs/*.rst`` or even on the web as blog posts or +articles. + +Submit Feedback +^^^^^^^^^^^^^^^ + +The best way to send feedback is to open an issue on `Apache Jira <https://issues.apache.org/jira/browse/AIRFLOW>`__. + +If you are proposing a feature: + +- Explain in detail how it would work. +- Keep the scope as narrow as possible, to make it easier to implement. +- Remember that this is a volunteer-driven project, and that contributions are welcome :) + +Documentation +------------- + +The latest API documentation is usually available +`here <https://airflow.apache.org/>`__. To generate a local version, +you need to have set up an Airflow development environment (see below). Also +install the `doc` extra. + +.. code-block:: bash + + pip install -e .[doc] + +Generate and serve the documentation by running: + +.. code-block:: bash + + cd docs + ./build.sh + ./start_doc_server.sh + + +Only a subset of the API reference documentation builds. Install additional +extras to build the full API reference. + +Development and Testing +----------------------- + +Setting up a development environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +There are three ways to setup an Apache Airflow development environment. + +1. Using tools and libraries installed directly on your system + + Install Python (2.7.x or 3.5.x), MySQL, and libxml by using system-level package + managers like yum, apt-get for Linux, or Homebrew for Mac OS at first. Refer to the `base CI Dockerfile <https://github.com/apache/airflow-ci/blob/master/Dockerfile>`__ for + a comprehensive list of required packages. + + Then install python development requirements. It is usually best to work in a virtualenv: + + .. code-block:: bash + + cd $AIRFLOW_HOME + virtualenv env + source env/bin/activate + pip install -e .[devel] + + +2. Using a Docker container + + Go to your Airflow directory and start a new docker container. You can choose between Python 2 or 3, whatever you prefer. + + .. code-block:: bash + + # Start docker in your Airflow directory + docker run -t -i -v `pwd`:/airflow/ -w /airflow/ python:3 bash + + # Install Airflow with all the required dependencies, + # including the devel which will provide the development tools + pip install -e ".[hdfs,hive,druid,devel]" Review comment: ```suggestion pip install -e '.[hdfs,hive,druid,devel]' ``` ---------------------------------------------------------------- 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] With regards, Apache Git Services
