Contributing to pg_ttl_index

Thank you for your interest in contributing to pg_ttl_index! This document provides guidelines and instructions for contributing.

Table of Contents

  1. Code of Conduct
  2. Getting Started
  3. Development Setup
  4. Making Changes
  5. Testing
  6. Submitting Changes
  7. Coding Standards

Code of Conduct

This project adheres to a code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainers.

Be respectful, be collaborative, be helpful.

Getting Started

Prerequisites

  • PostgreSQL 12.0 or higher
  • GCC or compatible C compiler
  • GNU Make
  • Git
  • PostgreSQL development headers (postgresql-server-dev-*)

Fork and Clone

  1. Fork the repository on GitHub
  2. Clone your fork locally: bash git clone https://github.com/YOUR_USERNAME/pg_ttl_index.git cd pg_ttl_index
  3. Add the upstream repository: bash git remote add upstream https://github.com/ibrahimkarimeddin/postgres-extensions-pg_ttl.git

Development Setup

Build the Extension

# Clean any previous builds
make clean

# Build the extension
make

# Install to your PostgreSQL installation
sudo make install

Load the Extension

-- Connect to your test database
\c test_database

-- Create the extension
CREATE EXTENSION pg_ttl_index;

-- Start the worker
SELECT ttl_start_worker();

Making Changes

Branch Naming

Use descriptive branch names: - feature/add-new-function - for new features - fix/issue-123 - for bug fixes - docs/update-readme - for documentation - refactor/cleanup-worker - for refactoring

Commit Messages

Write clear, descriptive commit messages:

Short summary (50 chars or less)

More detailed explanatory text, if necessary. Wrap it to about 72
characters. The blank line separating the summary from the body is
critical.

- Bullet points are okay
- Use present tense ("Add feature" not "Added feature")
- Reference issues and pull requests

Fixes: #123
See also: #456

Testing

Running Tests

# Run regression tests (when implemented)
make installcheck

# Or run tests without installation
make check

Manual Testing

Create a test script to verify your changes:

-- test/manual_test.sql
\c test_db

-- Create test table
CREATE TABLE test_table (
    id SERIAL PRIMARY KEY,
    data TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Add TTL index
SELECT ttl_create_index('test_table', 'created_at', 60);

-- Insert test data
INSERT INTO test_table (data) VALUES ('test1'), ('test2');

-- Check TTL configuration
SELECT * FROM ttl_index_table;

-- Wait and verify cleanup (optional)
-- SELECT pg_sleep(65);
-- SELECT ttl_runner();
-- SELECT * FROM test_table;

-- Cleanup
SELECT ttl_drop_index('test_table', 'created_at');
DROP TABLE test_table;

Test Coverage

When adding new features: 1. Add corresponding test cases 2. Verify edge cases 3. Test with different PostgreSQL versions (if possible) 4. Test with different data types (timestamp, timestamptz, date)

Submitting Changes

Before Submitting

  1. Update from upstream: bash git fetch upstream git rebase upstream/main

  2. Build and test: ```bash make clean make sudo make install

    Run your tests

    ```

  3. Check code style:

    • Follow PostgreSQL C coding conventions
    • Use 4-space indentation (tabs in Makefile)
    • Add comments for complex logic
    • Keep lines under 80 characters when reasonable

  4. Update documentation:

    • Update README.md if adding features
    • Update CHANGES file with your changes
    • Add inline code comments

Pull Request Process

  1. Push to your fork: bash git push origin feature/your-feature-name

  2. Create Pull Request:

    • Go to GitHub and create a PR from your fork
    • Fill in the PR template with:
      • Description of changes
      • Related issues
      • Testing performed
      • Screenshots (if applicable)

  3. PR Title Format: ``` [TYPE] Brief description

    Examples: [FEATURE] Add support for interval-based TTL [FIX] Resolve worker crash on NULL timestamps [DOCS] Update installation instructions [REFACTOR] Improve error handling ```

  4. Address Review Comments:

    • Respond to all review comments
    • Make requested changes
    • Push updates to the same branch

Coding Standards

C Code Standards

/*
 * Function: my_function_name
 *
 * Description:
 *   Brief description of what this function does
 *
 * Parameters:
 *   param1 - description
 *   param2 - description
 *
 * Returns:
 *   Description of return value
 */
static bool
my_function_name(const char *param1, int param2)
{
    /* Variable declarations */
    StringInfoData query;
    bool result = false;

    /* Function body with clear logic */
    if (param1 == NULL)
        ereport(ERROR,
                (errcode(ERRCODE_INVALID_PARAMETER_VALUE),
                 errmsg("param1 cannot be NULL")));

    /* More implementation */

    return result;
}

SQL Code Standards

-- Use descriptive function/table names
-- Add comments for complex queries
-- Format for readability

CREATE OR REPLACE FUNCTION ttl_my_function(
    table_name TEXT,
    column_name TEXT
)
RETURNS BOOLEAN
LANGUAGE plpgsql
AS $$
DECLARE
    row_count INTEGER;
BEGIN
    -- Clear comment explaining the logic
    SELECT COUNT(*) INTO row_count
    FROM ttl_index_table
    WHERE table_name = $1
      AND column_name = $2;

    RETURN row_count > 0;
END;
$$;

Documentation Standards

  • Use Markdown for all documentation
  • Keep README.md up to date
  • Add examples for new features
  • Document all parameters and return values
  • Include error conditions

Project Structure

pg_ttl_index/
├── src/                    # C source files
│   ├── pg_ttl_index.c      # Extension entry point
│   ├── worker.c            # Background worker logic
│   ├── api.c               # SQL interface implementation
│   └── utils.c             # Helper functions
├── test/                   # Regression tests
│   ├── sql/                # Test scripts
│   └── expected/           # Expected output
├── pg_ttl_index--*.sql     # SQL definitions
├── pg_ttl_index.control    # Extension control file
├── Makefile                # Build configuration
├── README.md               # User documentation
├── CONTRIBUTING.md         # This file
├── LICENSE                 # License information
├── CHANGES                 # Version history
└── META.json               # PGXN metadata

Questions or Need Help?

  • GitHub Issues: Open an issue for bugs or feature requests
  • Discussions: Use GitHub Discussions for questions
  • Email: Contact maintainers for security issues

Recognition

Contributors will be acknowledged in: - CHANGES file - GitHub contributors list

Thank you for contributing to pg_ttl_index! 🎉