Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
317 lines (220 loc) · 8.79 KB

CONTRIBUTING.md

File metadata and controls

317 lines (220 loc) · 8.79 KB
Raw

Contributing to Free Gift Coupons Bulk Coupon Generator

Thank you for considering contributing to Free Gift Coupons Bulk Coupon Generator! This document provides guidelines and instructions for contributors.

Code of Conduct

This project follows the WordPress Community Code of Conduct. By participating, you're expected to uphold this code.

Development Environment

Requirements

  • PHP: 8.2 or higher
  • WordPress: 6.8 or higher
  • WooCommerce: Required for plugin functionality
  • Free Gift Coupons for WooCommerce: Required for end-to-end free gift coupon behavior
  • Composer: For dependency management
  • Node.js: 16+ (if working with build tools)
  • Git: For version control

Setup

  1. Fork the repository on GitHub

  2. Clone your fork locally:

    git clone https://github.com/YOUR-USERNAME/free-gift-coupons-bulk-coupons-generator.git
cd free-gift-coupons-bulk-coupons-generator

  3. Install dependencies:

    composer install

  4. Create a feature branch:

    git checkout -b feature/your-feature-name

Coding Standards

WordPress Coding Standards

This project adheres to WordPress Coding Standards:

Key Principles

  1. Security First: All code must follow OWASP security guidelines

    • Input validation and sanitization
    • Output escaping with context-appropriate functions
    • CSRF protection with nonces
    • Capability checks for admin functions

  2. Performance: Optimize for efficiency

    • Use WordPress caching mechanisms
    • Minimize database queries
    • Conditional loading of assets

  3. Internationalization: All user-facing strings must be translatable

    • Use __(), _e(), esc_html__(), esc_html_e() functions
    • Text domain: free-gift-bulk-coupon-generator

  4. Accessibility: Follow WCAG guidelines

    • Proper semantic markup
    • Keyboard navigation support
    • Screen reader compatibility

Code Quality Tools

PHP CodeSniffer (PHPCS)

Run coding standards checks:

composer run phpcs

PHPStan

Run static analysis:

composer run phpstan

PHPUnit

Run tests (when available):

composer test

File Structure

free-gift-bulk-coupon-generator/
|-- free-gift-bulk-coupon-generator.php # Main plugin file
|-- includes/                           # Plugin source files
|-- assets/                             # Admin CSS and JavaScript
|-- README.md                           # Project documentation
|-- readme.txt                          # WordPress.org readme
|-- CHANGELOG.md                        # Version history
|-- CONTRIBUTING.md                     # This file
|-- LICENSE                             # GPL license
|-- composer.json                       # PHP dependencies
|-- phpcs.xml                           # PHPCS configuration
|-- phpstan.neon                        # PHPStan configuration
|-- phpmd.xml                           # PHPMD configuration
|-- languages/                          # Translation files
|   `-- free-gift-bulk-coupon-generator.pot
`-- .github/                            # GitHub workflows
    `-- workflows/

Making Changes

Before You Start

  1. Check existing issues and pull requests
  2. Create an issue for significant changes to discuss the approach
  3. Follow the existing code patterns and conventions

Code Requirements

Security

  • Input Validation: Validate all user inputs
  • Output Escaping: Use esc_html(), esc_attr(), esc_url() as appropriate
  • Sanitization: Use sanitize_text_field(), sanitize_textarea_field(), etc.
  • Nonce Verification: Protect forms with WordPress nonces
  • Capability Checks: Verify user permissions with current_user_can()

Documentation

  • PHPDoc: All functions must have PHPDoc comments
  • @since: Include version tags for new functions
  • Inline Comments: Explain complex logic
  • Security Notes: Document security measures taken

Example Function

/**
 * Example function with proper documentation
 *
 * @since 1.5.13
 * @param string $input User input to process.
 * @return string Sanitized output.
 */
function fgcbg_example_function( $input ) {
    // Security: Validate and sanitize input.
    if ( ! current_user_can( 'manage_options' ) ) {
        return '';
    }

    $sanitized = sanitize_text_field( $input );

    // Additional processing.

    return esc_html( $sanitized );
}

Testing

  1. Manual Testing:

    • Test in WordPress 6.8+ and the latest version
    • Test with PHP 8.2 and 8.3+ for development tooling
    • Verify admin interface functionality
    • Verify WooCommerce coupon creation and Free Gift Coupons metadata

  2. Automated Testing:

    • Run PHPCS for coding standards
    • Run PHPStan for static analysis
    • Ensure CI/CD tests pass

Performance Guidelines

  1. Batch Generation: Keep coupon creation server-friendly and bounded
  2. Conditional Loading: Only load admin assets on the generator screen
  3. Database Queries: Minimize WooCommerce product and coupon lookups
  4. Hook Priority: Use appropriate hook priorities

Submitting Changes

Pull Request Process

  1. Create Feature Branch:

    git checkout -b feature/description-of-change

  2. Make Changes:

    • Follow coding standards
    • Add/update tests if applicable
    • Update documentation

  3. Test Changes:

    composer run phpcs
composer run phpstan

  4. Commit Changes:

    git add .
git commit -m "feat: add coupon generation option"

  5. Push and Create PR:

    git push origin feature/description-of-change

Commit Message Format

Use Conventional Commits:

  • feat: New features
  • fix: Bug fixes
  • docs: Documentation changes
  • style: Code style changes
  • refactor: Code refactoring
  • test: Test additions/changes
  • chore: Maintenance tasks

Examples:

feat: add coupon prefix validation
fix: preserve free gift coupon metadata
docs: update installation instructions
style: fix PHPCS formatting violations

Pull Request Checklist

  • Code follows WordPress coding standards
  • All functions have proper PHPDoc documentation
  • Security best practices implemented
  • PHPCS and PHPStan checks pass
  • Manual testing completed
  • Documentation updated if needed
  • CHANGELOG.md updated

Version Management

Updating Versions

When releasing new versions, update these files:

  • free-gift-bulk-coupon-generator.php (plugin header)
  • README.md
  • readme.txt
  • CHANGELOG.md
  • languages/free-gift-bulk-coupon-generator.pot

Semantic Versioning

This project follows Semantic Versioning:

  • MAJOR: Breaking changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes (backward compatible)

Support Channels

Resources

WordPress Development

Security Resources

Tools

License

By contributing to Free Gift Coupons Bulk Coupon Generator, you agree that your contributions will be licensed under the GPL-3.0-or-later license.

Thank you for contributing to Free Gift Coupons Bulk Coupon Generator!