GitHub

Development Workflow

A systematic approach to building, reviewing, and shipping code at Orcta.

Core Workflow

1. Start with Why

Every feature begins with understanding the user need or pain point being addressed.

Before writing code, clarify the problem space. Link to the relevant issue or ticket. If none exists, document the user story or requirement first.

Reference: Engineering Philosophy, Section 3

2. Design Before Implementation

Think through architecture and approach before the first line of code.

For small changes, outline your approach in comments or notes. For larger features, write a brief design document or create a diagram. Share with the team for early feedback.

Reference: Engineering Philosophy, Section 3

3. Build Simple, Then Abstract

Start with the simplest implementation that solves the problem.

Avoid premature optimization or abstraction. If you find yourself building for hypothetical future requirements, step back and focus on the current need. Abstractions emerge naturally after patterns repeat.

Reference: Engineering Philosophy, Section 2

4. Test Your Implementation

Write tests that validate both happy paths and edge cases.

Unit tests for business logic are required. Integration tests for user-facing features are expected. Aim for 80% coverage on core services. Run tests locally before committing.

Reference: Engineering Playbook, Section 7

5. Refactor as You Go

Improve code quality incrementally rather than accumulating technical debt.

When you encounter duplicated code, unclear naming, or confusing logic, fix it immediately. The best time to refactor is when the context is fresh in your mind.

Reference: Engineering Philosophy, Section 3

6. Submit for Review

Create a pull request with clear description and context.

Use the PR template. Include what changed, why it changed, and how to test. Link to related issues. Add screenshots for UI changes. Request review from at least one team member.

Reference: Engineering Playbook, Section 5

7. Address Feedback

Engage with reviewer comments thoughtfully and promptly.

Respond to all feedback within 24 hours. If you disagree with a suggestion, explain your reasoning. Make requested changes or discuss alternatives. Reviews are collaborative, not adversarial.

Reference: Engineering Playbook, Section 5

8. Monitor After Deploy

Track your changes in production to catch issues early.

After merging, monitor logs and metrics for at least one hour. Set up relevant alerts if needed. If issues arise, address them quickly or revert. Ownership extends beyond the merge button.

Reference: Engineering Playbook, Section 6

Deployment Environments

Development → Staging → Production

  • Development: Active development and testing
  • Staging: Pre-production validation
  • Production: Live user traffic

Every change flows through all three environments. Deploy to development freely for testing. Deploy to staging after tests pass. Deploy to production only with tech lead approval after staging validation.

Reference: Engineering Playbook, Section 6

Code Review Principles

Focus on Clarity

Code should be understandable by someone unfamiliar with the context. Prioritize readability over cleverness.

Assume Positive Intent

Approach reviews collaboratively. Authors did their best. Reviewers want to help improve the code.

Be Specific

Vague feedback like “this could be better” is not helpful. Point to specific lines and suggest concrete improvements.

Ask Questions

When uncertain about an approach, ask why rather than demanding changes. Understanding comes first.

Reference: Engineering Playbook, Section 5

Pre-Submission Checklist

  • All tests pass locally
  • Linter shows no errors
  • Code follows naming conventions
  • New functionality includes tests
  • Documentation updated where relevant
  • No secrets or credentials committed
  • Commit messages are descriptive
  • PR description explains what and why

Reference: Engineering Playbook, Section 5.2

Naming Conventions

JavaScript & TypeScript

  • Variables: camelCase
  • Functions: camelCase
  • Components: PascalCase
  • Constants: SCREAMING_SNAKE_CASE
  • Files: kebab-case

Python

  • Variables: snake_case
  • Functions: snake_case
  • Classes: PascalCase
  • Constants: SCREAMING_SNAKE_CASE
  • Files: kebab-case

Go

  • Variables: camelCase
  • Exported Types: PascalCase
  • Packages: lowercase
  • Files: kebab-case

Reference: Naming Conventions Guide, Section 2

Edit this page