Development

Step 1: Define Framework and App Versions

Step 2: Identify and Create Custom Apps

• List all custom apps required based on the project scope and FRS.
• Follow the defined custom app naming convention: {client_prefix}_{module_name} (e.g., befree_lending, hmws_fleet).
• Use the standard app structure template for directory layout, hooks.py skeleton, and fixtures setup.

Step 3: Ownership Assignment

• Each custom app is assigned to a specific developer as the primary owner.
• The Tech Lead oversees all apps and is the final approver for merges.

Python Conventions

• snake_case for variables, functions, and file names.
• Type hints for function parameters and return values.
• Docstrings for all public functions and classes.
• Use frappe.throw() for user-facing validations, frappe.log_error() for backend errors.

JavaScript Conventions

• camelCase for variables and functions.
• Use Frappe Client API patterns: frappe.call(), frm.set_value(), frm.set_df_property().
• Never use direct DOM manipulation when a Frappe API exists.

Architecture Rules

• Server scripts over client scripts when business logic must be enforced.
• Custom app development over ERPNext core modifications (upgrade-safe approach).
• Fixtures for custom fields, property setters, and workflows.
• All business logic in controller methods (validate, before_save, on_submit), not in client scripts.

Pre-Development Security Checklist

• Review permission model design before writing code.
• Identify all user-facing APIs and plan permission enforcement.
• Define data access boundaries per role.

Runtime Security Practices

• SQL Injection Prevention: Always use frappe.db parameterised queries. Never concatenate user input into SQL strings.
• Permission Checks: Every whitelisted API must include frappe.has_permission() or @frappe.whitelist(methods=['POST']) with explicit role checks.
• XSS Prevention: Sanitise all user inputs rendered in HTML. Use frappe.utils.escape_html() for output encoding.
• IDOR Prevention: Validate that the current user has access to the requested document before returning data.

API Security Standards

• All APIs must use @frappe.whitelist() decorator with appropriate method restrictions.
• Rate limiting must be configured for public-facing APIs.
• Input validation at the API entry point before processing.

End-to-End Testing Process

• Developer performs unit testing on their branch before raising PR.
• QA creates test cases from FRS acceptance criteria before development starts.
• After PR merge to develop, QA performs functional testing on the dev/stage server.
• Regression testing at sprint end before develop → staging merge.
• UAT with client on staging/UAT server before production deployment.

Automated Test Cases

• Use frappe.tests.utils and unittest for writing test cases.
• Every custom doctype must have at least basic CRUD test cases.
• All business logic functions must have unit tests covering happy path and edge cases.
• Run tests via: bench --site {site} run-tests --app {app_name}.

Manual QA Checklist Per Feature

• Functional correctness against FRS requirements.
• Permission checks for all defined roles.
• Error handling for invalid inputs.
• UI/UX consistency and responsiveness.
• Print format and report accuracy.

Logging Standards

• Use frappe.logger() for structured logging in background jobs and long-running processes.
• Use frappe.log_error() for capturing exceptions with full traceback into the Error Log doctype.
• Never use bare print() statements in production code.
• Log meaningful context: document name, user, operation, and relevant field values.

Error Handling Practices

• All whitelisted APIs and doc_events must have try-except blocks.
• Use frappe.throw() for user-facing validation errors with clear messages.
• Use frappe.log_error() in except blocks to capture unexpected failures.
• Never use bare except: or except Exception: without logging the error.
• For background jobs: log errors and send notifications for critical failures.

Patch & Data Migration Process

• All data migrations use Frappe's patches framework: {app}/patches/{version}/patch_name.py.
• Every patch must include a clear docstring explaining what it does and why.
• Pre-patch validation: Check data state before modifying. Skip gracefully if already applied.
• Rollback strategy: Document manual rollback steps for every destructive patch.
• Post-patch verification: Run bench --site {site} migrate and verify data integrity.
• Register patches in patches.txt in the correct execution order.