Skip to main content

Development Guide

This guide outlines the development workflow, processes, and best practices for contributing to the Wrkbelt platform.

Development Setup​

Environment Files​

To run the project locally, you'll need two environment files:

  • apps/ui/.env - Environment variables for the UI application
  • apps/api/.env - Environment variables for the API application
Obtaining Environment Files

Contact Spencer Marx to receive the current environment files. These files contain sensitive information and should not be committed to the repository.

Project Organization​

For details on code structure and organization standards, please refer to our Coding Standards documentation.

Development Workflow​

Kanban Board​

We use Jira to track our work. Access our current release board here:

Git Workflow​

Our Git workflow differs based on our release phase:

Pre-Release of V0.0.1​

Trunk-Based Development (Simplified)
  • Release Branch: main
  • Feature Flags: Not yet required
  • Deployment Control: Manual via Netlify & GitHub Actions
  • Version Tracking: Git tags

Post-Release of V0.0.1​

GitFlow-Inspired Model
  • New Features:
    • Branch from develop
    • Branch naming: feat/WEN-123-feature-description
    • Use Feature Flags for gating new functionality
  • Release Branch: main (protected)
  • Staging Deployments:
    • Create release/vX.Y.Z-rc branch from develop
    • Merge to main for deployment

PR Process​

Our pull request process remains consistent across both workflow models:

PR Guidelines
  • One PR per Jira ticket (1:1 relationship)
  • If a PR becomes too large, contact Spencer Marx to help break down the work
  • Every PR requires a code review
    • Pre-V0.0.1: Spencer Marx is the permanent code reviewer
    • Post-V0.0.1: Any engineer's review is acceptable
  • Merge to the appropriate branch upon approval

Commit Standards​

We strive for atomic commits that:

  • Address a single concern
  • Have clear, descriptive messages
  • Are small enough to be easily reviewed
  • Allow for straightforward rollback if needed

Feature Flags​

We use Flagsmith to manage feature flags across our application.

Setup​

To work with feature flags:

  1. Request an invite link from Spencer Marx to access our Flagsmith instance
  2. Consider the default state for features when flags are unavailable
  3. Plan flag values for different environments (Local, Develop, Staging, Production)
Implementation Details

Feature flags are implemented differently in the UI and API components. Please refer to the UI-specific and API-specific documentation for implementation details.

Process​

For Release V0.0.1 and beyond:

  • Feature flags must be requested in advance in the relevant Jira ticket
  • If no feature flag is requested in a ticket, none is needed
  • Always implement fallback behavior in case the flag service is unavailable
  • Consider environment-specific values for each flag

Visual Documentation​

For complex UX flows or bug reporting, we encourage the use of screen recordings.

Loom is our recommended tool for creating screen recordings.

Usage Guideline

The free version of Loom limits videos to 5 minutes. Keep your recordings concise and focused on the specific flow or issue you're documenting.

Quick Summary of Best Practices​

  • Follow our Coding Standards for consistent code quality
  • Create atomic, focused commits with clear messages
  • Include appropriate tests with all changes
  • Document new features, APIs, or significant changes
  • Use feature flags for controlled rollout of new functionality