Contributing to Batavia¶
Setting up your development environment¶
The process of setting up a development environment is very similar to the Tutorial: Preparing your Environment for Batavia Development process. The biggest difference is that instead of using the official PyBee repository, you’ll be using your own Github fork.
As with the getting started guide, these instructions will assume that you have Python 3.4.
Start by forking Batavia into your own Github repository; then check out your fork to your own computer into a development directory:
$ mkdir batavia-dev $ cd batavia-dev $ git clone https://github.com/<your github username>/batavia.git
Then create a virtual environment and install Batavia into it:
For Linux, MacOS:$ python3.4 -m venv venv $ . venv/bin/activate $ cd batavia $ pip install -e .
For Windows:> py -3.4 -m venv venv > venv\Scripts\activate > cd batavia > pip install -e .
$ npm install -g npm $ npm install $ npm run build
Raspbian for Raspberry Pi 1 does not come with Python 3.4. (Ubuntu 16.04 for Raspberry Pi is now available, and has new enough packages as described above.) To install Python 3.4, download the source code and then build it:
$ cd /tmp $ wget https://www.python.org/ftp/python/3.4.4/Python-3.4.4.tgz $ tar xvzf Python-3.4.4.tgz $ cd Python-3.4.4/ $ ./configure --prefix=/opt/python3.4 $ make $ sudo make install
Running the test suite¶
You’re now ready to run the test suite! This can be done the immediately-available-but-tiresome way, or the takes-little-effort-but-then-fun way, which is preferred (assuming your Python is configured for Tk; MacOS Python often is not).
For the fun way, you need to install BeeWare’s test-running tool,
Cricket. Follow the installation instructions to install it into your
virtualenv; then, in the
batavia-dev/batavia directory, type:
This launches a test-running GUI, where you can easily and intuitively run all tests or a subset of tests, see the progress of tests (which is quite valuable when running over 10000 tests), and whenever failure is encountered, immediately see the details.
If, for whatever reason, you want to run the tests without Cricket, you can always use a text test runner by typing:
$ python setup.py test
This will take at least several minutes, and can take upwards of 1.5hrs on most modern PCs/laptops. It will also generate around 10000 lines of console output - one line for each test that is executed. Each line will tell you the pass/fail status of each test - e.g.,:
test_abs_not_implemented (tests.builtins.test_abs.AbsTests) ... expected failure test_bool (tests.builtins.test_abs.BuiltinAbsFunctionTests) ... ok
This indicates that tests have passed (
ok), or have failed in an expected
expected failure). These outcomes are what you expect to see.
If you see any tests reported as
then you’ve found a problem. If this happens, at the end of the test run, you’ll
also see a summary of the cause of those problems.
As soon as you see problems, you can stop the tests and start debugging. Cricket has a button for this; with the text test runner, hit Ctrl-C or Cmd-C to quit.
However, this shouldn’t happen - Batavia runs continuous integration to make sure the test suite is always in a passing state. If you do get any failures, errors, or unexpected successes, please check out the troubleshooting section or get in touch, because you may have found a problem.
If you just want to run a single test, or a single group of tests with the text runner, you can provide command-line arguments.
To run a single test, provide the full dotted-path to the test:
$ python setup.py test -s tests.datatypes.test_str.BinaryStrOperationTests.test_add_bool
To run a full test case, do the same, but stop at the test case name:
$ python setup.py test -s tests.datatypes.test_str.BinaryStrOperationTests
Or, to run all the Str datatype tests:
$ python setup.py test -s tests.datatypes.test_str
Or, to run all the datatypes tests:
$ python setup.py test -s tests.datatypes
Running the linter¶
$ npm run lint
If you copied the main Batavia code a while ago, please make sure your forked branch is up to date with the original branch. To do this:
set your upstream remote:
$ git remote add upstream https://github.com/pybee/batavia.git
make sure you have the latest changes from upstream:
$ git fetch upstream
rebase your master branch to upstream before pushing to GitHub and submitting a pull request:
$ git rebase upstream/master