cuatro/CONTRIBUTING.md

Contributing to Cuatro

Thank you for your interest in contributing to Cuatro! This document provides guidelines for contributing to this 3D printable game pieces project.

Ways to Contribute

Reporting Bugs

• Check if the bug has already been reported in the issues
• Provide clear steps to reproduce the issue
• Include OpenSCAD version and operating system information
• Attach screenshots or error messages if applicable

Suggesting Enhancements

• Check existing issues for similar suggestions
• Clearly describe the proposed feature or improvement
• Explain the use case and benefits
• Consider backward compatibility with existing designs

Code Contributions

We welcome improvements to the OpenSCAD code! Areas where contributions are especially valuable:

• Parameterization: Making more aspects of the design configurable
• New Piece Types: Adding additional game piece variants
• Optimization: Improving print efficiency or material usage
• Documentation: Adding code comments and improving clarity
• Testing: Validating designs across different print settings

Development Guidelines

OpenSCAD Code Style

• Use descriptive variable and module names
• Keep modules focused on single responsibilities
• Add comments for complex calculations or design decisions
• Use consistent indentation (4 spaces)
• Group related modules together

Design Principles

• Printability: All designs must be 3D printer friendly
• Modularity: Create reusable modules when possible
• Parameterization: Use variables instead of magic numbers
• Efficiency: Minimize material usage while maintaining strength
• Compatibility: Maintain consistent scaling relationships

File Organization

• Keep the main design in parts.scad
• Use meaningful module names that describe their function
• Place configurable parameters at the top of the file
• Document parameter units and expected ranges

Submission Process

Before Submitting

1. Test your changes in OpenSCAD (both preview and render)
2. Verify the generated STL files are printable
3. Check that existing functionality still works
4. Update documentation if you've added new features
5. Ensure your changes follow the project's design principles

Creating a Pull Request

1. Fork the repository
2. Create a descriptive branch name (e.g., feature/hollow-star-pieces)
3. Make your changes with clear, focused commits
4. Test thoroughly with different parameter values
5. Submit a pull request with:
   • Clear description of changes made
   • Explanation of the problem solved or feature added
   • Screenshots or images of printed results (if available)
   • Any breaking changes clearly noted

Commit Messages

• Use clear, descriptive commit messages
• Start with a verb (Add, Fix, Update, Remove, etc.)
• Keep the first line under 72 characters
• Example: "Add hollow star piece variant with configurable points"

Testing Guidelines

Design Validation

• Preview design in OpenSCAD (F5) for quick validation
• Full render (F6) for final verification
• Export STL and check for printability issues
• Test with different parameter values to ensure robustness

Print Testing

While not required for all contributions, physical print testing is highly valued:

• Test with common 3D printer settings
• Verify dimensional accuracy
• Check structural integrity
• Document any print-specific observations

Questions and Support

• Design Questions: Open an issue for design-related discussions
• Technical Issues: Include OpenSCAD version and code snippets
• Feature Requests: Describe the use case and expected behavior

License Agreement

By contributing to Cuatro, you agree that your contributions will be licensed under the same CC BY-NC-SA 4.0 International License that covers the project. You retain copyright of your contributions while granting the project rights to use and distribute them under this license.

Recognition

Contributors will be acknowledged in the project documentation. Significant contributions may be recognized in release notes and project history.

Thank you for helping make Cuatro better!