From 61fae01fb757a30d494a523b3dc71eb7ffe1487f Mon Sep 17 00:00:00 2001 From: gfr Date: Wed, 6 May 2015 10:36:16 -0400 Subject: [PATCH] DOC: Note on PyTables index issue and additional Contributing refinements. --- doc/source/contributing.rst | 30 ++++++++++++++++++++++-------- doc/source/index.rst.template | 2 +- doc/source/install.rst | 2 +- doc/source/io.rst | 4 ++++ doc/source/whatsnew/v0.16.1.txt | 2 +- 5 files changed, 29 insertions(+), 11 deletions(-) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 7785f5fe3283d..1ece60bf704d6 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -112,8 +112,10 @@ want to clone your fork to your machine: :: This creates the directory `pandas-yourname` and connects your repository to the upstream (main project) *pandas* repository. -You will also need to hook up Travis-CI to your GitHub repository so the suite -is automatically run when a Pull Request is submitted. Instructions are `here +The testing suite will run automatically on Travis-CI once your Pull Request is +submitted. However, if you wish to run the test suite on a branch prior to +submitting the Pull Request, then Travis-CI needs to be hooked up to your +GitHub repository. Instructions are for doing so are `here `_. Creating a Branch @@ -134,6 +136,17 @@ changes in this branch specific to one bug or feature so it is clear what the branch brings to *pandas*. You can have many shiny-new-features and switch in between them using the git checkout command. +To update this branch, you need to retrieve the changes from the master branch:: + + git fetch upstream + git rebase upstream/master + +This will replay your commits on top of the lastest pandas git master. If this +leads to merge conflicts, you must resolve these before submitting your Pull +Request. If you have uncommitted changes, you will need to `stash` them prior +to updating. This will effectively store your changes and they can be reapplied +after updating. + .. _contributing.dev_env: Creating a Development Environment @@ -338,7 +351,7 @@ dependencies. Building the documentation ~~~~~~~~~~~~~~~~~~~~~~~~~~ -So how do you build the docs? Navigate to your local the folder +So how do you build the docs? Navigate to your local the folder ``pandas/doc/`` directory in the console and run:: python make.py html @@ -358,8 +371,9 @@ If you want to do a full clean build, do:: Starting with 0.13.1 you can tell ``make.py`` to compile only a single section of the docs, greatly reducing the turn-around time for checking your changes. -You will be prompted to delete `.rst` files that aren't required, since the -last committed version can always be restored from git. +You will be prompted to delete `.rst` files that aren't required. This is okay +since the prior version can be checked out from git, but make sure to +not commit the file deletions. :: @@ -417,7 +431,7 @@ deprecation warnings where needed. Test-driven Development/Writing Code ------------------------------------ -*Pandas* is serious about `Test-driven Development (TDD) +*Pandas* is serious about testing and strongly encourages individuals to embrace `Test-driven Development (TDD) `_. This development process "relies on the repetition of a very short development cycle: first the developer writes an (initially failing) automated test case that defines a desired @@ -550,8 +564,8 @@ Doing 'git status' again should give something like :: # modified: /relative/path/to/file-you-added.py # -Finally, commit your changes to your local repository with an explanatory message. An informal -commit message format is in effect for the project. Please try to adhere to it. Here are +Finally, commit your changes to your local repository with an explanatory message. *Pandas* +uses a convention for commit message prefixes and layout. Here are some common prefixes along with general guidelines for when to use them: * ENH: Enhancement, new functionality diff --git a/doc/source/index.rst.template b/doc/source/index.rst.template index ee779715bcb95..fb63d0c6d66f1 100644 --- a/doc/source/index.rst.template +++ b/doc/source/index.rst.template @@ -115,6 +115,7 @@ See the package overview for more detail about what's in the library. {%if not single -%} whatsnew install + contributing faq overview 10min @@ -149,7 +150,6 @@ See the package overview for more detail about what's in the library. api {% endif -%} {%if not single -%} - contributing internals release {% endif -%} diff --git a/doc/source/install.rst b/doc/source/install.rst index 0d473522c1c6e..79adab0463588 100644 --- a/doc/source/install.rst +++ b/doc/source/install.rst @@ -243,7 +243,7 @@ Optional Dependencies * `Cython `__: Only necessary to build development version. Version 0.19.1 or higher. * `SciPy `__: miscellaneous statistical functions -* `PyTables `__: necessary for HDF5-based storage. Version 3.0.0 or higher required. +* `PyTables `__: necessary for HDF5-based storage. Version 3.0.0 or higher required, Version 3.2.0 or higher highly recommended. * `SQLAlchemy `__: for SQL database support. Version 0.8.1 or higher recommended. * `matplotlib `__: for plotting * `statsmodels `__ diff --git a/doc/source/io.rst b/doc/source/io.rst index 52c7402594c60..73a2f2f1d3531 100644 --- a/doc/source/io.rst +++ b/doc/source/io.rst @@ -2364,6 +2364,10 @@ for some advanced strategies As of version 0.15.0, pandas requires ``PyTables`` >= 3.0.0. Stores written with prior versions of pandas / ``PyTables`` >= 2.3 are fully compatible (this was the previous minimum ``PyTables`` required version). +.. warning:: + + There is a ``PyTables`` indexing bug which may appear when querying stores using an index. If you see a subset of results being returned, upgrade to ``PyTables`` >= 3.2. Stores created previously will need to be rewritten using the updated version. + .. ipython:: python :suppress: :okexcept: diff --git a/doc/source/whatsnew/v0.16.1.txt b/doc/source/whatsnew/v0.16.1.txt index 5c67f910c77fa..1c2dbaa48832b 100755 --- a/doc/source/whatsnew/v0.16.1.txt +++ b/doc/source/whatsnew/v0.16.1.txt @@ -297,7 +297,7 @@ Bug Fixes - +- Bug in PyTables queries that did not return proper results using the index (:issue:`8265`, :issue:`9676`)