From 1afc6eeec925fbccea06a1b979ea5dcf6f36ef7f Mon Sep 17 00:00:00 2001 From: Amjith Ramanujam Date: Thu, 18 Dec 2014 22:32:47 -0800 Subject: [PATCH] Update README and add DEVELOP file. --- DEVELOP.rst | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.rst | 33 +++++++++++++++++++----------- 2 files changed, 79 insertions(+), 12 deletions(-) create mode 100644 DEVELOP.rst diff --git a/DEVELOP.rst b/DEVELOP.rst new file mode 100644 index 00000000..85280a37 --- /dev/null +++ b/DEVELOP.rst @@ -0,0 +1,58 @@ +Development Guide +----------------- +This is a guide for developers who would like to contribute to this project. + +Git Workflow +------------ + +If you're interested in contributing to pgcli, first of all my heart felt +thanks. Please `fork the project `_ in github. +Then clone your fork into your computer (``git clone ``). +Make the necessary changes and create the commits in your local machine. Then +push those changes to your fork. Then click on the pull request icon on github +and create a new pull request. Add a description about the change and send it +along. I promise to review you in a reasonable window of time and get back to +you. + +In order to keep your fork up to date with any changes from mainline, add a new +git remote to your local copy called 'upstream' and point it to the main pgcli +repo. + +.. :: + + $ git remote add upstream git@github.com:amjith/pgcli.git + +Once the 'upstream' end point is added you can then periodically do a ``git +pull upstream master`` to update your local copy and then do a ``git push +origin master`` to keep your own fork up to date. + +Local Setup +----------- + +The installation instructions in the README file are intended for users of +pgcli. If you're developing pgcli, you'll need to install it in a slightly +different way so you can see the effects of your changes right away without +having to go through the install cycle everytime you change the code. + +It is highly recommended to use virtualenv for development. If you don't know +what a virtualenv is, this `guide `_ +will help you get started. + +Create a virtualenv (let's call it pgcli-dev). Once the virtualenv is activated +`cd` into the local clone of pgcli folder and install pgcli using pip as +follows: + +.. :: + + $ pip install --editable . + + or + + $ pip install -e . + +This will install the necessary dependencies as well as install pgcli from the +working folder into the virtualenv. By installing it using `pip install -e` +we've linked the pgcli installation with the working copy. So any changes made +to the code is immediately available in the installed version of pgcli. This +makes it easy to change something in the code, launch pgcli and check the +effects of your change. diff --git a/README.rst b/README.rst index 0af03020..436849bf 100644 --- a/README.rst +++ b/README.rst @@ -15,7 +15,8 @@ If you already know how to install python pacakges, then you can simply do: $ pip install pgcli -If you don't know how to install python pacakges, please check the `detailed instructions`__. +If you don't know how to install python pacakges, please check the +`detailed instructions`__. __ https://github.com/amjith/pgcli#detailed-installation-instructions @@ -46,7 +47,8 @@ The `pgcli` is written using prompt_toolkit_. * Auto-completion as you type for SQL keywords as well as tables and columns in the database. * Syntax highlighting using Pygments. -* Smart-completion (enabled by default) will suggest context-sensitive completion. +* Smart-completion (enabled by default) will suggest context-sensitive + completion. - `SELECT * FROM ` will only show table names. - `SELECT * FROM users WHERE ` will only show column names. @@ -105,7 +107,8 @@ If it does then install pgcli using the pip command as follows: $ sudo pip install pgcli -If it doesn't exist, use your linux package manager to install `pip`. This might look something like: +If it doesn't exist, use your linux package manager to install `pip`. This +might look something like: :: @@ -126,15 +129,21 @@ Thanks: ======= A special thanks to `Jonathan Slenders `_ for -creating `Python Prompt Toolkit `_, which is quite -literally the backbone library, that made this app possible. Jonathan has also -provided valuable feedback and support during the development of this app. +creating `Python Prompt Toolkit `_, +which is quite literally the backbone library, that made this app possible. +Jonathan has also provided valuable feedback and support during the development +of this app. -This app includes the awesome `tabulate `_ library -for printing the output of tables. The reason for vendoring this library rather than -listing it as a dependency in setup.py, is because I had to make a change to the table -format which is merged back into the original repo, but not yet released inPyPI. +This app includes the awesome `tabulate `_ +library for printing the output of tables. The reason for vendoring this +library rather than listing it as a dependency in setup.py, is because I had to +make a change to the table format which is merged back into the original repo, +but not yet released inPyPI. -`Click `_ is used for command line option parsing and printing error messages. +`Click `_ is used for command line option parsing +and printing error messages. -Thanks to `psycopg `_ for providing a rock solid interface to Postgres dataabase. +Thanks to `psycopg `_ for providing a rock solid +interface to Postgres dataabase. + +Thanks to all the beta testers and contributors for your time and patience. :)