Update docs to replace use of patches with Pull Requests. (#5349)

README.md

@@ -267,8 +267,8 @@ A GitHub project for pgAdmin 4 can be found at the address below:
 
 https://github.com/pgadmin-org/pgadmin4
 
-**NOTE:** The repository on GitHub is a clone of the main project repository.
+Please submit any changes as Pull Requests against the *master* branch of the
-Please do not submit pull requests!
+*pgadmin-org/pgadmin4* repository.
 
 If you wish to discuss pgAdmin 4, or contribute to the project, please use the
 pgAdmin Hackers mailing list:

docs/en_US/code_review.rst

@@ -5,7 +5,7 @@
 **************************
 
 This document lists a number of standard items that will be checked during the
-review process for any patches submitted for inclusion in pgAdmin.
+review process for any changes submitted for inclusion in pgAdmin.
 
 * Ensure all code follows the pgAdmin :doc:`coding_standards`.
 
@@ -52,10 +52,13 @@ review process for any patches submitted for inclusion in pgAdmin.
   current schema/user as appropriate. In general, if there are common or sensible
   default values available, put them in the fields for the user.
 
-* 1 patch == 1 feature. If you need to fix/update existing infrastructure in
+* 1 Pull Request == 1 feature. If you need to fix/update existing
-  your patch, it's usually easier if it's in a separate patch. Patches containing
+  infrastructure in your change, it's usually easier if it's in a separate
-  multiple new features or unrelated changes are likely to be rejected.
+  Pull Request. Pull Requests containing multiple new features or unrelated
+  changes are likely to be rejected.
 
-* Ensure the patch is fully functional, and works! If a patch is being sent as
+* Ensure the change is fully functional, and works! If you wish to send a
-  a work in progress, not intended for commit, clearly state that it's a WIP,
+  work in progress (WIP) change that is not intended for commit, instead of
-  and note what does or does not yet work.
+  submitting a Pull Request, send either as a link to a repository fork or a
+  patch to the pgadmin-hackers@postgresql.org mailing list, clearly stating
+  that it's a WIP, and noting what does or does not yet work.

docs/en_US/contributions.rst

@@ -15,7 +15,7 @@ development process used to develop, improve, and maintain the pgAdmin client.
 
 .. toctree::
    
-   submitting_patches
+   submitting_pull_requests
    code_overview
    coding_standards
    code_snippets

docs/en_US/submitting_patches.rst

@@ -1,55 +0,0 @@
-.. _submitting_patches:
-
-***************************
-`Submitting Patches`:index:
-***************************
-
-Before developing a patch for pgAdmin you should always contact the developers 
-on the mailing list pgadmin-hackers@postgresql.org to discuss your 
-plans. This ensures that others know if you're fixing a bug and can then avoid
-duplicating your work, and in the case of large patches, gives the community
-the chance to discuss and refine your ideas before investing too much time 
-writing code that may later be rejected.
-
-You should always develop patches against a checkout of the source code from the
-GIT source code repository, and not a release tarball. This ensures that you're 
-working with the latest code on the branch and makes it easier to generate
-patches correctly. You can checkout the source code with a command like:
-
-.. code-block:: bash
-
-    $ git clone https://github.com/pgadmin-org/pgadmin4.git
-    
-Once you've made the changes you wish to make, commit them to a private 
-development branch in your local repository. Then create a patch containing the
-changes in your development branch against the upstream branch on which your 
-work is based. For example, if your current branch contains your changes, you
-might run:
-
-.. code-block:: bash
-
-    $ git diff origin/master > my_cool_feature.diff
-
-to create a patch between your development branch and the public master branch.
-
-You can also create patches directly from the development tree, for example:
-
-.. code-block:: bash
-
-    $ git diff > my_cool_feature.diff
-
-If you are adding new files, you may need to stage them for commit, and then
-create your patch against the staging area. If any of the files are binary,
-for example, images, you will need to use the *--binary* option:
-
-.. code-block:: bash
-
-    $ git add file1.py file2.py images/image1.png [...]
-    $ git diff --cached --binary > my_cool_feature.diff
-
-Once you have your patch, check it thoroughly to ensure it meets the pgAdmin
-:doc:`coding_standards`, and review it against the :doc:`code_review` to minimise
-the chances of it being rejected. Once you're happy with your work, mail it
-as an attachment to the mailing list pgadmin-hackers@postgresql.org.
-Please ensure you include a full description of what the patch does,
-as well as the rationale for any important design decisions.

docs/en_US/submitting_pull_requests.rst

@@ -0,0 +1,65 @@
+.. _submitting_pull_requests:
+
+*********************************
+`Submitting Pull Requests`:index:
+*********************************
+
+Before developing a feature or bug fix for pgAdmin you should always contact
+the developers on the mailing list pgadmin-hackers@postgresql.org to discuss
+your plans. This ensures that others know what you are doing and can then
+avoid duplicating your work, and in the case of large changes, gives the
+community the chance to discuss and refine your ideas before investing too
+much time writing code that may later be rejected.
+
+You should always develop changes against a checkout of the source code from
+the GIT source code repository, and not a release tarball. This ensures that
+you're working with the latest code on the branch and makes it easier to
+generate Pull Requests correctly.
+
+As of September 2022, the pgAdmin source repository can found at
+https://github.com/pgadmin-org/pgadmin4. A typical workflow for a relatively
+simple change might look as follows:
+
+1. Visit the pgAdmin 4 project on GitHub, and click the *Fork* button to create
+   your own development repository in your GitHub account.
+
+2.  Checkout a local copy of the source code with a command like:
+
+   .. code-block:: bash
+
+      $ git clone https://github.com/<your GitHub username>/pgadmin4.git
+
+3. Develop and test your change in your local development environment.
+
+4. Review your changes and check them thoroughly to ensure they meet the
+   pgAdmin :doc:`coding_standards`, and review them against the
+   :doc:`code_review` to minimise the chances of them being rejected.
+
+5. Once you're happy with your change, commit it with a suitable message.
+   Include a one-line summary at the top, and if appropriate, further
+   paragraphs following a blank line after the summary.
+
+6. Push your changes to your fork of the repository.
+
+7. Back in GitHub, create a new Pull Request against the *pgadmin-org/pgadmin4*
+   *master* branch.
+
+   .. note::
+      Each Pull Request should encompass a single bug fix or feature as a single
+      commit. If necessary, you should squash multiple commits for larger changes
+      or features into a single commit before submitting.
+
+8. Your Pull Request will be reviewed by one or more members of the development
+   team and either accepted or sent back with requested changes. In some cases
+   it may be rejected if the change is not considered appropriate - this is
+   why it's important to discuss your work with the team before spending any
+   significant time on it.
+
+For more complex changes, you may wish to use a *Feature Branch* in your fork
+of the pgAdmin repository, and use that to create the Pull Request.
+
+.. note::
+   This is a simple example of a workflow. You may choose to use other
+   tools such as the `GitHub CLI <https://cli.github.com>`_ instead; documenting
+   such tools and workflows is outside the scope of the pgAdmin documentation
+   however.