Skip to content

DEV_GUIDE.md

Latest commit

 

History

History
273 lines (217 loc) · 8.38 KB

DEV_GUIDE.md

File metadata and controls

273 lines (217 loc) · 8.38 KB

Development Guide

Table of Contents

Code Review Best Practices

For Reviewers

  1. Be Constructive and Respectful

    • Focus on the code, not the person 🔐
    • Provide clear, actionable feedback 🚧
    • Explain the "why" behind your suggestions
    • Use a positive and encouraging tone 💜

  2. Review Checklist

    • Code follows project style guidelines
    • No obvious bugs or security issues
    • Tests are included and pass
    • Documentation is updated
    • Performance considerations are addressed
    • Error handling is appropriate

  3. Timely Reviews

    • Respond to review requests within 24 hours
    • If you can't review immediately, communicate your timeline
    • Don't let PRs sit idle for extended periods

  4. Focus Areas

    • Functionality: Does it work as intended?
    • Maintainability: Is the code clean and well-structured?
    • Testability: Is it easy to test?
    • Security: Are there any security concerns?
    • Performance: Are there any performance implications?

For Authors

  1. Before Submitting

    • Make a branch and adhere to the naming convention: yourname/issue
    • Self-review your changes
    • Run all tests locally
    • Run the pre-commit checks & formatting!
    • Update documentation!
    • Keep changes focused and manageable -- "MVP-R" what is the minimally viable PR -- would you want to review it?
    • Follow the project's commit message conventions

  2. PR Description

    • Clear title describing the change
    • Detailed description of changes
    • Link to related issues
    • Screenshots for UI changes
    • Testing instructions

Issue Management

Creating Issues

  1. Issue Template

    • Use the provided issue templates
    • Fill out all required sections
    • Be specific and detailed

  2. Issue Types

    • Bug: Describe the current behavior and expected behavior
    • Feature: Explain the use case and benefits
    • Enhancement: Detail the improvement
    • Documentation: Specify what needs to be updated

  3. Issue Content

    • Clear, descriptive title
    • Detailed description
    • Steps to reproduce (for bugs)
    • Expected vs actual behavior
    • Environment details
    • Screenshots/videos when relevant

Managing Issues

  1. Labels

    • Use appropriate labels (bug, enhancement, etc.)
    • Priority labels when necessary
    • Component/area labels

  2. Assignments

    • Assign issues to specific team members
    • Set realistic deadlines
    • Update status regularly

  3. Communication

    • Keep discussions in the issue thread
    • Tag relevant team members
    • Update issue status promptly

Collaborative Coding Guidelines

Each project is different, so please check project-specific guidelines. However, below is a guide for collaborative projects in general. I recommend the following system for within-lab projects that have different levels of maintainers & builders.

Who is developing?

  1. Organize weekly dev meetings
    • Review the current issues, PRs, and major milestones.
    • Self-assessment: are you blocking anyone? If so, work to fix that.
    • No one person is the gate-keeper for the project: work together
  2. Get a review assignment system in place
    • 🟥 Make a flag for major dev/changes: all users of the code should agree and sign off (git reviews), and this includes the PI.
    • 🟧 Make a flag for user-needs: this is needed to stop a block -- it might not be perfect, so make an issue to revisit later. 1 sign off from another user, and go! 🚀
    • 🟩 Make a flag for minor change: not breaking, can be changed later, 1 sign off okay

Git Workflow

  1. Branching Strategy

    • Use feature branches for new work
    • Branch naming convention: name/issue-number-description
      • Example: john/123-add-login-feature
      • Example: sarah/456-fix-navigation-bug
    • Keep branches up to date with main
    • Delete branches after merging

  2. Commits

    • Write clear, descriptive commit messages
    • Keep commits focused and atomic
    • Reference issue numbers in commits
    • Follow conventional commits format

  3. Pull Requests

    • Keep PRs small and focused
    • Update PR description as changes are made
    • Request reviews from appropriate team members
    • Address review comments promptly

Communication

  1. Team Communication

    • Use appropriate channels for different purposes - use basecamp campfire and github issues/PRs
    • Be clear and concise
    • Document important decisions!!
    • Share knowledge and learnings

  2. Code Documentation

    • Document complex logic in the code with comments!
    • Keep README up to date
    • Add inline comments when necessary
    • Document API changes

  3. Knowledge Sharing

    • Share learnings with the team
    • Document common patterns
    • Create and maintain team documentation
    • Regular team sync-ups, organize them!

Development Environment

  1. Setup

    • Document environment setup
    • Use consistent development tools
    • Share configuration/docker files
    • Maintain development dependencies

  2. Local Development

    • Follow our development guidelines
    • Use consistent formatting tools
    • Run tests before committing (see pre-commits)
    • Keep dependencies updated

  3. Code Quality

    • Use our suggeested linters and formatters
    • Follow our style guides

Code Formatting

General Formatting Rules

We use the Google Style Guide: https://google.github.io/styleguide/

  1. Indentation

    • Use 2 spaces for indentation
    • No tabs
    • Maximum indentation level: 4 levels
    • Align with opening delimiter

  2. Line Length

    • Maximum line length: 100 characters
    • Break long lines at logical points
    • Indent continuation lines by 4 spaces
    • Break after operators, not before

  3. Whitespace

    • No trailing whitespace
    • One blank line between functions/classes
    • Two blank lines between major sections
    • No multiple consecutive blank lines
    • Spaces around operators
    • No spaces inside parentheses
    • Spaces after commas and semicolons

  4. Naming Conventions

    • Variables: lower_snake_case
    • Functions: lower_snake_case
    • Classes: PascalCase
    • onstants: UPPER_SNAKE_CASE
    • Files: lower_snake_case.py
    • Private members: _single_leading_underscore
    • Modules/Packages: lower_snake_case
    • Interfaces: PascalCase (same as classes, no special prefix)

  5. Comments

    • Use clear, concise comments
    • Comment complex logic
    • Keep comments up to date
    • Remove commented-out code

  6. Imports/Exports

    • Group imports in the following order:
      1. Third-party imports
      2. Project imports
    • Sort imports by isort within the groups
    • Use named exports
    • Avoid default exports
    • One import per line

  7. Code Organization

    • One class/component per file
    • Group related functionality
    • Keep files focused and manageable
    • Follow the project's file structure
    • RECOMMENDED: Maximum file length: 1000 lines
    • RECOMMENDED: Maximum function length: 50 lines

Automated Formatting

  1. Pre-commit Hooks

    • Run formatters before commit
    • Run linters before commit
    • Check for common issues
    • Ensure consistent formatting
    • Block commits with formatting errors

  2. CI/CD Integration

    • Run formatting checks in pipeline
    • Fail builds on formatting errors
    • Generate formatting reports
    • Enforce style guide compliance
    • Use Google's style guide linters

Google Style Guide Compliance

  1. General Principles

    • Be consistent with existing code
    • Be consistent with Google's style guide
    • Use Google's official linters
    • Follow language-specific style guides
    • Document any style guide exceptions

  2. Code Review Requirements

    • Check style guide compliance
    • Verify formatting is correct
    • Ensure consistent naming
    • Validate documentation
    • Review for best practices

  3. Style Guide Resources

Remember: These guidelines are living documents. Feel free to suggest improvements and updates as the team evolves and learns.