Quality‐Driven Development & Contribution - CApy-RPI/app GitHub Wiki

Quality-Driven Development

This development approach emphasizes meeting strict quality gates before considering any task or feature "done." It integrates principles from several established methodologies, ensuring robust, maintainable, and error-free code.

1. Key Principles

  1. Test-Driven Development (TDD):

    • Writing automated tests before implementing the code.
    • Ensures functionality meets requirements from the start.
    • Emphasizes "all tests must pass" as a non-negotiable requirement.

  2. Continuous Integration/Continuous Deployment (CI/CD):

    • Every change to the codebase passes through automated pipelines for testing, linting, and type checks.
    • Ensures consistent code quality and reduces integration issues.

  3. Static Typing and Code Quality Enforcement:

    • Tools like mypy (type checking), flake8 or pylint (linting), and black (code formatting) are enforced.
    • Guarantees code is type-safe, well-formatted, and adheres to coding standards.

  4. Definition of Done (DoD):

    • Establishes a clear checklist to define when a task or feature is complete.
    • Tasks must:
      • Pass all automated tests.
      • Validate linting rules.
      • Enforce typing with no errors.
    • Prevents incomplete or low-quality code from being merged or deployed.

2. Quality-Driven Development Practices

  • Prioritizing Quality Gates: Quality gates (tests, linting, typing) are prerequisites for task completion.
  • Clean Code Development: Clean, maintainable, and validated code is enforced in every step of the workflow.
  • Best Practices-Driven Development: Industry standards like TDD, CI/CD, and static typing are integrated to ensure robustness.

3. Benefits of This Approach

  • Error Prevention: Automated gates catch issues early in the development process.
  • Consistency: Linting and typing ensure code adheres to a uniform style and standard.
  • Robustness: Passing tests and type checks reduces bugs and increases confidence in the code.
  • Maintainability: Clean, well-tested code is easier to understand and extend in the future.

4. AI in Quality-Driven Development

The use of AI is not only allowed but also encouraged. AI tools can assist in:

  • Debugging: Identifying and resolving issues quickly.
  • Code Suggestions: Accelerating development by generating code snippets and tests.
  • Research Assistance: Streamlining research into best practices and tools.

However, we maintain high standards for students' ability to debug and research issues independently. All development practices must be met before marking a task as done. If any criteria are unmet, we will work with the developer to review and improve the work.

5. Pre-Push Checklist

Before pushing your code to the repository, ensure the following steps are completed:

5.1. Code Formatting with Black

  • Use black to automatically format your code files:
# Install black if not already installed
pip install black

# Format your code files
black path/to/your/code/file.py

5.2. Linting with Flake8

  • Use flake8 to check for style guide enforcement and code quality issues in your code files:
# Install flake8 if not already installed
pip install flake8

# Run flake8 on your code files
flake8 path/to/your/code/file.py

5.3. Type Checking with Mypy

  • Use mypy for static type checking in your code files:
# Install mypy if not already installed
pip install mypy

# Run mypy on your code files
mypy path/to/your/code/file.py

5.4. Running Tests with Pytest

  • Use pytest for running unit tests:
# Install pytest if not already installed
pip install pytest

# Run all tests
pytest

5.5. Creating Branch

  • Ensure that you are checked out of the develop branch

  • On Linear, select which issue you are working on and do

    • Command/Ctrl + Shift + "."

    This copies the branch name template that you have to use on your created branch

    feature/cap-[ISSUE_NUM]

  • Run this command, ensuring that you are using the specified branch name template. Make sure that you append an issue title at the end of the name as well:

    git checkout -b feature/cap-[ISSUE_NUM]-["Issue Title"]

  • Examples of this:

    feature/cap-123-add-user-auth
feat/cap-234-search-api
fix/cap-301-fix-login-redirect
hotfix/cap-999-prod-crash
refactor/cap-444-clean-auth-flow
test/cap-555-add-unit-tests
docs/cap-777-update-readme
release/1.2.0

5.6. Pushing to the Repository

  • Ensure all tests pass and code is properly formatted and linted before pushing:
# Add changes to the staging area
git add .

# Commit changes with a descriptive message
git commit -m "[Description of changes]"

# Push changes to the repository
git push origin [branch-name]
  • Use descriptive commit messages:
[Feature] Add user profile creation functionality
[Refactor] Moving utility method to module
[Fix] Resolve MongoDB connection issue

6. Pull Request Guidelines

  • Include a clear description of changes.
  • Link to relevant issues.
  • Request at least one reviewer for approval.