Contributing¶

Thank you for your interest in contributing to pgraft! This guide will help you get started.

Getting Started¶

1. Fork the repository on GitHub
2. Clone your fork:

   git clone https://github.com/YOUR_USERNAME/pgraft.git cd pgraft 

3. Create a feature branch:

   git checkout -b feature/my-new-feature 

Development Environment¶

Setup¶

Follow the Building from Source guide to set up your development environment.

Prerequisites¶

• PostgreSQL 17+
• Go 1.21+
• GCC/Clang
• Make

Coding Standards¶

C Code Standards¶

pgraft follows strict PostgreSQL C coding standards:

C89/C90 Compliance¶

/* All variables at function start */ void my_function(void) {  int result;  char *message;  bool success;   /* Initialize variables */  result = 0;  message = NULL;  success = false;   /* Function code */ } 

Comments¶

/*  * Use C-style comments only  * Multi-line comments like this  */  /* Single line comments */  /* NO C++ style comments */ // Don't use these 

Indentation¶

• Tabs only (no spaces)
• Tab width: 4 spaces equivalent
• Opening brace on same line (usually):

if (condition) {  /* code */ } 

Naming Conventions¶

/* Functions: snake_case with pgraft_ prefix */ void pgraft_do_something(void);  /* Variables: snake_case */ int node_count; char *cluster_id;  /* Macros: UPPER_CASE */ #define PGRAFT_MAX_NODES 7 

Go Code Standards¶

Follow standard Go conventions:

// Use gofmt gofmt -w src/pgraft_go.go  // Use golint golint src/pgraft_go.go  // Keep functions focused // Add comments for exported functions // Handle errors explicitly 

Code Quality¶

Before Submitting¶

1. No compilation errors or warnings:

make clean && make 2>&1 | grep -E "(error|warning)" # Should be empty 

2. Format code:

# C code: Follow PostgreSQL style # Go code: gofmt -w src/pgraft_go.go 

3. Test thoroughly:

cd examples ./run.sh --destroy ./run.sh --init ./run.sh --status 

4. Check for memory leaks (optional but recommended):

valgrind --leak-check=full postgres -D /path/to/data 

Testing Requirements¶

Minimum Testing¶

Before submitting a pull request:

1. Build successfully with no errors or warnings
2. Initialize test cluster successfully
3. All existing tests pass
4. New feature works as documented

Testing Your Changes¶

# 1. Clean build make clean && make  # 2. Install make install  # 3. Test cluster cd examples ./run.sh --destroy ./run.sh --init ./run.sh --status  # 4. Run manual tests psql -p 5432 -c "SELECT pgraft_test();" # ... test your feature ...  # 5. Check logs for errors tail -100 examples/logs/primary1/postgresql.log | grep -i error 

Pull Request Process¶

1. Prepare Your Changes¶

# Make your changes vim src/pgraft_core.c  # Test thoroughly make clean && make make install # Run tests  # Commit with good message git add src/pgraft_core.c git commit -m "Add feature: description of change  Detailed explanation of: - What changed - Why it changed - How to use it" 

2. Push to Your Fork¶

git push origin feature/my-new-feature 

3. Create Pull Request¶

On GitHub:

1. Navigate to your fork
2. Click "New Pull Request"
3. Select your feature branch
4. Fill out the template:

## Description Brief description of the change  ## Motivation Why is this change needed?  ## Changes - List of specific changes - Another change  ## Testing How did you test this?  ## Checklist - [ ] Code compiles without errors - [ ] Code compiles without warnings - [ ] Tests pass - [ ] Documentation updated (if needed) - [ ] Follows coding standards 

4. Code Review¶

Maintainers will review your PR:

• Respond to feedback
• Make requested changes
• Push updates to same branch (PR updates automatically)

5. Merge¶

Once approved, maintainers will merge your PR!

Commit Message Guidelines¶

Format¶

Short summary (50 chars or less)  Longer explanation if needed. Wrap at 72 characters. Explain what and why, not how.  - Bullet points are fine - Use present tense: "Add feature" not "Added feature" 

Good Examples¶

Add support for dynamic cluster membership  Allows nodes to be added and removed from cluster at runtime without restarting. Uses Raft's joint consensus protocol.  Fix memory leak in log compaction  Free allocated memory after snapshot creation.  Improve error handling in network layer  Add retries for transient network failures and better error messages for debugging. 

Documentation¶

Update Documentation¶

If your change affects:

• User-facing features: Update relevant .md files
• Configuration: Update GUC documentation
• SQL functions: Update function reference
• Architecture: Update architecture docs

Documentation Style¶

# Use sentence case for headings  Write clear, concise sentences. Use active voice.  Provide examples: \`\`\`sql SELECT pgraft_example(); \`\`\`  Use admonitions for important information: !!! warning  Important warning here 

Areas for Contribution¶

We welcome contributions in these areas:

High Priority¶

• Testing: More test cases and scenarios
• Documentation: Examples, tutorials, guides
• Bug fixes: Check GitHub issues
• Performance: Optimization improvements

Medium Priority¶

• Monitoring: Better metrics and observability
• Security: TLS, authentication
• Platform support: Windows, BSD

Nice to Have¶

• Tools: Cluster management utilities
• Examples: Real-world use cases
• Integrations: Connection poolers, HA tools

Bug Reports¶

Before Reporting¶

1. Search existing issues: Check if already reported
2. Test latest version: Bug may be fixed
3. Reproduce: Verify you can reproduce it

Creating Good Bug Reports¶

Use this template:

**Describe the bug** Clear description of the bug  **To Reproduce** Steps to reproduce: 1. Do X 2. Do Y 3. See error  **Expected behavior** What should happen  **Actual behavior** What actually happens  **Environment** - OS: [e.g. Ubuntu 22.04] - PostgreSQL version: [e.g. 17.2] - pgraft version: [e.g. 1.0.0]  **Logs** \`\`\` Relevant log output \`\`\`  **Configuration** \`\`\`ini pgraft.cluster_id = 'test' ... \`\`\` 

Feature Requests¶

Creating Feature Requests¶

**Feature Description** What feature do you want?  **Use Case** Why is this needed? What problem does it solve?  **Proposed Solution** How might this work?  **Alternatives** Other solutions you've considered?  **Additional Context** Any other information 

Communication¶

• GitHub Issues: Bug reports, feature requests
• Pull Requests: Code contributions
• Discussions: Questions, ideas, help

License¶

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

Code of Conduct¶

Our Standards¶

• Be respectful and inclusive
• Welcome newcomers
• Accept constructive criticism gracefully
• Focus on what's best for the project

Unacceptable Behavior¶

• Harassment or discrimination
• Trolling or insulting comments
• Publishing others' private information
• Other unprofessional conduct

Recognition¶

Contributors will be recognized in:

• Release notes
• CONTRIBUTORS file
• Git history

Thank you for contributing to pgraft!