Skip to content

Contributing

This guide provides instructions for developers who want to contribute to the pgEdge AI DBA Workbench project. The guide covers setting up a development environment, building and testing the project, and submitting contributions.

Prerequisites

Before starting development, install the following tools:

  • Go 1.24 or later for building server-side components.
  • Node.js 18 or later for building the web client.
  • PostgreSQL 14 or later for running tests.
  • Git for version control.
  • Make for build automation.

Install the Go linter with the following command:

go install \
  github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Add the Go bin directory to your PATH:

# Add to your ~/.bashrc, ~/.zshrc, or ~/.zprofile
export PATH="$PATH:$(go env GOPATH)/bin"

Getting Started

Clone the repository from GitHub:

git clone \
  https://github.com/pgEdge/ai-dba-workbench.git
cd ai-dba-workbench

Building

Build all components from the top-level directory:

make all

The build process compiles all Go binaries and places them in the bin/ directory. Build individual components by changing to the component directory:

cd collector && make build
cd server && make build

Build the web client with the following commands:

cd client && npm install && npm run build

Testing

The project uses comprehensive unit tests for all components. Run all tests from the top-level directory:

make test-all

The test-all target runs tests, coverage analysis, and linting for all Go components. Run individual test targets as needed:

# Run tests only
make test

# Run coverage analysis
make coverage

# Run linting
make lint

Test Database

Tests that require a database create a temporary database with a timestamp in the name. Set the connection string using an environment variable:

export TEST_AI_WORKBENCH_SERVER=\
  "postgres://user:pass@localhost/postgres"

The test database drops automatically after tests complete. Set the keep flag to preserve the database for inspection:

export TEST_AI_WORKBENCH_KEEP_DB=1

Component-Specific Tests

Run tests for a specific component by changing to the component directory:

cd collector && make test
cd server && make test

See the component development guides for detailed testing information:

Code Style

The project follows these coding standards:

  • Use four spaces for indentation in all source files.
  • Run gofmt on all Go files before committing.
  • Follow Go conventions for naming and code organization.
  • Write readable, modular, and well-documented code.
  • Include unit tests for all new functions and features.

Include the following copyright header at the top of every source file:

/*-------------------------------------------------------
 *
 * pgEdge AI DBA Workbench
 *
 * Copyright (c) 2025 - 2026, pgEdge, Inc.
 * This software is released under The PostgreSQL License
 *
 *-------------------------------------------------------
 */

Adjust the comment style for non-Go languages. Do not include the header in configuration files.

Go Code

Follow these Go-specific guidelines:

  • Export types and functions using PascalCase naming.
  • Use camelCase for private functions and variables.
  • Add doc comments to all exported types and functions.
  • Handle all errors and provide context using fmt.Errorf with %w.
  • Run gofmt and go vet before committing.

Documentation

Follow the documentation style guide in CLAUDE.md:

  • Use active voice in all documentation.
  • Write sentences between 7 and 20 words.
  • Wrap markdown files at 79 characters.
  • Use one first-level heading per file.
  • Include an introductory sentence after each heading.

Submitting Contributions

We welcome contributions from the community. Follow these steps to submit a contribution.

1. Create a Feature Branch

Create a branch for your changes:

git checkout -b feature/your-feature-name

2. Make Your Changes

Implement your changes following the code style guidelines. Add tests for any new functionality and update documentation as needed.

3. Run Quality Checks

Run the full test suite before committing:

make test-all

The test suite must pass without errors or warnings before you submit a pull request.

4. Commit Your Changes

Write clear commit messages that explain what changed and why:

Short summary (50 characters or less)

More detailed explanation if needed. Wrap at 72
characters. Explain what changed and why, not how
(the code shows how).

- Use bullet points for multiple changes
- Use present tense ("Add feature" not "Added feature")
- Reference issues: "Fixes #123"

5. Submit a Pull Request

Push your branch to GitHub and open a pull request:

git push origin feature/your-feature-name

Provide a clear description of your changes in the pull request. Reference any related issues and describe how you tested your changes.

6. Address Review Feedback

Respond to code review comments and make requested changes. Push additional commits to your branch to update the pull request.

Reporting Issues

To report a bug or request a feature, create an issue on GitHub:

GitHub Issues

Include the following information in bug reports:

  • A clear description of the problem.
  • Steps to reproduce the issue.
  • Expected and actual behavior.
  • Component version and environment details.

License

This project is licensed under the PostgreSQL License.

By contributing to the project, you agree that your contributions will be licensed under the same license.