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

This commit is contained in:
Dave Page 2022-09-22 13:54:14 +01:00 committed by GitHub
parent ed1184fcf8
commit 9ed3be335e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
5 changed files with 78 additions and 65 deletions

View File

@ -267,8 +267,8 @@ A GitHub project for pgAdmin 4 can be found at the address below:
https://github.com/pgadmin-org/pgadmin4 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 If you wish to discuss pgAdmin 4, or contribute to the project, please use the
pgAdmin Hackers mailing list: pgAdmin Hackers mailing list:

View File

@ -5,7 +5,7 @@
************************** **************************
This document lists a number of standard items that will be checked during the 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`. * 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 current schema/user as appropriate. In general, if there are common or sensible
default values available, put them in the fields for the user. 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.

View File

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

View File

@ -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.

View File

@ -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.