Contributing to STRUCT¶
Thank you for your interest in contributing to STRUCT! We welcome contributions from the community and are pleased to have you join us.
🚀 Quick Start¶
- Fork the repository on GitHub
- Clone your fork locally
- Create a feature branch from
main
- Make your changes and commit them
- Push to your fork and submit a pull request
📋 Development Setup¶
Prerequisites¶
- Python 3.8 or higher
- Git
- A text editor or IDE
Local Development¶
Clone the repository:
Create a virtual environment:
Install in development mode:
Run tests to ensure everything works:
🔧 Making Changes¶
Code Style¶
- Follow PEP 8 guidelines
- Use 2 spaces for indentation in YAML files
- Use 4 spaces for indentation in Python files
- Write clear, descriptive commit messages
- Add docstrings to new functions and classes
Testing¶
- Write tests for new functionality
- Ensure all existing tests pass
- Run the test suite:
pytest
- Check test coverage:
pytest --cov=struct_module
Pull Request Guidelines¶
- Create descriptive PR titles that summarize the change
- Fill out the PR template completely
- Link to related issues when applicable
- Keep PRs focused - one feature/fix per PR
- Update documentation if your changes affect user-facing functionality
📝 Documentation¶
We use Markdown for documentation. When contributing:
- Update relevant documentation files
- Add examples for new features
- Keep language clear and concise
- Follow the existing documentation structure
Documentation Structure¶
docs/
├── index.md # Main documentation index
├── installation.md # Installation instructions
├── quickstart.md # Quick start guide
├── configuration.md # YAML configuration reference
├── template-variables.md # Template variable documentation
├── file-handling.md # File handling features
├── custom-structures.md # Creating custom structures
├── hooks.md # Pre/post hooks
├── mappings.md # External data mappings
├── github-integration.md # GitHub Actions integration
├── development.md # Development setup
├── completion.md # CLI completion setup
├── cli-reference.md # Complete CLI reference
├── schema.md # YAML schema reference
├── examples/ # Example configurations
├── articles.md # External articles and tutorials
├── known-issues.md # Known limitations
├── contributing.md # This file
└── funding.md # Funding information
🏗️ Contributing New Structures¶
STRUCT includes a collection of contrib structures in struct_module/contribs/
. To add a new structure:
- Create a new YAML file in the appropriate subdirectory
- Follow naming conventions: use lowercase with hyphens
- Test your structure with various scenarios
- Add documentation explaining what the structure does
- Include examples in your PR description
Structure Guidelines¶
- Use descriptive file and folder names
- Include appropriate comments in YAML
- Follow the established patterns in existing structures
- Test with different variable combinations
- Ensure compatibility across platforms
🐛 Reporting Issues¶
Bug Reports¶
When reporting bugs, please include:
- OS and Python version
- STRUCT version (
struct --version
) - Complete error message or traceback
- Steps to reproduce the issue
- Expected vs actual behavior
- Sample configuration that reproduces the issue
Feature Requests¶
For feature requests:
- Describe the use case clearly
- Explain the benefit to other users
- Provide examples of how it would work
- Consider implementation complexity
📊 Project Structure¶
struct/
├── struct_module/ # Main Python package
│ ├── commands/ # CLI command implementations
│ ├── contribs/ # Contributed structure templates
│ ├── __init__.py
│ ├── main.py # CLI entry point
│ ├── file_item.py # File handling logic
│ ├── template_renderer.py # Jinja2 template rendering
│ ├── content_fetcher.py # Remote content fetching
│ ├── model_wrapper.py # AI model integration
│ └── utils.py # Utility functions
├── tests/ # Test suite
├── docs/ # Documentation
├── examples/ # Example configurations
├── requirements.txt # Production dependencies
├── requirements.dev.txt # Development dependencies
├── setup.py # Package configuration
├── struct-schema.json # JSON schema for validation
└── README.md # Project overview
🏷️ Issue Labels¶
We use labels to categorize issues:
bug
- Something isn't workingenhancement
- New feature or requestdocumentation
- Improvements to documentationgood first issue
- Good for newcomershelp wanted
- Extra attention is neededquestion
- Further information is requested
💬 Communication¶
- GitHub Issues - Bug reports and feature requests
- GitHub Discussions - General questions and community support
- Pull Requests - Code contributions and reviews
🙏 Recognition¶
All contributors will be recognized in our documentation and releases. We appreciate every contribution, whether it's:
- Code improvements
- Bug reports
- Documentation updates
- Feature suggestions
- Community support
📜 Code of Conduct¶
This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.
🤝 Getting Help¶
If you need help contributing:
- Check existing documentation
- Search existing issues
- Create a new issue with the
question
label - Join our GitHub Discussions
Thank you for contributing to STRUCT! 🎉