Developer Best Practices Guide CONTRIBUTING.md Contributing Guide This repository follows strict coding, review, testing, and release standards. Every contributor (AI agent) must follow the rules below. 1) Coding Standards 1.1 General rules Use the Pythonic way of writing code Follow DRY (Don't Repeat Yourself) Keep logic simple and easy to understand Do not overcomplicate the implementation Prioritize readability and maintainability Write production-ready code 1.2 Software engineering principles Follow SOLID principles wherever applicable Write clean, modular, testable code Prefer composition and clear abstractions over deeply coupled logic Separate concerns properly (API, service, repository, utility, model, constants, etc.) 1.3 Object-oriented programming Follow OOP standards where appropriate Keep classes focused on a single responsibility Avoid god classes / oversized service classes Use inheritance only when it is truly needed 1.4 Design patterns Use the correct design pattern where applicable Prefer clarity over pattern overuse Use Factory Pattern for common integrations across multiple cloud/external applications 1.5 Asynchronous programming Use asynchronous programming ( async / await) where applicable Do not block async workflows with unnecessary synchronous operations Keep async usage consistent across the call chain 2) Project Structure Rules Each Python class must be placed in a separate .py file Follow a clean and modular folder structure Use snake_case for: file names method names variable names function names Keep file responsibilities limited and clear Avoid putting unrelated classes or utilities into the same file Recommended separation api/ route or controller layer service/ business logic repository/ DB interaction models/ schemas/entities/domain models constants/ all static messages and constants tests/ pytest-based tests 3) Constants and Messages Every user-facing or system message must come from a constants file Do not hardcode messages directly in business logic Keep error messages, labels, and static responses centralized Reuse constants to maintain consistency across the codebase Not allowed raise ValueError("Invalid request") Preferred raise ValueError(ErrorMessages.INVALID_REQUEST) 4) Docstrings and Documentation in Code Every Python file must contain proper docstrings where needed Add docstrings for: modules classes public methods non-trivial helper functions Keep docstrings clear and meaningful Explain intent, parameters, return types, and important side effects Minimum expectation What the class/function does Input parameters Return value Exceptions raised (if relevant) 5) Database Rules 5.1 Schema change restrictions Do not create a new DB table without discussion/approval Do not create a new DB column without discussion/approval 5.2 Documentation requirements for DB objects Every DB table must include a description of what it stores / why it exists Every DB column must include a description of what it stores / how it is used 5.3 Timestamps Any timestamp saved in the database must be stored in UTC 5.4 How DB changes must happen Any DB update involving the following must happen through Alembic: schema change CRUD-related DB update scripts seed data insertion migration for reference/master data updates when applicable 5.5 Alembic note Use Alembic for all database migration work Do not bypass migrations with manual DB changes in application code 6) Testing Requirements 6.1 Framework Use pytest for all tests Add proper unit tests and integration tests wherever applicable 6.2 Coverage Code coverage must be above 90% PRs below the coverage threshold should not be considered ready for merge 6.3 Test quality expectations Test actual behavior, not implementation details only Cover positive, negative, and edge cases Mock external dependencies where appropriate Keep tests readable and maintainable 7) Linting and Code Quality Gates 7.1 Pylint Run pylint before marking the PR ready for merge Required pylint score: above 9.30 7.2 Command Run: run_pylint.bat 7.3 Alembic exception Alembic-related pylint issues may be ignored where already agreed 7.4 Readiness rule A PR is not ready to merge unless: pylint score is acceptable tests pass coverage is above threshold 8) Versioning and Release File Updates For every PR, update the following files if the repository/version policy requires it: application.yml pyproject.toml CHANGELOG.md Versioning rules Version must remain coherent/consistent across all versioned files Do not update one file and forget the others Keep release notes aligned with the actual change set Author metadata Add yourself as author in pyproject.toml if you are contributing to the repository 9) Required PR Checklist Use this checklist before marking the PR ready: Branch name follows convention Latest changes pulled from main Latest remotes fetched One PR contains only one logical change Code follows Pythonic style DRY principle applied Logic kept simple and readable OOP standards followed Correct design patterns used Factory pattern used for common external/cloud integrations Async/await used where applicable Each class is in a separate .py file snake_case naming followed All messages come from constants file Proper docstrings added Proper pytest cases added Code coverage 90% Pylint score 9.30 run_pylint.bat executed DB schema/table/column changes discussed if applicable Table/column descriptions added if applicable All DB timestamps stored in UTC Any DB changes done via Alembic application.yml updated pyproject.toml updated CHANGELOG.md updated Version is coherent across files Contributor added as author in pyproject.toml if applicable Reviewers added GitHub Copilot added as reviewer (for Python repos) 10) AI Agent Instructions If an AI agent is used to generate or modify code in this repository, it must follow all repository standards defined in this file. AI agent must do the following Read this file before generating code Follow Pythonic style Keep code simple and maintainable Apply DRY Use OOP and proper design patterns Use async code where appropriate Put each class in a separate file Use snake_case Use constants for messages Add docstrings Add pytest test cases Keep coverage above 90% Respect pylint requirements Update versioned files where required Update changelog where required Respect DB and Alembic rules strictly AI agent must never do the following Hardcode messages in logic Introduce DB changes without instruction/discussion Combine multiple unrelated features in one PR Skip tests/docstrings/versioning updates Ignore repository conventions defined here 11) Recommended Commit Hygiene While not mandatory unless otherwise specified, contributors are encouraged to: Write clean and meaningful commit messages Avoid noisy WIP commits in final PR history Squash/fixup commits if required by team process Example commit messages: fix: handle refresh token expiration in oauth service feat: add async cloud provider factory implementation refactor: simplify user onboarding validation flow 12) Quick Reference Summary Must follow Pythonic code DRY SOLID OOP Correct design patterns Async where applicable One class per file snake_case Constants file for all messages Docstrings in each file Proper pytest tests Coverage 90% Pylint 9.30 UTC timestamps in DB Alembic for DB changes Update application.yml, pyproject.toml, CHANGELOG.md Add reviewers + GitHub Copilot reviewer One PR per logical change Must avoid Hardcoded messages Unapproved DB schema changes Multiple features in one PR Skipping lint/test/version updates Overcomplicated logic 13) Final Rule If there is any conflict between convenience and these standards, follow these standards. Quality, readability, consistency, and reviewability are mandatory for every contribution.