31bfdb83bb
- Add complete CC BY-NC-SA 4.0 International License - Add comprehensive README with project description and usage - Add CONTRIBUTING guidelines for developers - Add Nix development environment with OpenSCAD tooling - Add .gitignore for OpenSCAD and Nix projects - Add copyright headers to source files
105 lines
No EOL
4.1 KiB
Markdown
105 lines
No EOL
4.1 KiB
Markdown
# 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! |