Adding upstream version 4.0.1.upstream/4.0.1

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 220 insertions, 0 deletions

diff --git a/DEVELOP.rst b/DEVELOP.rst
new file mode 100644
index 0000000..aed2cf8
--- /dev/null
+++ b/DEVELOP.rst
@@ -0,0 +1,220 @@
+Development Guide
+-----------------
+This is a guide for developers who would like to contribute to this project.
+
+GitHub Workflow
+---------------
+
+If you're interested in contributing to pgcli, first of all my heart felt
+thanks. `Fork the project <https://github.com/dbcli/pgcli>`_ on github.  Then
+clone your fork into your computer (``git clone <url-for-your-fork>``).  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
+a new pull request. Add a description about the change and send it along. I
+promise to review the pull request 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:dbcli/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.
+
+Check Github's `Understanding the GitHub flow guide
+<https://guides.github.com/introduction/flow/>`_ 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 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 <http://docs.python-guide.org/en/latest/dev/virtualenvs/#virtual-environments>`_
+will help you get started.
+
+Create a virtualenv (let's call it pgcli-dev). Activate it:
+
+::
+
+    source ./pgcli-dev/bin/activate
+
+    or
+
+    .\pgcli-dev\scripts\activate (for Windows)
+
+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. 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 changes.
+
+Adding PostgreSQL Special (Meta) Commands
+-----------------------------------------
+
+If you want to work on adding new meta-commands (such as `\dp`, `\ds`, `dy`),
+you need to contribute to `pgspecial <https://github.com/dbcli/pgspecial/>`_
+project.
+
+Visual Studio Code Debugging
+-----------------------------
+To set up Visual Studio Code to debug pgcli requires a launch.json file.
+
+Within the project, create a file: .vscode\\launch.json like below.
+
+::
+
+    {
+        // Use IntelliSense to learn about possible attributes.
+        // Hover to view descriptions of existing attributes.
+        // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+        "version": "0.2.0",
+        "configurations": [
+            {
+                "name": "Python: Module",
+                "type": "python",
+                "request": "launch",
+                "module": "pgcli.main",
+                "justMyCode": false,
+                "console": "externalTerminal",
+                "env": {
+                    "PGUSER": "postgres",
+                    "PGPASS": "password",
+                    "PGHOST": "localhost",
+                    "PGPORT": "5432"
+                }
+            }
+        ]
+    }
+
+Building RPM and DEB packages
+-----------------------------
+
+You will need Vagrant 1.7.2 or higher. In the project root there is a
+Vagrantfile that is setup to do multi-vm provisioning. If you're setting things
+up for the first time, then do:
+
+::
+
+    $ version=x.y.z vagrant up debian
+    $ version=x.y.z vagrant up centos
+
+If you already have those VMs setup and you're merely creating a new version of
+DEB or RPM package, then you can do:
+
+::
+
+    $ version=x.y.z vagrant provision
+
+That will create a .deb file and a .rpm file.
+
+The deb package can be installed as follows:
+
+::
+
+    $ sudo dpkg -i pgcli*.deb   # if dependencies are available.
+
+    or
+
+    $ sudo apt-get install -f pgcli*.deb  # if dependencies are not available.
+
+
+The rpm package can be installed as follows:
+
+::
+
+    $ sudo yum install pgcli*.rpm
+
+Running the integration tests
+-----------------------------
+
+Integration tests use `behave package <https://behave.readthedocs.io/>`_ and
+pytest.
+Configuration settings for this package are provided via a ``behave.ini`` file
+in the ``tests`` directory.  An example::
+
+    [behave]
+    stderr_capture = false
+
+    [behave.userdata]
+    pg_test_user = dbuser
+    pg_test_host = db.example.com
+    pg_test_port = 30000
+
+First, install the requirements for testing:
+
+::
+    $ pip install -U pip setuptools 
+    $ pip install --no-cache-dir ".[sshtunnel]" 
+    $ pip install -r requirements-dev.txt 
+
+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:
+(Note that these ``behave`` tests do not currently work when developing on Windows due to pexpect incompatibility.)
+
+::
+
+    # on directory /pgcli/tests
+    $ behave
+
+And on the ``/pgcli`` directory:
+
+::
+
+    # on directory /pgcli
+    $ py.test
+
+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 <https://github.com/dbcli/pgcli/issues/945>`_ for relevant information.
+- `File an issue <https://github.com/dbcli/pgcli/issues/new>`_.
+
+Coding Style
+------------
+
+``pgcli`` uses `black <https://github.com/ambv/black>`_ to format the source code. Make sure to install black.
+
+Releases
+--------
+
+If you're the person responsible for releasing `pgcli`, `this guide <https://github.com/dbcli/pgcli/blob/main/RELEASES.md>`_ is for you.