Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
330 lines (254 loc) · 8.54 KB

CONTRIBUTING.md

File metadata and controls

330 lines (254 loc) · 8.54 KB

Contributing to EZCONTACTFORM Widget

First off, thank you for considering contributing to the EZCONTACTFORM Widget! It's people like you that make this project such a great tool.

Table of Contents

Code of Conduct

This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code.

Security Policy

If you discover a security vulnerability, please follow our Security Policy instead of opening a public issue.

Getting Started

Development Setup

  1. Fork the repository

    Click the "Fork" button on GitHub to create your own copy of the repository.

  2. Clone your fork

    git clone https://github.com/YOUR_USERNAME/widget.git
cd widget

  3. Install dependencies

    npm install

  4. Start a local server

    # Using Python
python -m http.server 3000

# Using Node.js
npx http-server -p 3000

# Using PHP
php -S localhost:3000

  5. Open the example file

    Navigate to http://localhost:3000/src/widget-example.html in your browser.

Project Structure

widget/
├── src/
│   ├── widget.js           # Main widget source
│   ├── widget.css          # Widget styles
│   ├── ezform.js           # EZForm library
│   └── widget-example.html # Example implementations
├── dist/                   # Built distribution files (generated)
├── test/                   # Test files
│   ├── conditional-logic.test.js
│   ├── field-types.test.js
│   ├── localization.test.js
│   └── validation.test.js
├── docs/                   # Documentation
├── build.cjs               # Build script
├── package.json            # Package configuration
└── README.md               # Project documentation

How to Contribute

Reporting Bugs

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

When reporting bugs, include:

  • Clear, descriptive title
  • Steps to reproduce - Be specific and include code samples if possible
  • Expected behavior - What you expected to happen
  • Actual behavior - What actually happened
  • Environment details:
    • Browser name and version
    • Operating system
    • Widget version
    • Any relevant console errors

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. See error

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

**Screenshots**
If applicable, add screenshots.

**Environment:**
 - OS: [e.g., macOS 14.0]
 - Browser: [e.g., Chrome 120]
 - Widget Version: [e.g., 1.11.0]

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

Suggesting Features

We love feature suggestions! Please check existing issues first to see if your idea has already been discussed.

When suggesting features, include:

  • Clear, descriptive title
  • Problem statement - What problem does this solve?
  • Proposed solution - How would it work?
  • Alternatives considered - Other approaches you've thought about
  • Additional context - Examples, mockups, or references

Submitting Pull Requests

  1. Fork and clone the repository
  2. Create a branch for your changes: 
    git checkout -b feature/amazing-feature
# or
git checkout -b fix/bug-description
  3. Make your changes and test thoroughly
  4. Run the tests: 
    npm test
  5. Build and verify: 
    npm run build
  6. Commit your changes with a clear message: 
    git commit -m "Add amazing feature"
  7. Push to your fork: 
    git push origin feature/amazing-feature
  8. Open a Pull Request on GitHub

Pull Request Guidelines:

  • Fill out the PR template completely
  • Reference any related issues
  • Include screenshots for UI changes
  • Update documentation if needed
  • Ensure all tests pass
  • Keep changes focused and atomic

Development Guidelines

Code Style

  • Follow existing patterns - Match the style of surrounding code
  • Use meaningful names - Variables and functions should be self-documenting
  • Add comments - Explain complex logic, not obvious code
  • Keep functions small - Each function should do one thing well
  • No trailing whitespace - Clean up before committing
  • Use 2-space indentation - Consistent with the project

JavaScript Guidelines:

// Good: Descriptive function name, clear purpose
function validateEmailField(field, value) {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(value);
}

// Good: Comment explaining non-obvious logic
// Debounce validation to avoid excessive API calls
const debouncedValidate = debounce(validate, 300);

CSS Guidelines:

/* Good: Use the .ezform- prefix for all classes */
.ezform-field {
  margin-bottom: 1rem;
}

/* Good: Group related properties */
.ezform-button {
  /* Positioning */
  display: inline-flex;
  align-items: center;
  
  /* Box model */
  padding: 0.75rem 1.5rem;
  border: none;
  border-radius: 4px;
  
  /* Typography */
  font-size: 1rem;
  font-weight: 500;
  
  /* Visual */
  background: var(--ezform-primary);
  color: white;
  
  /* Misc */
  cursor: pointer;
  transition: background 0.2s;
}

Testing

  • Run existing tests before submitting: 
    npm test
  • Add tests for new features
  • Test in multiple browsers - Chrome, Firefox, Safari, Edge
  • Test responsive behavior - Desktop and mobile
  • Test accessibility - Keyboard navigation, screen readers

Commit Messages

Write clear, concise commit messages:

# Good examples
Add phone number validation for UK format
Fix form submission on Safari mobile
Update README with new configuration options

# Bad examples
Fixed stuff
WIP
asdf

Commit message format:

<type>: <short description>

<optional longer description>

<optional footer with issue references>

Types:

  • feat: - New feature
  • fix: - Bug fix
  • docs: - Documentation changes
  • style: - Code style changes (formatting, etc.)
  • refactor: - Code changes that neither fix bugs nor add features
  • test: - Adding or updating tests
  • chore: - Maintenance tasks

Areas for Contribution

We especially welcome contributions in these areas:

Area Description
🐛 Bug Fixes Fix reported issues
✨ New Field Types Add support for new input types
🌍 Internationalization Add phone/country support for more regions
♿ Accessibility Improve WCAG compliance and screen reader support
📱 Mobile Optimize touch interactions and mobile UX
🎨 Themes Create new themes or improve existing ones
📚 Documentation Improve guides, examples, and API docs
🧪 Testing Increase test coverage
⚡ Performance Optimize bundle size and runtime performance

Self-Hosting / Forking

If you want to fork this project and host your own version:

  1. Fork the repository
  2. Set up your own CDN (Cloudflare R2, AWS S3, or any static host)
  3. Configure deployment:
    • Remove or update .github/workflows/release.yml with your credentials
  4. Build and deploy: 
    npm run build
# Upload dist/ to your CDN
  5. Update API endpoints (optional): 
    // Before loading the widget
window.EZFORM_CONFIG = { apiBase: 'https://your-api.com' };

Questions?

Need help? Here's how to reach us:

Thank you for contributing! 🎉