# Contributing to AppsFruit Elementor Embed

Thank you for your interest in contributing to AppsFruit Elementor Embed! This document provides guidelines and instructions for contributing.

## Code of Conduct

- Be respectful and inclusive
- Provide constructive feedback
- Focus on what is best for the community
- Show empathy towards other community members

## How to Contribute

### Reporting Bugs

Before creating bug reports, please check existing issues to avoid duplicates.

**When submitting a bug report, include:**

- Clear and descriptive title
- Steps to reproduce the issue
- Expected behavior
- Actual behavior
- Screenshots (if applicable)
- WordPress version
- PHP version
- Elementor version
- Plugin version
- Theme being used
- Other active plugins

**Bug Report Template:**

```
**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error

**Expected behavior**
What you expected to happen.

**Screenshots**
If applicable, add screenshots.

**Environment:**
- WordPress Version: [e.g., 6.3]
- PHP Version: [e.g., 8.0]
- Elementor Version: [e.g., 3.16]
- Plugin Version: [e.g., 1.0.0]
- Theme: [e.g., Astra]
- Active Plugins: [list other plugins]

**Additional context**
Any other context about the problem.
```

### Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues.

**When suggesting an enhancement, include:**

- Clear and descriptive title
- Detailed description of the proposed functionality
- Use cases and examples
- Why this enhancement would be useful
- Possible implementation approach (if you have ideas)

### Pull Requests

1. **Fork the repository**
2. **Create a feature branch** (`git checkout -b feature/amazing-feature`)
3. **Make your changes**
4. **Test thoroughly**
5. **Commit your changes** (`git commit -m 'Add amazing feature'`)
6. **Push to the branch** (`git push origin feature/amazing-feature`)
7. **Open a Pull Request**

**Pull Request Guidelines:**

- Follow WordPress Coding Standards
- Include relevant tests (if applicable)
- Update documentation
- Add entry to CHANGELOG.md
- Ensure backward compatibility
- Keep changes focused and atomic
- Write clear commit messages

## Development Setup

### Prerequisites

- WordPress development environment
- PHP 7.4 or higher
- Elementor plugin
- Code editor (VS Code, PHPStorm, etc.)

### Local Setup

1. Clone the repository into your WordPress plugins directory:
```bash
cd wp-content/plugins/
git clone [repository-url] appsfruit-elementor-embed
```

2. Activate the plugin in WordPress admin

3. Install Elementor if not already installed

### Development Workflow

1. **Create a branch** for your feature or fix
2. **Make changes** following coding standards
3. **Test locally** with various configurations
4. **Document** your changes
5. **Submit** a pull request

## Coding Standards

### PHP

Follow [WordPress PHP Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/):

- Use tabs for indentation
- Use single quotes for strings (unless interpolation needed)
- Add spaces around operators
- Use meaningful variable names
- Add inline documentation
- Use proper WordPress functions

**Example:**

```php
<?php
/**
 * Function description
 *
 * @param int    $post_id Post ID.
 * @param string $context Context.
 * @return bool
 */
function aefe_custom_function( $post_id, $context = 'default' ) {
    if ( ! $post_id ) {
        return false;
    }
    
    $result = get_post_meta( $post_id, '_custom_key', true );
    
    return ! empty( $result );
}
```

### JavaScript

Follow [WordPress JavaScript Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/):

- Use tabs for indentation
- Use single quotes for strings
- Use camelCase for variables and functions
- Add JSDoc comments
- Use strict mode

**Example:**

```javascript
/**
 * Copy text to clipboard
 *
 * @param {string} text Text to copy.
 * @param {Function} callback Callback function.
 */
function copyToClipboard( text, callback ) {
    'use strict';
    
    if ( navigator.clipboard ) {
        navigator.clipboard.writeText( text ).then( function() {
            callback( true );
        } );
    }
}
```

### CSS

Follow [WordPress CSS Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/css/):

- Use tabs for indentation
- Use lowercase for selectors
- One selector per line
- Add space after colon
- Use shorthand properties when possible

**Example:**

```css
.afe-wrapper {
    display: flex;
    padding: 20px;
    margin: 0 auto;
    background: #fff;
}

.afe-wrapper .afe-item {
    flex: 1;
    margin-right: 10px;
}
```

## Documentation

### Inline Documentation

- Add PHPDoc blocks for all functions and classes
- Document parameters and return values
- Explain complex logic with comments
- Keep comments up to date

### User Documentation

When adding features:
- Update README.md
- Update SETUP.md if setup changes
- Add examples to DEVELOPER.md
- Update help page content

### Changelog

Add entries to CHANGELOG.md following this format:

```markdown
## [Version] - YYYY-MM-DD

### Added
- New feature description

### Changed
- Changed feature description

### Fixed
- Bug fix description

### Deprecated
- Deprecated feature description

### Removed
- Removed feature description

### Security
- Security fix description
```

## Testing

### Manual Testing

Before submitting:

1. **Test core functionality**
   - Create template
   - Edit with Elementor
   - Embed with shortcode
   - Test Gutenberg block

2. **Test conditional display**
   - Device conditions
   - Role conditions
   - Post type conditions

3. **Test admin UI**
   - Copy shortcode
   - Quick actions
   - Meta boxes

4. **Test edge cases**
   - Invalid template ID
   - Non-existent template
   - Without Elementor
   - With different themes

5. **Test compatibility**
   - Different WordPress versions
   - Different PHP versions
   - Different Elementor versions
   - Common plugins

### Browser Testing

Test in:
- Chrome (latest)
- Firefox (latest)
- Safari (latest)
- Edge (latest)

### Responsive Testing

Test on:
- Desktop (1920x1080)
- Tablet (768x1024)
- Mobile (375x667)

## Commit Messages

Use clear and descriptive commit messages:

**Format:**
```
Type: Brief description

Detailed explanation (if needed)

Fixes #issue-number
```

**Types:**
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting)
- `refactor`: Code refactoring
- `test`: Adding tests
- `chore`: Maintenance tasks

**Examples:**

```
feat: Add template scheduling feature

Added ability to schedule templates to show between specific dates.
Includes new shortcode attributes: start_date and end_date.

Fixes #123
```

```
fix: Resolve shortcode rendering issue on mobile

Fixed bug where shortcodes weren't rendering correctly on mobile
devices due to incorrect device detection logic.

Fixes #456
```

## Version Control

### Branching Strategy

- `main` - Stable release branch
- `develop` - Development branch
- `feature/*` - Feature branches
- `fix/*` - Bug fix branches
- `hotfix/*` - Urgent fixes

### Branch Naming

Use descriptive names:
- `feature/template-scheduling`
- `fix/mobile-rendering`
- `hotfix/security-patch`

## Release Process

1. Update version number in main plugin file
2. Update CHANGELOG.md
3. Update README.md if needed
4. Test thoroughly
5. Create release tag
6. Build release package
7. Deploy to WordPress.org (if applicable)

## Questions?

If you have questions:
- Check existing documentation
- Search closed issues
- Open a new issue with "Question" label
- Email: developers@appsfruit.com

## License

By contributing, you agree that your contributions will be licensed under the GPL v2 or later license.

## Recognition

Contributors will be recognized in:
- CHANGELOG.md
- Plugin credits
- Project documentation

Thank you for contributing! 🎉