🎯 Frappe Coding Standards

A comprehensive package for enforcing coding standards in Frappe Framework projects. This package provides pre-commit hooks, custom scripts, and GitHub Actions workflows to maintain consistent, secure, and high-quality code across your Frappe applications.

✨ Features

• 🔧 Pre-commit hooks for automatic code quality checks
• 🛡️ Security checks for SQL injection prevention and sensitive data encryption
• 🌐 Translation wrapper validation for internationalization
• 📏 Coding standards enforcement (function length, indentation, naming conventions)
• 📝 DocType naming convention checks
• ⚙️ GitHub Actions workflows for CI/CD integration
• 💻 VS Code configuration for optimal development experience
• 🎨 Automatic code formatting with Black, Prettier, and isort

🚀 Quick Start

Installation

# Install the package
pip install frappe-coding-standards

# Initialize in your Frappe project
cd /path/to/your/frappe-project
frappe-standards init

That's it! Your project now has comprehensive coding standards set up.

What Gets Installed

• ✅ .pre-commit-config.yaml - Pre-commit configuration with Frappe-specific hooks
• ✅ .flake8 - Python linting configuration
• ✅ .prettierrc - JavaScript/CSS formatting configuration
• ✅ pyproject.toml - Python project configuration
• ✅ scripts/ - Custom Frappe coding standards check scripts
• ✅ .github/workflows/ - GitHub Actions for automated quality checks
• ✅ .vscode/settings.json - VS Code configuration (optional)

📖 Usage

CLI Commands

# Initialize coding standards in current project
frappe-standards init

# Update to latest configuration
frappe-standards update

# Run coding standards checks
frappe-standards check

# Run checks on specific files
frappe-standards check --files file1.py file2.js

# Run on all files
frappe-standards check --all-files

# Show setup status
frappe-standards status

# Setup only GitHub Actions (skip other configs)
frappe-standards setup-github

Manual Pre-commit Usage

# Run all hooks on all files
pre-commit run --all-files

# Run hooks on staged files only
pre-commit run

# Run specific hook
pre-commit run black
pre-commit run frappe-coding-standards

# Skip hooks for emergency commits
git commit -m "Emergency fix" --no-verify

🔍 Coding Standards Enforced

🌐 Internationalization

All user-facing strings must be wrapped in translation functions:

# ❌ Wrong
frappe.msgprint("Document saved successfully")

# ✅ Correct  
frappe.msgprint(_("Document saved successfully"))

// ❌ Wrong
frappe.msgprint("Document saved successfully");

// ✅ Correct
frappe.msgprint(__("Document saved successfully"));

🛡️ Security Best Practices

SQL Injection Prevention:

# ❌ Wrong - SQL injection vulnerability
frappe.db.sql("SELECT * FROM tabUser WHERE name = '{}'".format(user_name))

# ✅ Correct - Parameterized query
frappe.db.sql("SELECT * FROM tabUser WHERE name = %s", user_name)

Data Encryption:

# ❌ Wrong - Plain text sensitive data
frappe.db.set_value("User", user_name, "api_key", plain_password)

# ✅ Correct - Encrypted sensitive data
encrypted_password = frappe.utils.password.encrypt(password)
frappe.db.set_value("User", user_name, "api_key", encrypted_password)

📏 Code Structure

Function Length:

• Functions should be ≤20 lines
• Each function should have a single responsibility
• Break complex functions into smaller, focused functions

Indentation:

• Use tabs (not spaces) for indentation
• Maintain consistent indentation across Python and JavaScript

Naming Conventions:

# DocType Names - Title Case with Spaces
"Sales Order", "Purchase Invoice", "Item Price"

# Field Names - snake_case
"customer_name", "item_code", "posting_date"

# Function Names - snake_case  
def validate_customer_details(self):
    pass

def calculate_total_amount(self):
    pass

⚙️ GitHub Actions Integration

The package automatically sets up GitHub Actions workflows:

