From f3ce7999163e9f082898340fe4acf7d750b18f90 Mon Sep 17 00:00:00 2001 From: dev-hari-prasad Date: Mon, 15 Jun 2026 22:15:19 +0530 Subject: [PATCH 1/4] docs: add basic starter contributing guide Add a CONTRIBUTING.md file to document the contribution workflow for pgAdmin 4. Includes: - Getting started instructions - Issue reporting guidelines - Development workflow and coding practices - Pull request requirements - Development environment setup - Database migration guidance - Security reporting process - Community support resources This provides a single reference for new and existing contributors. --- CONTRIBUTING.md | 320 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 320 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000000..c6fb026a0e5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,320 @@ +# Contributing to pgAdmin 4 + +Thank you for your interest in contributing to pgAdmin 4. + +## Contents + +- Getting Started +- Reporting Issues +- Making Changes +- Pull Requests +- Development Setup +- Database Migrations +- Security Issues +- Community and Support +- License + +## Getting Started + +Before starting work, please review the project documentation and familiarize yourself with the architecture and development workflow. + +If you are new to the codebase, consider starting with smaller bug fixes or documentation improvements before working on larger changes. + +## Reporting Issues + +When reporting a bug: + +- Search existing issues first. +- If a similar issue exists, add any additional information or context you have. Do not create a duplicate issue. +- Provide clear steps to reproduce the issue. +- Include relevant environment and version information. +- Attach screenshots, logs, or error messages when appropriate. + +For feature requests, describe the problem being solved and the expected behavior. + + +## Making Changes + +When working on a contribution: + +- Keep changes focused and easy to review. +- Follow existing coding patterns and conventions. +- Avoid unrelated refactoring and changes in the same commit. +- Keep commit messages clear and descriptive. +- Update tests or documentation when necessary. + +## Pull Requests + +Before opening a pull request: + +- Ensure your changes build successfully. +- Test your changes locally. +- Review your code before submission. +- Update your branch with the latest changes from `master` upstream when appropriate. + +When opening a pull request: + +- Clearly describe the change. +- Explain the reason for the change. +- Include screenshots or recordings for UI-related changes when applicable. +- Submit any changes as Pull Requests against the `master` branch of the `pgadmin-org/pgadmin4` repository. + +## Development Setup + +### Prerequisites + +1. Install Node.js 20 and above (https://nodejs.org/en/download) +2. yarn (https://yarnpkg.com/getting-started/install) +3. Python 3.9 and above (https://www.python.org/downloads/) +4. PostgreSQL server (https://www.postgresql.org/download) + +Start by enabling Corepack, if it isn't already; this will add the yarn binary to your PATH: + +```bash +corepack enable +``` + +### Building Web Assets + +pgAdmin is dependent on a number of third-party JavaScript libraries. These, along with its own JavaScript code, CSS code and images must be compiled into a "bundle" which is transferred to the browser for execution and rendering. This is far more efficient than simply requesting each asset as it is needed by the client. + +To create the bundle, you will need the 'yarn' package management tool to be installed. Then, you can run the following commands on a *nix system to download the required packages and build the bundle: + +```bash +$ cd $PGADMIN4_SRC +$ make install-node +$ make bundle +``` + +On Windows systems (where "make" is not available), the following commands can be used: + +``` +C:\> cd $PGADMIN4_SRC\web +C:\$PGADMIN4_SRC\web> yarn install +C:\$PGADMIN4_SRC\web> yarn run bundle +``` + +### Python Environment + +In order to run the Python code, a suitable runtime environment is required. Python version 3.9 and later are currently supported. It is recommended that a Python virtual environment is set up for this purpose, rather than using the system Python environment. On Linux and Mac systems, the process is fairly simple - adapt as required for your distribution: + +1. Create a virtual environment in an appropriate directory. The last argument is the name of the environment; that can be changed as desired: + + ```bash + $ python3 -m venv venv + ``` + +2. Now activate the virtual environment: + + ```bash + $ source venv/bin/activate + ``` + + On Windows: + + ```bash + venv\Scripts\activate + ``` + +3. Some of the components used by pgAdmin require a very recent version of *pip*, so update that to the latest: + + ```bash + (venv) $ pip install --upgrade pip + ``` + +4. Ensure that a PostgreSQL installation's bin/ directory is in the path (so pg_config can be found for building psycopg3), and install the required packages: + + ```bash + (venv) $ PATH=$PATH:/usr/local/pgsql/bin pip install -r $PGADMIN4_SRC/requirements.txt + ``` + + If you are planning to run the regression tests, you also need to install additional requirements from `web/regression/requirements.txt`: + + ```bash + (venv) $ pip install -r $PGADMIN4_SRC/web/regression/requirements.txt + ``` + +### Configuration + +Create a local configuration file for pgAdmin. Edit `$PGADMIN4_SRC/web/config_local.py` and add any desired configuration options (use the `config.py` file as a reference - any settings duplicated in `config_local.py` will override those in `config.py`). A typical development configuration may look like: + +```python +import os +import logging + +# Change pgAdmin data directory +DATA_DIR = '/Users/myuser/.pgadmin_dev' + +# Change pgAdmin server and port +DEFAULT_SERVER = '127.0.0.1' +DEFAULT_SERVER_PORT = 5051 + +# Switch between server and desktop mode +SERVER_MODE = True + +# Change pgAdmin config DB path in case an external DB is used. +CONFIG_DATABASE_URI="postgresql://postgres:postgres@localhost:5436/pgadmin" + +# Set up SMTP +MAIL_SERVER = 'smtp.gmail.com' +MAIL_PORT = 465 +MAIL_USE_SSL = True +MAIL_USERNAME = 'user@gmail.com' +MAIL_PASSWORD = 'xxxxxxxxxx' + +# Change log level +CONSOLE_LOG_LEVEL = logging.INFO +FILE_LOG_LEVEL = logging.INFO + +# Use a different config DB for each server mode. +if SERVER_MODE == False: + SQLITE_PATH = os.path.join( + DATA_DIR, + 'pgadmin4-desktop.db' + ) +else: + SQLITE_PATH = os.path.join( + DATA_DIR, + 'pgadmin4-server.db' + ) +``` + +This configuration allows easy switching between server and desktop modes for testing. + +### Running pgAdmin + +The initial setup of the configuration database is interactive in server mode, and non-interactive in desktop mode. You can run it either by running: + +```bash +(venv) $ python3 $PGADMIN4_SRC/web/setup.py +``` + +or by starting pgAdmin 4: + +```bash +(venv) $ python3 $PGADMIN4_SRC/web/pgAdmin4.py +``` + +Whilst it is possible to automatically run setup in desktop mode by running the runtime, that will not work in server mode as the runtime doesn't allow command line interaction with the setup program. + +At this point you will be able to run pgAdmin 4 from the command line in either server or desktop mode, and access it from a web browser using the URL shown in the terminal once pgAdmin has started up. + +Setup of an environment on Windows is somewhat more complicated unfortunately, please see `pkg/win32/README.md` for complete details. + +### Building the documentation + +In order to build the docs, an additional Python package is required in the virtual environment. This can be installed with the pip package manager: + +```bash +$ source venv/bin/activate +(venv) $ pip install Sphinx +(venv) $ pip install sphinxcontrib-youtube +``` + +The docs can then be built using the Makefile in `$PGADMIN4_SRC`, e.g. + +```bash +(venv) $ make docs +``` + +The output can be found in `$PGADMIN4_SRC/docs/en_US/_build/html/index.html` + +### Runtime Development + +For Electron runtime development: + +1. Navigate to the `runtime` directory. +2. Install dependencies: + +```bash +yarn install +``` + +3. Copy: + +```text +dev_config.json.in +``` + +to: + +```text +dev_config.json +``` + +4. Update the paths to your Python executable and `pgAdmin4.py`. + +Start the runtime: + +```bash +yarn run start +``` + +### Building packages + +Most packages can be built using the Makefile in `$PGADMIN4_SRC`, provided all the setup and configuration above has been completed. + +To build a source tarball: + +```bash +(venv) $ make src +``` + +To build a PIP Wheel, activate either a Python 3 virtual environment, configured with all the required packages, and then run: + +```bash +(venv) $ make pip +``` + +To build the macOS AppBundle, please see `pkg/mac/README.md`. + +To build the Windows installer, please see `pkg/win32/README.md`. + +## Database Migrations + +In order to make changes to the SQLite DB, navigate to the 'web' directory: + +```bash +(venv) $ cd $PGADMIN4_SRC/web +``` + +Create a migration file with the following command: + +```bash +(venv) $ FLASK_APP=pgAdmin4.py flask db revision +``` + +This will create a file in `$PGADMIN4_SRC/web/migrations/versions/`. Add any changes to the `upgrade` function. + +When making schema changes, update the `SCHEMA_VERSION` value in: + +```text +web/pgadmin/model/__init__.py +``` + +There is no need to increment the `SETTINGS_SCHEMA_VERSION`. + +## Security Issues + +**Do not report security vulnerabilities through GitHub issues.** + +Potential security issues should be reported to: +`security@pgadmin.org`. + +Note that this **address should only be used for reporting security issues** that you believe you've found in the design or code of pgAdmin, pgAgent, and the pgAdmin website. It **should not be used to ask security questions**. + +If you are unsure whether an issue is a security vulnerability, please lean on the side of caution and report it to the above address. The pgAdmin team will review the report and respond as appropriate. + +## Community and Support + +For development discussions, use: + +`pgadmin-hackers@postgresql.org` + +For support options, visit the [pgAdmin support page](https://www.pgadmin.org/support/). + +Use the GitHub issue tracker for reporting bugs and requesting features, but please follow the guidelines outlined in the "Reporting Issues" section above. + +## License + +By contributing to pgAdmin 4, you agree that your contributions will be licensed under the project's existing and future license terms. \ No newline at end of file From 26e9dee929989e90404eb4850d74cbf9eb49c37b Mon Sep 17 00:00:00 2001 From: dev-hari-prasad Date: Mon, 15 Jun 2026 22:42:16 +0530 Subject: [PATCH 2/4] add language tag on the opening fence of the Windows command block --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c6fb026a0e5..a964f14f447 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -88,7 +88,7 @@ $ make bundle On Windows systems (where "make" is not available), the following commands can be used: -``` +```bat C:\> cd $PGADMIN4_SRC\web C:\$PGADMIN4_SRC\web> yarn install C:\$PGADMIN4_SRC\web> yarn run bundle From e8c354268a54bf7d825d49af773d6685a482da02 Mon Sep 17 00:00:00 2001 From: dev-hari-prasad Date: Tue, 16 Jun 2026 11:56:42 +0530 Subject: [PATCH 3/4] =?UTF-8?q?Add=20architecture=20overview,=20define?= =?UTF-8?q?=E2=80=AF$PGADMIN4=5FSRC,=20and=20link=20GitHub=20URLs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CONTRIBUTING.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a964f14f447..d57bb4a3af9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,6 +18,12 @@ Thank you for your interest in contributing to pgAdmin 4. Before starting work, please review the project documentation and familiarize yourself with the architecture and development workflow. +### Architecture + +pgAdmin 4 is written as a web application with Python (Flask) on the server side and ReactJS, HTML5 with CSS for the client side processing and UI. + +Although developed using web technologies, pgAdmin 4 can be deployed either on a web server using a browser, or standalone on a workstation. The [runtime/](file:///d:/t3%20code/pgadmin4/runtime) subdirectory contains an Electron-based runtime application intended to allow this, which will fork a Python server process and display the UI. + If you are new to the codebase, consider starting with smaller bug fixes or documentation improvements before working on larger changes. ## Reporting Issues @@ -57,10 +63,12 @@ When opening a pull request: - Clearly describe the change. - Explain the reason for the change. - Include screenshots or recordings for UI-related changes when applicable. -- Submit any changes as Pull Requests against the `master` branch of the `pgadmin-org/pgadmin4` repository. +- Submit any changes as Pull Requests against the `master` branch of the [pgadmin-org/pgadmin4](https://github.com/pgadmin-org/pgadmin4) repository. ## Development Setup +In the following documentation and examples, `$PGADMIN4_SRC` is used to denote the top-level directory of your copy of the pgAdmin source tree (either from a tarball or a git checkout). + ### Prerequisites 1. Install Node.js 20 and above (https://nodejs.org/en/download) @@ -313,7 +321,7 @@ For development discussions, use: For support options, visit the [pgAdmin support page](https://www.pgadmin.org/support/). -Use the GitHub issue tracker for reporting bugs and requesting features, but please follow the guidelines outlined in the "Reporting Issues" section above. +Use the [GitHub issue tracker](https://github.com/pgadmin-org/pgadmin4/issues) for reporting bugs and requesting features, but please follow the guidelines outlined in the "Reporting Issues" section above. ## License From 5c299ff8390973ddce089346e7d8562144f6e0c6 Mon Sep 17 00:00:00 2001 From: dev-hari-prasad Date: Sat, 20 Jun 2026 12:37:33 +0530 Subject: [PATCH 4/4] docs: update contribution guidance Clarify contributor workflow, fix the runtime link, and add references to existing contributor docs. --- CONTRIBUTING.md | 19 ++++++++++++++++--- 1 file changed, 16 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d57bb4a3af9..c7a22067b59 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,6 +8,7 @@ Thank you for your interest in contributing to pgAdmin 4. - Reporting Issues - Making Changes - Pull Requests +- AI-assisted Contributions - Development Setup - Database Migrations - Security Issues @@ -22,10 +23,14 @@ Before starting work, please review the project documentation and familiarize yo pgAdmin 4 is written as a web application with Python (Flask) on the server side and ReactJS, HTML5 with CSS for the client side processing and UI. -Although developed using web technologies, pgAdmin 4 can be deployed either on a web server using a browser, or standalone on a workstation. The [runtime/](file:///d:/t3%20code/pgadmin4/runtime) subdirectory contains an Electron-based runtime application intended to allow this, which will fork a Python server process and display the UI. +Although developed using web technologies, pgAdmin 4 can be deployed either on a web server using a browser, or standalone on a workstation. The [runtime/](runtime/) subdirectory contains an Electron-based runtime application intended to allow this, which will fork a Python server process and display the UI. + +For a fuller introduction to the codebase, see the [code overview](docs/en_US/code_overview.rst). If you are new to the codebase, consider starting with smaller bug fixes or documentation improvements before working on larger changes. +The Sphinx documentation also includes contributor guidance for [coding standards](docs/en_US/coding_standards.rst), [submitting pull requests](docs/en_US/submitting_pull_requests.rst), [code review](docs/en_US/code_review.rst), and [translations](docs/en_US/translations.rst). + ## Reporting Issues When reporting a bug: @@ -44,7 +49,7 @@ For feature requests, describe the problem being solved and the expected behavio When working on a contribution: - Keep changes focused and easy to review. -- Follow existing coding patterns and conventions. +- Follow existing coding patterns and conventions, including the [coding standards](docs/en_US/coding_standards.rst). - Avoid unrelated refactoring and changes in the same commit. - Keep commit messages clear and descriptive. - Update tests or documentation when necessary. @@ -65,6 +70,14 @@ When opening a pull request: - Include screenshots or recordings for UI-related changes when applicable. - Submit any changes as Pull Requests against the `master` branch of the [pgadmin-org/pgadmin4](https://github.com/pgadmin-org/pgadmin4) repository. +Use a clear pull request title that describes the change. Short prefixes such as `feat:`, `fix:`, `docs:`, `test:`, `refactor:`, and `chore:` are useful when they match the change being made. Branch names are contributor-local and do not need to follow a project-specific naming convention. + +For more detail, see the [pull request submission guide](docs/en_US/submitting_pull_requests.rst) and [code review guide](docs/en_US/code_review.rst). + +## AI-assisted Contributions + +Contributors are responsible for understanding, testing, and standing behind everything they submit, whether or not AI tools were used. Please do not open large numbers of auto-generated issues or pull requests without first discussing that work with the maintainers. + ## Development Setup In the following documentation and examples, `$PGADMIN4_SRC` is used to denote the top-level directory of your copy of the pgAdmin source tree (either from a tarball or a git checkout). @@ -325,4 +338,4 @@ Use the [GitHub issue tracker](https://github.com/pgadmin-org/pgadmin4/issues) f ## License -By contributing to pgAdmin 4, you agree that your contributions will be licensed under the project's existing and future license terms. \ No newline at end of file +By contributing to pgAdmin 4, you agree that your contributions will be licensed under the project's existing and future license terms.