Skip to content

contributing.md

Latest commit

 

History

History
304 lines (222 loc) · 7.7 KB

contributing.md

File metadata and controls

304 lines (222 loc) · 7.7 KB
Raw

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 20.19 or later on the 20.x line, or Node.js 22.12 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 from the ai-dba-workbench repository root. In the following example, the cd client command enters the client directory; the npm install command installs dependencies; the npm run build command builds the client:

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.

Copyright Header

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.

Transaction Rollbacks

Roll every pgx transaction back through the shared github.com/pgedge/ai-workbench/pkg/rollback helper, never by calling Rollback on the transaction directly:

tx, err := pool.Begin(ctx)
if err != nil {
    return fmt.Errorf("begin transaction: %w", err)
}
defer rollback.Tx(ctx, tx) //nolint:errcheck // no-op after commit

Use rollback.ToSavepoint(ctx, tx, name) in place of a hand-written ROLLBACK TO SAVEPOINT statement. Both functions run the rollback on a context derived from ctx with context.WithoutCancel and a rollback.Timeout deadline of five seconds. When a rollback is given a request context that the client has already cancelled, the pgx v5 driver fails the rollback and closes the connection; the server then ends the transaction itself, so the cost is connection churn and a lost pool slot whilst the pool reconnects. A plain context.Background() avoids that but has no deadline, so a rollback to a hung server could pin a pool slot and the goroutine indefinitely; the helper bounds the wait and keeps the request's tracing values. The statements inside the transaction still use the request context; only the rollback differs. A convention test in each Go module rejects direct Rollback calls and hand-written ROLLBACK SQL outside the helper package; the package doc comment in pkg/rollback gives the full reasoning.

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.