diff --git a/README.md b/README.md index bb4307ae7..00105ae5d 100644 --- a/README.md +++ b/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 do not submit pull requests! +Please submit any changes as Pull Requests against the *master* branch of the +*pgadmin-org/pgadmin4* repository. If you wish to discuss pgAdmin 4, or contribute to the project, please use the pgAdmin Hackers mailing list: diff --git a/docs/en_US/code_review.rst b/docs/en_US/code_review.rst index 226f8ece5..befb86700 100644 --- a/docs/en_US/code_review.rst +++ b/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 - your patch, it's usually easier if it's in a separate patch. Patches containing - multiple new features or unrelated changes are likely to be rejected. +* 1 Pull Request == 1 feature. If you need to fix/update existing + infrastructure in your change, it's usually easier if it's in a separate + 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 - a work in progress, not intended for commit, clearly state that it's a WIP, - and note what does or does not yet work. +* Ensure the change is fully functional, and works! If you wish to send a + work in progress (WIP) change that is not intended for commit, instead of + 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. diff --git a/docs/en_US/contributions.rst b/docs/en_US/contributions.rst index 92eea471a..e91fc105f 100644 --- a/docs/en_US/contributions.rst +++ b/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 diff --git a/docs/en_US/submitting_patches.rst b/docs/en_US/submitting_patches.rst deleted file mode 100644 index 337fa1aaa..000000000 --- a/docs/en_US/submitting_patches.rst +++ /dev/null @@ -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. diff --git a/docs/en_US/submitting_pull_requests.rst b/docs/en_US/submitting_pull_requests.rst new file mode 100644 index 000000000..06b9aa369 --- /dev/null +++ b/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//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 `_ instead; documenting + such tools and workflows is outside the scope of the pgAdmin documentation + however.