diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..cf3dae4f --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,10 @@ +============ +Contributing +============ + +Thank you for considering to make a contribution. + +Please see the `contribution guide`_ for CrateDB for more information. +Everything in the CrateDB contribution guide applies to this repository. + +.. _contribution guide: https://github.com/crate/crate/blob/master/CONTRIBUTING.rst diff --git a/DEVELOP.rst b/DEVELOP.rst index 7dad071c..a9a87ee3 100644 --- a/DEVELOP.rst +++ b/DEVELOP.rst @@ -1,113 +1,112 @@ -================= -Crash Development -================= +=============== +Developer Guide +=============== -Development Setup -================= +Setup +===== -To get a development environment crash uses `buildout -`_. +This project uses buildout_ to set up the development environment. -Run `bootstrap.py`:: +To start things off, run:: - python bootstrap.py + $ python bootstrap.py -And afterwards run buildout:: +Then, run:: - ./bin/buildout -N + $ ./bin/buildout -N +Then to run your local crash, use:: -Start the ``crash`` shell with:: - - ./bin/crash + $ ./bin/crash Running Tests ============= -The tests are run using the `zope.testrunner -`_:: +The tests are run using the zope.testrunner_:: + + $ ./bin/test - ./bin/test +This will run all tests using the Python interpreter that was used to bootstrap +buildout. -This will run all tests using the python interpreter that was used to -bootstrap buildout. +You can run the tests against multiple Python interpreters with tox_:: -In addition to that it is also possible to run the test case against multiple -python interpreter using `tox `_:: + $ ./bin/tox - ./bin/tox +To do this, you will need ``python2.7``, ``python3.3``, and ``pypy`` on your +``$PATH``. -This required the interpreters `python2.7`, `python3.3` and `pypy` to be -available in `$PATH`. To run against a single interpreter tox can also be -invoked like this:: +To run against a single interpreter, you can also do:: - ./bin/tox -e py33 + $ ./bin/tox -e py33 -Bundling -======== +Standalone Executable +===================== -It is possible to build an executable zip archive, which starts crash -like this: +To build the standalone executable, run:: - ./bin/py devtools/bundle.py crash_standalone + $ ./bin/py devtools/bundle.py crash_standalone -You can then start the generated file like this:: +Run the executable like so:: - ./crash_standalone + $ ./crash_standalone -Preparing a new Release -======================= +Preparing a Release +=================== -Before creating a new Crash distribution, a new version and tag need to be created: +To create a new release, you must: - - Update the ``__version__`` in ``src/crate/crash/__init__.py``. +- Update ``__version__`` in ``src/crate/crash/__init__.py`` - - Add a note for the new version at the ``CHANGES.txt`` file. +- Add a section for the new version in the ``CHANGES.txt`` file - - Commit e.g. using message 'prepare release x.x.x'. +- Commit your changes with a message like "prepare release x.y.z" - - Push to origin +- Push to origin - - Create a tag using the ``create_tag.sh`` script - (run ``./devtools/create_tag.sh``). +- Create a tag by running ``./devtools/create_tag.sh`` -Deployment to PyPi ------------------- +PyPI Deployment +--------------- To create the packages use:: - bin/py setup.py sdist bdist_wheel + $ bin/py setup.py sdist bdist_wheel -and then use `twine `_ to upload the -packages:: +Then, use twine_ to upload the packages:: - twine upload dist/* + $ bin/twine upload dist/* -If twine is not installed locally the regular setup.py upload can also be used, -but does only support plaintext authentication:: +If you want to check the PyPI description before uploading, run:: - bin/py setup.py upload + $ bin/py setup.py check --strict --restructuredtext -Release Crate Standalone -------------------------- +Standalone Deployment +--------------------- -Building and releasing the standalone version is done by a Jenkins_ job. +The standalone executable is built and deployed by a Jenkins_ job. Writing Documentation ===================== -The documentation is maintained under the ``docs`` directory and -written in ReStructuredText_ and processed with Sphinx_. +The docs live under the ``docs`` directory. -Normally the documentation is built by `Read the Docs`_. -However if you work on the documentation you can run sphinx -directly, which can be done by just running ``bin/sphinx``. -The output can then be found in the ``out/html`` directory. +The docs are written written with ReStructuredText_ and processed with Sphinx_. -.. _Jenkins: http://jenkins-ci.org/ +Build the docs by running:: -.. _Sphinx: http://sphinx-doc.org/ + $ bin/sphinx -.. _ReStructuredText: http://docutils.sourceforge.net/rst.html +The output can then be found in the ``out/html`` directory. + +The docs are automatically built from Git by `Read the Docs`_ and there is +nothing special you need to do to get the live docs to update. -.. _`Read the Docs`: http://readthedocs.org +.. _Read the Docs: http://readthedocs.org +.. _buildout: https://pypi.python.org/pypi/zc.buildout +.. _Jenkins: http://jenkins-ci.org/ +.. _ReStructuredText: http://docutils.sourceforge.net/rst.html +.. _Sphinx: http://sphinx-doc.org/ +.. _tox: http://testrun.org/tox/latest/ +.. _twine: https://pypi.python.org/pypi/twine +.. _zope.testrunner: https://pypi.python.org/pypi/zope.testrunner/4.4.1 diff --git a/README.rst b/README.rst index 83f6140b..ad56c11b 100644 --- a/README.rst +++ b/README.rst @@ -1,10 +1,6 @@ -.. image:: https://cdn.crate.io/web/2.0/img/crate-logo_330x72.png - :width: 165px - :height: 36px - :alt: Crate.IO - :target: https://crate.io - -| +===== +Crash +===== .. image:: https://travis-ci.org/crate/crash.svg?branch=master :target: https://travis-ci.org/crate/crash @@ -26,98 +22,93 @@ :target: https://coveralls.io/r/crate/crash?branch=master :alt: Coverage -======== -Overview -======== +| + +Crash is an interactive CrateDB *command line interface* (CLI) SQL shell with autocompletion. + +Screenshot +========== -This is the Crate shell called ``crash``. +.. image:: crash.png + :alt: A screenshot of Crash + +Prerequisites +============= + +Recent versions of Crash require Python (>= 2.7) to run. + +Use Crash 0.16.0 if you're running Python 2.6. Installation ============ -Installing via pip ------------------- +As a Python Package +------------------- + +Crash is available as a pip_ package. -To install crash via `pip `_ use -the following command:: +To install, run:: $ pip install crash -To update use:: +Now, run it:: + + $ crash + +To update, run:: $ pip install -U crash Standalone ---------- -There is also a single file executable that includes all dependencies and can -be run as long as python (>= 2.7) is available on the system. +Crash is also available as a standalone executable that includes all the +necessary dependencies, and can be run as long as Python (>= 2.7) is available. -`Download Crash bundle -`_ +First, download the executable:: -The bundle can then be executed using python:: + $ curl -o crash https://cdn.crate.io/downloads/releases/crash_standalone_latest - python ./crash_standalone_latest +Then, make it executable:: -Or:: + $ chmod +x crash - chmod +x ./crash_standalone_latest - ./crash_standalone_latest +Now, run it:: + $ ./crash -Crash supported Python 2.6 until 0.16. `Use Crash 0.16.0 -`_ if you're -running Python 2.6 +If you would like to run ``crash`` from any directory and without using leading +``./`` you will need to move it to somewhere on your ``$PATH``. Usage ------ +===== -If the package was installed using `pip` the shell can be started by -running the command `crash` in a terminal. +For usage information and options, run:: -For usage information and command line options invoke:: + $ crash --help - crash --help +Contributing +============ -Or consult the `crash documentation 📚 `_. +Crash is primarily maintained by `Crate.io`_, but we welcome community contributions! -Are you a Developer? -==================== +See the `developer docs`_ and the `contribution docs`_ for more information. -You can build Crash on your own with the latest version hosted on GitHub. -To do so, please refer to ``DEVELOP.rst`` for further information. +Help +==== -Help & Contact -============== +Looking for more help? -Do you have any questions? Or suggestions? We would be very happy -to help you. So, feel free to swing by our Community on Slack_. -Or for further information and official contact please -visit `https://crate.io/ `_. +- Read `the Crash documentation`_ +- Check `StackOverflow`_ for common problems +- Chat with us on `Slack`_ +- Get `paid support`_ +.. _contribution docs: CONTRIBUTING.rst +.. _Crate.io: http://crate.io/ +.. _developer docs: DEVELOP.rst +.. _paid support: https://crate.io/pricing/ +.. _pip: https://pypi.python.org/pypi/pip .. _Slack: https://crate.io/docs/support/slackin/ - -License -======= - -Copyright 2013-2014 CRATE Technology GmbH ("Crate") - -Licensed to CRATE Technology GmbH ("Crate") under one or more contributor -license agreements. See the NOTICE file distributed with this work for -additional information regarding copyright ownership. Crate 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. - -However, if you have executed another commercial license agreement -with Crate these terms will supersede the license and you may use the -software solely pursuant to the terms of the relevant commercial agreement. +.. _StackOverflow: https://stackoverflow.com/tags/crate +.. _the Crash documentation: https://crate.io/docs/reference/crash/ diff --git a/buildout.cfg b/buildout.cfg index 91a8af43..b01b85ad 100644 --- a/buildout.cfg +++ b/buildout.cfg @@ -17,6 +17,7 @@ eggs = crash wheel codecov coverage + twine [crate] recipe = hexagonit.recipe.download diff --git a/crash.png b/crash.png new file mode 100644 index 00000000..58ff34f2 Binary files /dev/null and b/crash.png differ diff --git a/versions.cfg b/versions.cfg index 81dff0b0..cef2a7c1 100644 --- a/versions.cfg +++ b/versions.cfg @@ -5,7 +5,7 @@ Babel = 2.2.0 Jinja2 = 2.8 Sphinx = 1.3.6 alabaster = 0.7.7 -appdirs = 1.4.0 +appdirs = 1.4.3 argparse = 1.1 codecov = 1.6.3 collective.recipe.omelette = 0.16 @@ -20,8 +20,9 @@ pytz = 2015.7 requests = 2.9.1 snowballstemmer = 1.2.1 sphinx-rtd-theme = 0.1.9 +twine = 1.8.1 wheel = 0.29.0 -zc.buildout = 2.5.0 +zc.buildout = 2.9.2 zc.customdoctests = 1.0.1 zc.recipe.egg = 2.0.3 zc.recipe.testrunner = 2.0.0