From 819f66e5b550e8881f2a650c0d70bcaa01af8ecb Mon Sep 17 00:00:00 2001 From: igncampa Date: Tue, 13 Nov 2018 16:01:47 -0600 Subject: Contrib guide improv (#946) improved DEVELOP docs --- DEVELOP.rst | 50 +++++++++++++++++++++++++++++++++++++------------- changelog.rst | 2 ++ 2 files changed, 39 insertions(+), 13 deletions(-) diff --git a/DEVELOP.rst b/DEVELOP.rst index 601c3f30..005c9f3f 100644 --- a/DEVELOP.rst +++ b/DEVELOP.rst @@ -6,7 +6,7 @@ GitHub Workflow --------------- If you're interested in contributing to pgcli, first of all my heart felt -thanks. `Fork the project `_ in github. Then +thanks. `Fork the project `_ on github. Then clone your fork into your computer (``git clone ``). Make the 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 @@ -26,16 +26,20 @@ 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. +Check Github's `Understanding the GitHub flow guide +`_ for a more detailed +explanation of this process. + 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. +having to go through the install cycle every time you change the code. It is highly recommended to use virtualenv for development. If you don't know -what a virtualenv is, this `guide `_ +what a virtualenv is, `this guide `_ will help you get started. Create a virtualenv (let's call it pgcli-dev). Activate it: @@ -57,10 +61,10 @@ and install pgcli using pip as follows: 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 +we've linked the pgcli installation with the working copy. Any changes made +to the code are 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. +effects of your changes. Adding PostgreSQL Special (Meta) Commands ----------------------------------------- @@ -123,22 +127,35 @@ in the ``tests`` directory. An example:: pg_test_host = db.example.com pg_test_port = 30000 -The database user has to have -permissions to create and drop test databases. Default user is ``postgres`` -at ``localhost``, without the password (authentication mode trust). - First, install the requirements for testing: :: $ pip install -r requirements-dev.txt -After that, tests can be run with: +Ensure that the database user has permissions to create and drop test databases +by checking your ``pg_hba.conf`` file. The default user should be ``postgres`` +at ``localhost``. Make sure the authentication method is set to ``trust``. If +you made any changes to your ``pg_hba.conf`` make sure to restart the postgres +service for the changes to take effect. + +:: + + # ONLY IF YOU MADE CHANGES TO YOUR pg_hba.conf FILE + $ sudo service postgresql restart + +After that, tests in the ``/pgcli/tests`` directory can be run with: :: - $ cd tests + # on directory /pgcli/tests $ behave + +And on the ``/pgcli`` directory: + +:: + + # on directory /pgcli $ py.test To see stdout/stderr, use the following command: @@ -147,9 +164,16 @@ To see stdout/stderr, use the following command: $ behave --no-capture +Troubleshooting the integration tests +------------------------------------- + +- Make sure postgres instance on localhost is running +- Check your ``pg_hba.conf`` file to verify local connections are enabled +- Check `this issue `_ for relevant information. +- Contact us on `gitter `_ or `file an issue `_. PEP8 checks (lint) ------------------_ +------------------ When you submit a PR, the changeset is checked for pep8 compliance using `pep8radius `_. If you see a build failing because diff --git a/changelog.rst b/changelog.rst index 4abcfc98..50fc631d 100644 --- a/changelog.rst +++ b/changelog.rst @@ -12,6 +12,7 @@ Internal: * Clean up and add behave logging. (Thanks: `Dick Marinus`_) * Require prompt_toolkit>=2.0.6. (Thanks: `Dick Marinus`_) +* Improve development guide (Thanks: `Ignacio Campabadal`_) 2.0.0: @@ -899,3 +900,4 @@ Improvements: .. _`Kenny Do`: https://github.com/kennydo .. _`Max Rothman`: https://github.com/maxrothman .. _`DanEEStar`: https://github.com/DanEEStar +.. _`Ignacio Campabadal`: https://github.com/igncampa -- cgit v1.2.3