diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a8d1dd861ab47..04b0d7f7135c2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,7 +32,7 @@ the problem. ### Fix Bugs -Look through the Jira issues for bugs. Anything is open to whoever wants +Look through the Jira issues for bugs. Anything is open to whoever wants to implement it. ### Implement Features @@ -65,8 +65,8 @@ If you are proposing a feature: ## Documentation -The latest API documentation is usually available [here](http://pythonhosted.org/airflow). -To generate a local version, you need to have installed airflow with +The latest API documentation is usually available [here](http://pythonhosted.org/airflow). +To generate a local version, you need to have installed airflow with the `doc` extra. In that case you can generate the doc by running: cd docs && ./build.sh @@ -93,28 +93,38 @@ Before you submit a pull request from your forked repo, check that it meets these guidelines: 1. The pull request should include tests, either as doctests, unit tests, or -both. The airflow repo uses [Travis CI](https://travis-ci.org/apache/incubator-airflow) -to run the tests and [codecov](https://codecov.io/gh/apache/incubator-airflow) -to track coverage. You can set up both for free on your fork. It will -help you making sure you do not break the build with your PR and that you help +both. The airflow repo uses [Travis CI](https://travis-ci.org/apache/incubator-airflow) +to run the tests and [codecov](https://codecov.io/gh/apache/incubator-airflow) +to track coverage. You can set up both for free on your fork. It will +help you making sure you do not break the build with your PR and that you help increase coverage. -2. If the pull request adds functionality, the docs should be updated as part +2. Please [rebase your fork](http://stackoverflow.com/a/7244456/1110993), +squash commits, and resolve all conflicts. +3. Every pull request should have an associated +[JIRA](https://issues.apache.org/jira/browse/AIRFLOW/?selectedTab=com.atlassian.jira.jira-projects-plugin:summary-panel). +The JIRA link should also be contained in the PR description. +4. Preface your commit's subject & PR's title with **[AIRFLOW-XXX]** +where *XXX* is the JIRA number. We compose release notes (i.e. for Airflow releases) from all commit titles in a release. +By placing the JIRA number in the commit title and hence in the release notes, +Airflow users can look into JIRA and Github PRs for more details about a particular change. +5. Add an [Apache License](http://www.apache.org/legal/src-headers.html) + header to all new files +6. If the pull request adds functionality, the docs should be updated as part of the same PR. Doc string are often sufficient. Make sure to follow the -sphinx compatible standards. -3. The pull request should work for Python 2.7 and 3.4. If you need help +Sphinx compatible standards. +7. The pull request should work for Python 2.7 and 3.4. If you need help writing code that works in both Python 2 and 3, see the documentation at the [Python-Future project](http://python-future.org) (the future package is an Airflow requirement and should be used where possible). -4. As Airflow grows as a project, we try to enforce a more consistent -style and try to follow the Python community guidelines. We track this -using [landscape.io](https://landscape.io/github/apache/incubator-airflow/), -which you can setup on your fork as well to check before you submit your -PR. We currently enforce most [PEP8](https://www.python.org/dev/peps/pep-0008/) -and a few other linting rules. It is usually a good idea to lint locally -as well using [flake8](https://flake8.readthedocs.org/en/latest/) +8. As Airflow grows as a project, we try to enforce a more consistent +style and try to follow the Python community guidelines. We track this +using [landscape.io](https://landscape.io/github/apache/incubator-airflow/), +which you can setup on your fork as well to check before you submit your +PR. We currently enforce most [PEP8](https://www.python.org/dev/peps/pep-0008/) +and a few other linting rules. It is usually a good idea to lint locally +as well using [flake8](https://flake8.readthedocs.org/en/latest/) using `flake8 airflow tests` -5. Please rebase and resolve all conflicts before submitting. -6. Please read this excellent [article](http://chris.beams.io/posts/git-commit/) on +9. Please read this excellent [article](http://chris.beams.io/posts/git-commit/) on commit messages and adhere to them. It makes the lives of those who come after you a lot easier. @@ -127,8 +137,8 @@ Tests can then be run with (see also the [Running unit tests](#running-unit-test #### Running unit tests -We *highly* recommend setting up [Travis CI](https://travis-ci.org/) on -your repo to automate this. It is free for open source projects. If for +We *highly* recommend setting up [Travis CI](https://travis-ci.org/) on +your repo to automate this. It is free for open source projects. If for some reason you cannot, you can use the steps below to run tests. Here are loose guidelines on how to get your environment to run the unit tests.