# Contributing to MTS Social Auto Post

Thank you for your interest in contributing to MTS Social Auto Post! This document provides guidelines and instructions for contributing.

## Code of Conduct

By participating in this project, you agree to maintain a respectful and inclusive environment. We expect all contributors to:

- Be respectful and considerate in all interactions
- Welcome newcomers and help them learn
- Focus on constructive feedback
- Accept responsibility for mistakes and learn from them

## How to Contribute

### Reporting Bugs

Before submitting a bug report:

1. Check [existing issues](https://github.com/AjeebBhai/mts-social-auto-post/issues) to avoid duplicates
2. Verify the bug exists in the latest version
3. Collect relevant information

When submitting a bug report, include:

- **WordPress version**: (e.g., 6.4.2)
- **PHP version**: (e.g., 8.1)
- **Plugin version**: (e.g., 1.0.0)
- **Steps to reproduce**: Detailed steps to trigger the bug
- **Expected behavior**: What should happen
- **Actual behavior**: What actually happens
- **Error messages**: Any PHP errors or JavaScript console errors
- **Screenshots**: If applicable

Use the bug report template when creating an issue.

### Suggesting Features

We welcome feature suggestions! When proposing a feature:

1. Check if it's already been suggested
2. Explain the use case clearly
3. Describe how it would benefit users
4. Consider potential implementation approaches

### Submitting Pull Requests

1. **Fork the repository** and create your branch from `main`
2. **Set up your development environment** (see below)
3. **Make your changes** following our coding standards
4. **Test thoroughly** on a local WordPress installation
5. **Write clear commit messages**
6. **Submit a pull request** with a detailed description

## Development Environment Setup

### Prerequisites

- PHP 7.4 or higher
- WordPress 5.8 or higher (local installation)
- Composer (for development dependencies)
- Node.js 16+ (if modifying JavaScript/CSS)
- Git

### Local Setup

1. Clone your fork:
   ```bash
   git clone https://github.com/YOUR-USERNAME/mts-social-auto-post.git
   cd mts-social-auto-post
   ```

2. Install development dependencies:
   ```bash
   composer install
   ```

3. Link to your local WordPress installation:
   ```bash
   # Symlink or copy to wp-content/plugins/
   ln -s /path/to/mts-social-auto-post /path/to/wordpress/wp-content/plugins/
   ```

4. Activate the plugin in WordPress admin

### Running Code Quality Checks

```bash
# PHP CodeSniffer (WordPress Coding Standards)
composer run phpcs

# Fix auto-fixable issues
composer run phpcbf

# PHP Static Analysis (if configured)
composer run phpstan
```

## Coding Standards

We follow the [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/).

### PHP Guidelines

- Use tabs for indentation (not spaces)
- Opening braces on the same line
- Space after control structure keywords
- Yoda conditions for comparisons
- Proper PHPDoc blocks for all functions and classes

```php
/**
 * Example function demonstrating coding standards.
 *
 * @since 1.0.0
 * @param int    $post_id Post ID.
 * @param string $message Optional message.
 * @return bool True on success, false on failure.
 */
public function example_function( $post_id, $message = '' ) {
    if ( empty( $post_id ) ) {
        return false;
    }

    // Process the post.
    $result = $this->process( $post_id );

    return true === $result;
}
```

### Security Best Practices

All contributions must follow WordPress security best practices:

- **Sanitize input**: Use appropriate sanitization functions
  - `sanitize_text_field()` for single-line text
  - `sanitize_textarea_field()` for multi-line text
  - `absint()` for integers
  - `sanitize_key()` for keys/slugs

- **Escape output**: Always escape when outputting
  - `esc_html()` for text content
  - `esc_attr()` for attributes
  - `esc_url()` for URLs
  - `wp_kses()` for allowed HTML

- **Verify nonces**: Check nonces for all form submissions
  ```php
  if ( ! wp_verify_nonce( $_POST['nonce'], 'action_name' ) ) {
      wp_die( 'Security check failed' );
  }
  ```

- **Check capabilities**: Verify user permissions
  ```php
  if ( ! current_user_can( 'manage_options' ) ) {
      return;
  }
  ```

- **Prepare SQL queries**: Use `$wpdb->prepare()` for database queries
  ```php
  $wpdb->get_results(
      $wpdb->prepare(
          "SELECT * FROM %i WHERE id = %d",
          $table_name,
          $id
      )
  );
  ```

### JavaScript Guidelines

- Use ES6+ syntax
- Wrap in IIFE to avoid global scope pollution
- Use strict mode
- Document with JSDoc comments

```javascript
/**
 * Handle share button click.
 *
 * @param {Event} e Click event.
 */
sharePost: function( e ) {
    'use strict';
    e.preventDefault();
    // Implementation
}
```

### CSS Guidelines

- Use BEM-like naming convention
- Prefix classes with `mts-sap-`
- Avoid `!important` unless absolutely necessary
- Keep selectors specific but not overly nested

```css
.mts-sap-card {
    background: #fff;
    border-radius: 4px;
}

.mts-sap-card__header {
    padding: 20px;
}

.mts-sap-card--highlighted {
    border-color: #0073aa;
}
```

## Commit Messages

Write clear, descriptive commit messages:

- Use present tense ("Add feature" not "Added feature")
- Use imperative mood ("Fix bug" not "Fixes bug")
- Limit first line to 72 characters
- Reference issues when applicable

**Good examples:**
```
Add token expiry warning notification

Fix SQL injection vulnerability in Logger class

Update Facebook API version to v18.0

Refactor settings validation for better error handling

Closes #42
```

**Bad examples:**
```
fixed stuff
updates
WIP
asdf
```

## Pull Request Process

1. **Create a descriptive PR title** summarizing the change

2. **Fill out the PR template** completely:
   - What does this PR do?
   - Why is this change needed?
   - How was it tested?
   - Related issues

3. **Ensure all checks pass**:
   - PHP CodeSniffer
   - Any automated tests

4. **Request review** from maintainers

5. **Address feedback** promptly and respectfully

6. **Squash commits** if requested before merge

### PR Title Format

Use one of these prefixes:
- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation only
- `style:` Code style/formatting
- `refactor:` Code refactoring
- `test:` Adding/updating tests
- `chore:` Maintenance tasks

Example: `feat: Add bulk share pagination`

## File Structure

```
mts-social-auto-post/
├── admin/                  # Admin-specific functionality
│   ├── css/               # Admin styles
│   ├── js/                # Admin scripts
│   ├── partials/          # Admin template parts
│   └── class-mts-sap-*.php
├── assets/                 # Static assets
│   └── images/
├── docs/                   # Documentation
├── includes/               # Core plugin classes
│   └── class-mts-sap-*.php
├── languages/              # Translation files
├── mts-social-auto-post.php  # Main plugin file
├── uninstall.php           # Cleanup on uninstall
└── readme.txt              # WordPress.org readme
```

## Testing

### Manual Testing Checklist

Before submitting a PR, test:

- [ ] Plugin activates without errors
- [ ] Plugin deactivates cleanly
- [ ] Settings save correctly
- [ ] Auto-share works on publish
- [ ] Manual share works from post list
- [ ] Manual share works from metabox
- [ ] Post log displays correctly
- [ ] Bulk share functions properly
- [ ] Setup wizard completes successfully
- [ ] Token expiry warning displays correctly
- [ ] No PHP warnings or notices
- [ ] No JavaScript console errors

### Browser Testing

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

## Questions?

If you have questions about contributing:

1. Check existing issues and documentation
2. Open a discussion on GitHub
3. Email: info@monirtechsolutions.com

Thank you for contributing!