|
| 1 | +Contributing |
| 2 | +============================ |
| 3 | + |
| 4 | +- **Please sign one of the contributor license agreements below.** |
| 5 | +- Fork the repo, develop and test your code changes, add docs. |
| 6 | +- Make sure that your commit messages clearly describe the changes. |
| 7 | +- Send a pull request. |
| 8 | + |
| 9 | +Here are some guidelines for hacking on `ndb`. |
| 10 | + |
| 11 | +Using a Development Checkout |
| 12 | +---------------------------- |
| 13 | + |
| 14 | +You'll have to create a development environment to hack on `ndb`, |
| 15 | +using a Git checkout: |
| 16 | + |
| 17 | +- While logged into your GitHub account, navigate to the `ndb` repo on |
| 18 | +GitHub. |
| 19 | + |
| 20 | +``` |
| 21 | +https://github.com/pcostell/appengine-ndb-experiment |
| 22 | +``` |
| 23 | + |
| 24 | +- Fork and clone the `ndb` repository to your GitHub account by |
| 25 | +clicking the "Fork" button. |
| 26 | + |
| 27 | +- Clone your fork of `ndb` from your GitHub account to your local |
| 28 | +computer, substituting your account username and specifying the destination |
| 29 | +as `hack-on-ndb`. For example: |
| 30 | + |
| 31 | +``` |
| 32 | +$ cd ~ |
| 33 | +$ git clone [email protected]:USERNAME/appengine-ndb-experiment.git hack-on-ndb |
| 34 | +$ cd hack-on-ndb |
| 35 | +# Configure remotes such that you can pull changes from the ndb-git |
| 36 | +# repository into your local repository. |
| 37 | +$ git remote add upstream https://github.com:pcostell/appengine-ndb-experiment |
| 38 | +# fetch and merge changes from upstream into master |
| 39 | +$ git fetch upstream |
| 40 | +$ git merge upstream/master |
| 41 | +``` |
| 42 | + |
| 43 | +Now your local repo is set up such that you will push changes to your GitHub |
| 44 | +repo, from which you can submit a pull request. |
| 45 | + |
| 46 | +- Create a virtualenv in which to install `ndb`: |
| 47 | + |
| 48 | +``` |
| 49 | +$ cd ~/hack-on-ndb |
| 50 | +$ virtualenv -ppython2.7 env |
| 51 | +``` |
| 52 | + |
| 53 | +Note that very old versions of `virtualenv` (versions below, say, |
| 54 | + 1.10 or thereabouts) require you to pass a `--no-site-packages` flag to |
| 55 | + get a completely isolated environment. |
| 56 | + |
| 57 | + You can choose which Python version you want to use by passing a `-p` |
| 58 | + flag to `virtualenv`. For example, `virtualenv -ppython2.7` |
| 59 | + chooses the Python 2.7 interpreter to be installed. |
| 60 | + |
| 61 | + From here on in within these instructions, the `~/hack-on-ndb/env` |
| 62 | + virtual environment you created above will be referred to as `${VENV}`. |
| 63 | + To use the instructions in the steps that follow literally, use the |
| 64 | + |
| 65 | + ``` |
| 66 | + $ export VENV=~/hack-on-ndb/env |
| 67 | + ``` |
| 68 | + |
| 69 | + command. |
| 70 | + |
| 71 | + - Install `ndb` from the checkout into the virtualenv using |
| 72 | + `setup.py develop`. Running `setup.py develop` **must** be done while |
| 73 | + the current working directory is the `ndb-git` checkout directory: |
| 74 | + |
| 75 | + ``` |
| 76 | + $ cd ~/hack-on-ndb |
| 77 | + $ ${VENV}/bin/python setup.py develop |
| 78 | + ``` |
| 79 | + |
| 80 | + Running Tests |
| 81 | + -------------- |
| 82 | + |
| 83 | + - To run all tests for `ndb`, run |
| 84 | + |
| 85 | + ``` |
| 86 | + $ make runtests |
| 87 | + ``` |
| 88 | + |
| 89 | + - In order to install the App Engine SDK for Python, you can either |
| 90 | + [download][1] the source as a zip file. |
| 91 | + |
| 92 | + If you already have the [Google Cloud SDK][2] (`gcloud` CLI tool) |
| 93 | + installed, then you can install via: |
| 94 | + |
| 95 | + ``` |
| 96 | + $ gcloud components update gae-python |
| 97 | + ``` |
| 98 | + |
| 99 | + If the Google Cloud SDK installed in `${GOOGLE_CLOUD_SDK}`, |
| 100 | + then the App Engine SDK can be found in |
| 101 | + `${GOOGLE_CLOUD_SDK}/platform/google_appengine` (as of January 2014). |
| 102 | + |
| 103 | + Contributor License Agreements |
| 104 | + ------------------------------ |
| 105 | + |
| 106 | + Before we can accept your pull requests you'll need to sign a Contributor |
| 107 | + License Agreement (CLA): |
| 108 | + |
| 109 | + - **If you are an individual writing original source code** and **you own the |
| 110 | + intellectual property**, then you'll need to sign an [individual CLA][3]. |
| 111 | + - **If you work for a company that wants to allow you to contribute your work**, |
| 112 | + then you'll need to sign a [corporate CLA][4]. |
| 113 | + |
| 114 | + You can sign these electronically (just scroll to the bottom). After that, |
| 115 | + we'll be able to accept your pull requests. |
| 116 | + |
| 117 | + [1]: https://cloud.google.com/appengine/downloads |
| 118 | + [2]: https://cloud.google.com/sdk/ |
| 119 | + [3]: https://developers.google.com/open-source/cla/individual |
| 120 | + [4]: https://developers.google.com/open-source/cla/corporate |
0 commit comments