Skip to main content

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**:
```sql
-- Relevant PostgreSQL logs

Additional Context: Any other information


[Report a Bug](https://github.com/ibrahimkarimeddin/postgres-extensions-pg_ttl/issues/new)

## Suggesting Features

### Feature Request Template

```markdown
**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?​

Thank You!​

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

See Also​