Contributing

Help improve pg_ttl_index! Contributions are welcome.

Ways to Contribute

  • ๐Ÿ› Report bugs - Found an issue? Let us know!
  • โœจ Suggest features - Have ideas? Share them!
  • ๐Ÿ“ Improve documentation - Fix typos, add examples
  • ๐Ÿ’ป Submit code - Fix bugs, add features
  • ๐Ÿงช Write tests - Improve test coverage
  • ๐Ÿ“ฃ Spread the word - Share with others

Reporting Bugs

Before Reporting

  1. Check existing issues
  2. Try the latest version
  3. Review Troubleshooting Guide

What to Include

**Environment**:
- PostgreSQL version: 16.1
- pg_ttl_index version: 2.0.0
- Operating System: Ubuntu 22.04

**Description**:
Clear description of the problem

**Steps to Reproduce**:
1. Create table...
2. Run SELECT ttl_create_index(...)
3. Observe error...

**Expected Behavior**:
What should happen

**Actual Behavior**:
What actually happened

**Logs**:

โ€“ Relevant PostgreSQL logs ```

Additional Context: Any other information ```

Report a Bug

Suggesting Features

Feature Request Template

**Feature Description**:
Brief summary of the feature

**Use Case**:
Why is this needed? What problem does it solve?

**Proposed Solution**:
How should it work?

**Alternatives Considered**:
Other approaches you've thought about

**Additional Context**:
Mockups, examples, etc.

Request a Feature

Development Setup

Prerequisites

  • PostgreSQL 12+ development packages
  • GCC or Clang compiler
  • Make
  • Git

Clone & Build

# Clone repository
git clone https://github.com/ibrahimkarimeddin/postgres-extensions-pg_ttl.git
cd postgres-extensions-pg_ttl

# Build extension
make

# Install locally
sudo make install

# Run tests
make installcheck

Development Workflow

# Create feature branch
git checkout -b feature/your-feature-name

# Make changes
$EDITOR src/worker.c

# Build
make clean && make

# Test
make installcheck

# Commit
git add .
git commit -m "feat: add your feature"

# Push
git push origin feature/your-feature-name

Code Style

C Code

Follow PostgreSQL coding conventions:

// Good
static void
cleanup_expired_rows(char *table_name)
{
    /* Clear documentation */
    int     rows_deleted = 0;

    /* Code here */
}

// Bad
static void cleanupExpiredRows(char* tableName) {
    int rowsDeleted=0;
}

Key points: - Tabs (not spaces) for indentation - Opening brace on same line for functions - Use PostgreSQL data types (int32, Datum, etc.) - Document with /* */ comments

SQL Code

-- Good: clear, formatted
CREATE OR REPLACE FUNCTION ttl_runner()
RETURNS INTEGER
LANGUAGE plpgsql
AS $$
DECLARE
    rec RECORD;
BEGIN
    FOR rec IN SELECT ... LOOP
        -- Code
    END LOOP;

    RETURN total;
END;
$$;

-- Bad: cramped, unclear
CREATE FUNCTION ttl_runner() RETURNS INTEGER LANGUAGE plpgsql AS $$ BEGIN FOR rec IN SELECT ... LOOP END LOOP; RETURN total; END;$$;

Format Your Code

# Format C code (if clang-format available)
make format

# Check SQL syntax
psql -d test -f pg_ttl_index--2.0.0.sql

Testing

Run Regression Tests

# Full test suite
make installcheck

# Results in: regression.diffs (if any failures)

Add New Tests

Edit test/sql/pg_ttl_index_test.sql:

-- Test your feature
CREATE TABLE test_feature (...);
SELECT ttl_create_index('test_feature', 'created_at', 60);

-- Verify expected behavior
SELECT * FROM ttl_summary() WHERE table_name = 'test_feature';

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

Expected output in test/expected/pg_ttl_index_test.out.

Manual Testing

# Start test database
docker-compose up -d

# Connect
psql -h localhost -U postgres -d postgres

# Test your changes
CREATE EXTENSION pg_ttl_index;
SELECT ttl_start_worker();
-- Test...

Submitting Pull Requests

Before Submitting

  • โœ… Tests pass (make installcheck)
  • โœ… Code follows style guide
  • โœ… Documentation updated (if needed)
  • โœ… Commit messages are clear
  • โœ… Branch is up to date with main

Pull Request Template

## Description
Brief description of changes

## Motivation
Why is this change needed?

## Changes Made
- Added feature X
- Fixed bug Y
- Updated documentation Z

## Testing
How did you test this?

## Checklist
- [ ] Tests pass
- [ ] Documentation updated
- [ ] Code follows style guide
- [ ] Tested on PostgreSQL 12, 13, 14, 15, 16 (if applicable)

Commit Message Format

type(scope): brief description

Longer explanation if needed

Fixes #123

Types: - feat: New feature - fix: Bug fix - docs: Documentation only - test: Adding tests - refactor: Code refactoring - perf: Performance improvement

Examples: ``` feat(worker): add batch deletion support

fix(api): handle missing timestamp column gracefully

docs(readme): update installation instructions ```

Documentation

Building Docs Locally

cd website_docs
npm install
npm start

Visit http://localhost:3000

Writing Documentation

  • Use clear, concise language
  • Include code examples
  • Add cross-links between related pages
  • Test all SQL examples

Code Review Process

  1. Automated checks run (tests, linting)
  2. Maintainer review (usually within 1 week)
  3. Feedback & iteration (if needed)
  4. Approval & merge

Community Guidelines

  • Be respectful and constructive
  • Welcome newcomers
  • Focus on ideas, not people
  • Assume good intentions

License

By contributing, you agree that your contributions will be licensed under the PostgreSQL License.

Questions?

  • GitHub Discussions: Ask questions
  • Email: ibrahimkarimeddin@gmail.com

Thank You!

Every contribution helps make pg_ttl_index better. Thank you for your time and effort!

See Also