Code Quality Workflow (.github/workflows/code-quality.yml)

• Runs on every PR and push to main branches
• Executes all pre-commit hooks
• Performs Frappe-specific security and standards checks
• Comments on PRs with helpful feedback if checks fail

Frappe Tests Workflow (.github/workflows/frappe-tests.yml)

• Sets up complete Frappe environment
• Runs Python and JavaScript tests
• Includes database and Redis services
• Validates app installation and functionality

Branch Protection

To fully enforce coding standards, set up branch protection rules:

1. Go to Repository Settings → Branches
2. Add protection rule for main/develop branches:
   • ✅ Require status checks to pass before merging
   • ✅ Select "Code Quality Checks" workflow
   • ✅ Require up-to-date branches
   • ✅ Include administrators

🛠️ Configuration Options

Initialization Options

# Full setup (recommended)
frappe-standards init

# Skip GitHub Actions setup
frappe-standards init --no-github

# Skip VS Code configuration
frappe-standards init --no-vscode

# Force overwrite existing files
frappe-standards init --force

# Skip interactive prompts
frappe-standards init --no-vscode --no-github --force

Pre-commit Configuration

The package includes sensible defaults, but you can customize .pre-commit-config.yaml:

repos:
  # Add your custom hooks here
  - repo: local
    hooks:
      - id: custom-check
        name: Custom Project Check
        entry: python scripts/custom_check.py
        language: system
        files: \.py$

🎯 Best Practices

Development Workflow

1. Install standards early in your project lifecycle
2. Run checks locally before pushing: pre-commit run --all-files
3. Fix issues immediately rather than accumulating technical debt
4. Update regularly: frappe-standards update

Team Setup

1. Document the setup in your project README
2. Include in onboarding for new developers
3. Set up branch protection to enforce standards
4. Regular reviews of coding standards compliance

Performance Tips

# Cache pre-commit environments for faster execution
export PRE_COMMIT_HOME=~/.cache/pre-commit

# Run only on changed files during development
pre-commit run

# Full check before important commits
pre-commit run --all-files

📊 Supported File Types

File Type	Checks Applied
Python (.py)	Black formatting, isort imports, flake8 linting, function length, naming conventions, SQL security, translation wrappers
JavaScript (.js)	Prettier formatting, translation wrappers, basic syntax
JSON (.json)	Prettier formatting, DocType naming conventions, syntax validation
CSS/SCSS	Prettier formatting, consistent styling
YAML (.yml/.yaml)	Prettier formatting, syntax validation
Markdown (.md)	Prettier formatting, consistent documentation style

🔧 Troubleshooting

Common Issues

Pre-commit hooks not running:

# Reinstall hooks
pre-commit clean
pre-commit install

Import errors in scripts:

# Ensure package is installed
pip install frappe-coding-standards

# Update to latest version
pip install --upgrade frappe-coding-standards

GitHub Actions failing:

# Check workflow syntax
cd .github/workflows
yamllint code-quality.yml

Getting Help

1. Check the status: frappe-standards status
2. Review logs: Look at pre-commit or GitHub Actions logs
3. Update package: pip install --upgrade frappe-coding-standards
4. Reset configuration: frappe-standards init --force

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

# Clone the repository
git clone https://github.com/dhwani-ris/frappe_coding_standards.git
cd frappe_coding_standards

# Install in development mode
pip install -e .

# Install development dependencies
pip install -e .[dev]

# Run tests
pytest

# Test CLI locally
frappe-standards --help

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

📈 Changelog

v1.0.0 (2025-07-17)

• ✨ Initial release
• 🔧 Complete pre-commit hooks setup
• 🛡️ Security checks for SQL injection and encryption
• 🌐 Translation wrapper validation
• 📏 Comprehensive coding standards enforcement
• ⚙️ GitHub Actions integration
• 💻 VS Code configuration
• 📖 Complete documentation and CLI tool

---

Ready to maintain high-quality Frappe code? Install frappe-coding-standards today! 🚀