Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
227 lines (157 loc) · 7.15 KB

CONTRIBUTING.md

File metadata and controls

227 lines (157 loc) · 7.15 KB
Raw

Contributing to Open Table Formats

Thank you for your interest in contributing to Open Table Formats! This project is designed to be a collaborative educational resource for understanding modern lakehouse table formats. We welcome contributions from everyone, regardless of experience level.

🎯 Our Mission

Open Table Formats aims to provide comprehensive, unbiased, and educational content about modern open table formats. We believe in:

  • Education First: Making complex technical concepts accessible to learners of all levels
  • Community Collaboration: Building knowledge together through open contribution
  • Technical Accuracy: Ensuring all content is technically correct and up-to-date
  • Vendor Neutrality: Providing unbiased comparisons without favoring any specific implementation

🤝 How to Contribute

For Beginners

If you're new to open source or technical writing, here are great ways to start:

  1. Fix Typos: Help us catch and fix spelling or grammatical errors
  2. Improve Clarity: Suggest clearer explanations for complex concepts
  3. Add Examples: Contribute simple code examples or use cases
  4. Report Issues: Let us know if you find outdated information or broken links

For Intermediate Contributors

If you have some experience with data engineering or technical writing:

  1. Expand Documentation: Add detailed explanations of features or concepts
  2. Create Tutorials: Write step-by-step guides for specific scenarios
  3. Update Content: Keep documentation current with latest format versions
  4. Add Comparisons: Create comparative analyses of different features

For Advanced Contributors

If you're experienced with table formats or open source:

  1. Deep Technical Content: Write advanced technical deep-dives
  2. Architecture Diagrams: Create visual representations of concepts
  3. Performance Analysis: Contribute benchmarks or performance studies
  4. Review Contributions: Help review and improve pull requests

📝 Contribution Process

1. Set Up Your Development Environment

# Fork the repository on GitHub
# Clone your fork locally
git clone https://github.com/YOUR_USERNAME/opentableformats.git
cd opentableformats

# Add the original repository as upstream
git remote add upstream https://github.com/opentableformats/opentableformats.git

# Create a new branch for your contribution
git checkout -b contribution/your-contribution-name

2. Make Your Changes

  • Edit the relevant markdown files
  • Test any code examples you add
  • Ensure your changes follow our style guidelines
  • Update related documentation if needed

3. Commit Your Changes

# Stage your changes
git add .

# Commit with a descriptive message
git commit -m "Add: Brief description of your changes"

Commit message format:

  • Add: for new content
  • Update: for modifications to existing content
  • Fix: for bug fixes or corrections
  • Docs: for documentation improvements

4. Submit Your Contribution

# Push to your fork
git push origin contribution/your-contribution-name

# Create a pull request on GitHub
# Provide a clear description of your changes

📖 Content Guidelines

Writing Style

  • Be Clear: Use simple, straightforward language
  • Be Concise: Get to the point without unnecessary elaboration
  • Be Accurate: Ensure all technical information is correct
  • Be Educational: Explain concepts from first principles
  • Be Neutral: Avoid favoring one technology over another

Documentation Structure

  • Use clear headings and subheadings
  • Include code examples for practical understanding
  • Add diagrams or visual aids when helpful
  • Provide context before diving into details
  • Include links to related resources

Code Examples

  • Use realistic, practical examples
  • Include comments explaining key concepts
  • Test examples before submitting
  • Specify required dependencies or versions
  • Follow language-specific conventions

Technical Accuracy

  • Verify technical claims with official documentation
  • Keep version information up-to-date
  • Distinguish between stable and experimental features
  • Note any platform-specific considerations
  • Cite sources for external information

🎨 Formatting Guidelines

Markdown Style

  • Use # for main titles, ## for subtitles
  • Use - for bullet points
  • Use ** for bold emphasis
  • Use ` for inline code
  • Use ``` for code blocks with language specification
  • Include proper spacing between sections

File Organization

  • Keep related content together
  • Use descriptive file names
  • Maintain consistent directory structure
  • Update table of contents when adding sections
  • Cross-reference related content

🧪 Testing Your Changes

For Documentation Changes

  • Read through your changes to ensure clarity
  • Check that all links work correctly
  • Verify code examples are accurate
  • Ensure formatting renders correctly
  • Test on different devices if possible

For Code Examples

  • Run examples to ensure they work
  • Test with different data scenarios
  • Verify output matches expectations
  • Check for dependency issues
  • Document any prerequisites

📋 Review Process

What We Look For

  1. Accuracy: Technical correctness of information
  2. Clarity: How well concepts are explained
  3. Completeness: Whether the content covers the topic adequately
  4. Consistency: Alignment with existing documentation style
  5. Value: How much the contribution improves the project

Review Timeline

  • Initial review within 1 week
  • Detailed feedback if changes are needed
  • Approval and merge when ready
  • We appreciate your patience during review

🌟 Recognition

We value all contributions and recognize contributors through:

  • GitHub contributor list
  • Release notes for significant contributions
  • Special recognition for outstanding contributions
  • Opportunities to become maintainers for active contributors

💬 Getting Help

If you need help with your contribution:

  • GitHub Issues: Ask questions in issues
  • GitHub Discussions: Start a discussion for general questions
  • Pull Request Comments: Ask for clarification during review
  • Documentation: Check existing documentation for guidance

📜 Code of Conduct

We are committed to providing a welcoming and inclusive environment. Please:

  • Be respectful and constructive in all interactions
  • Welcome newcomers and help them learn
  • Focus on what is best for the community
  • Show empathy towards other community members

🔒 Security

If you discover a security vulnerability:

  • Do not post it publicly
  • Send details to the project maintainers privately
  • Include steps to reproduce the vulnerability
  • Wait for confirmation before public disclosure

📄 License

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

🙏 Thank You

Every contribution, no matter how small, helps make this project better for everyone. We appreciate your time and effort in improving Open Table Formats!

Need more help? Check out our GitHub Issues or GitHub Discussions