# 🎻 Contributing to Kompose First off, thank you for considering contributing to Kompose! 🎉 It's people like you that make Kompose such a great tool. Every contribution, no matter how small, helps make Docker orchestration a little less painful and a lot more musical. ## 🎯 Quick Links - [Code of Conduct](#code-of-conduct) - [How Can I Contribute?](#how-can-i-contribute) - [Development Setup](#development-setup) - [Style Guidelines](#style-guidelines) - [Commit Messages](#commit-messages) - [Pull Request Process](#pull-request-process) ## 📜 Code of Conduct This project and everyone participating in it is governed by common sense and mutual respect. By participating, you are expected to: - ✨ Be welcoming and friendly - 🤝 Respect differing viewpoints and experiences - 🎯 Focus on what is best for the community - 🙌 Show empathy towards other community members - ☕ Remember that we're all human (and probably under-caffeinated) ## 🎪 How Can I Contribute? ### 🐛 Reporting Bugs Before creating bug reports, please check existing issues as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible: **Great Bug Report Template:** ```markdown ## Description A clear and concise description of the bug. ## Steps to Reproduce 1. Run `./kompose.sh ...` 2. See error ## Expected Behavior What you expected to happen. ## Actual Behavior What actually happened. ## Environment - OS: [e.g., Ubuntu 22.04] - Docker Version: [e.g., 24.0.5] - Bash Version: [e.g., 5.1.16] - Kompose Version/Commit: [e.g., commit abc123] ## Additional Context Any other context, logs, or screenshots. ``` ### 💡 Suggesting Enhancements Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, include: - **Use a clear and descriptive title** - **Provide a detailed description of the suggested enhancement** - **Explain why this enhancement would be useful** - **List some examples of how it would be used** ### 🎨 Your First Code Contribution Unsure where to begin? Look for issues labeled: - `good first issue` - Simple issues perfect for newcomers - `help wanted` - Issues we'd love help with - `documentation` - Improvements to docs ### 🔧 Pull Requests Ready to contribute code? Awesome! Follow these steps: 1. **Fork & Clone** ```bash git clone https://github.com/YOUR-USERNAME/kompose.git cd kompose ``` 2. **Create a Branch** ```bash git checkout -b feature/amazing-feature # or git checkout -b fix/annoying-bug ``` 3. **Make Your Changes** - Write clean, readable code - Add comments for complex logic - Test thoroughly with `--dry-run` 4. **Test Your Changes** ```bash # Test basic functionality ./kompose.sh --help ./kompose.sh --list # Test dry-run mode ./kompose.sh --dry-run "*" up -d # Test with actual stacks if possible ./kompose.sh blog up -d ``` 5. **Commit Your Changes** ```bash git add . git commit -m "feat: add amazing feature" ``` 6. **Push to Your Fork** ```bash git push origin feature/amazing-feature ``` 7. **Open a Pull Request** - Go to the original kompose repository - Click "New Pull Request" - Select your fork and branch - Fill in the PR template ## 🛠️ Development Setup ### Prerequisites - Bash 4.0+ - Docker & Docker Compose - Git - PostgreSQL client tools (for db operations) ### Setting Up ```bash # Clone your fork git clone https://github.com/YOUR-USERNAME/kompose.git cd kompose # Make script executable chmod +x kompose.sh # Create test environment cp .env.example .env nano .env # Create Docker network docker network create kompose # Test the script ./kompose.sh --help ``` ### Testing ```bash # Syntax check bash -n kompose.sh # ShellCheck (highly recommended) shellcheck kompose.sh # Test with dry-run ./kompose.sh --dry-run "*" ps # Test specific features ./kompose.sh --list ./kompose.sh blog up -d --dry-run ./kompose.sh -e TEST=value blog ps --dry-run ``` ## 📝 Style Guidelines ### Shell Script Style We follow these conventions: #### Variables ```bash # Constants in UPPER_CASE readonly SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" readonly ROOT_ENV_FILE="${SCRIPT_DIR}/.env" # Local variables in lowercase local stack_dir="$1" local dump_file="$2" ``` #### Functions ```bash # Descriptive function names with underscores function_name() { local param="$1" # Early returns for validation if [[ -z "${param}" ]]; then return 1 fi # Main logic here return 0 } ``` #### Error Handling ```bash # Use set -euo pipefail at the top set -euo pipefail # Check command success if ! docker compose up -d; then log_error "Failed to start containers" return 1 fi ``` #### Logging ```bash # Use consistent logging functions log_info "Starting operation..." log_success "Operation completed!" log_warning "This might be a problem" log_error "Something went wrong" ``` ### Documentation Style - Use clear, concise language - Include code examples - Add emojis sparingly but meaningfully - Keep line length reasonable (80-120 chars) - Use proper markdown formatting ## 💬 Commit Messages We follow [Conventional Commits](https://www.conventionalcommits.org/): ### Format ``` ():