Development Protocol

Table of Contents

  1. Overview

  2. Repository Structure

  3. Development Workflow

  4. Pull Request Process

  5. Code Quality Standards

  6. Security Considerations

  7. Release Management

  8. Issue Management

  9. Communication Guidelines

  10. Additional Best Practices

  11. Enforcement

  12. Questions and Support

Overview

This guide establishes the development protocols and best practices for contributing to the Striae project. Following these guidelines ensures code quality, security, and maintainability while facilitating effective collaboration among contributors.

👥 Developer Types: This guide covers protocols for both internal developers (with team access) and external contributors (community members).

Repository Structure

The Striae project uses different repository access patterns depending on your developer status:

For External Contributors:

  • Production Repository: striae-org/striae (fork this to your account)

  • Your Fork: your-username/striae (where you make changes)

  • Contribution Flow: Your Fork → Pull Request to striae-org/striae

For Internal Developers:

  • Development Repository: striae-org/striae-dev (direct access)

  • Production Repository: striae-org/striae (for reference)

  • Contribution Flow: Branch in striae-org/striae-dev → Pull Request within same repo

Development Workflow

Fork Management

For External Contributors:

  1. Fork the Repository: Fork striae-org/striae to your GitHub account

  2. Clone Your Fork: Work from your personal fork

  3. Keep Updated: Regularly sync your fork with the upstream repository

# Initial setup
git clone https://github.com/YOUR_USERNAME/striae.git
cd striae

# Add upstream remote (one-time setup)
git remote add upstream https://github.com/striae-org/striae.git

# Sync your fork regularly
git fetch upstream
git checkout master
git merge upstream/master
git push origin master

For Internal Developers:

  1. Direct Access: Clone striae-org/striae-dev directly (no forking needed)

  2. Branch-Based Workflow: Create feature branches within the shared repository

  3. Keep Updated: Regularly pull latest changes from the development repository

# Clone the development repository
git clone https://github.com/striae-org/striae-dev.git
cd striae-dev

# Stay updated
git checkout master
git pull origin master

Branch Strategy

Universal Guidelines (Both Developer Types):

  1. Feature Branches: Create descriptive feature branches from the latest master branch

  2. Branch Naming: Use descriptive names following the pattern:

    • feature/feature-name

    • bugfix/issue-description

    • hotfix/critical-fix

    • docs/documentation-update

For External Contributors:

# Branch creation in your fork
git checkout master
git pull upstream master
git checkout -b feature/user-authentication-improvements

For Internal Developers:

# Branch creation in shared repository
git checkout master
git pull origin master
git checkout -b feature/user-authentication-improvements

Development Environment Setup

External Contributors:

  • Must set up their own Cloudflare services (Pages, Workers, KV, R2, Images, Turnstile)

  • Must configure their own Firebase project with authentication

  • Must obtain their own SendLayer API key

  • Must manually configure all environment variables and config files

  • Follow the complete installation guide

Internal Developers:

  • Receive access to shared Cloudflare services (no separate setup needed)

  • Use pre-configured Firebase authentication and MFA

  • Access to shared SendLayer API service

  • Receive complete .env files and configuration files

  • Can skip most installation steps and focus on development

Commit Guidelines

  1. Commit Frequency: Commit often with logical, atomic changes

  2. File Limit: Avoid modifying more than 5 files per commit when possible

  3. Commit Messages: Use clear, descriptive commit messages following conventional commit format:

type(scope): brief description

Detailed explanation of what changed and why

Commit Types:

  • feat: New feature

  • fix: Bug fix

  • docs: Documentation changes

  • style: Code style changes (formatting, etc.)

  • refactor: Code refactoring

  • test: Adding or updating tests

  • chore: Maintenance tasks

Examples:

feat(auth): implement multi-factor authentication support

Add MFA functionality with TOTP support and backup codes.
Includes user settings UI and Firebase integration.

fix(canvas): resolve annotation positioning

Fixes issue where touch events were incorrectly calculated
on devices with different pixel densities.

Pull Request Process

PR Requirements

For External Contributors:

  1. Target Repository: Submit pull requests from your fork to striae-org/striae

  2. Cross-Repository PR: Your fork → striae-org/striae

  3. Branch Protection: Ensure your branch is up-to-date with the target branch

For Internal Developers:

  1. Target Repository: Submit pull requests within striae-org/striae-dev (branch → master)

  2. Same-Repository PR: Your feature branch → striae-dev master branch

  3. Direct Access: Work within the shared development repository

Both Developer Types:

  • Use the provided PR template and fill out all sections

  • Ensure branch is up-to-date before submitting

Review Process

  1. Mandatory Review: All pull requests must be reviewed and approved by a project admin before merging

  2. Review Criteria: Reviews will assess:

    • Code quality and adherence to standards

    • Security implications

    • Performance impact

    • Test coverage

    • Documentation completeness

Merge Guidelines

  1. Admin Only: Only project administrators can merge pull requests

  2. Merge Strategy: Use "Squash and Merge" for feature branches to maintain clean history

  3. Delete Branches: Feature branches should be deleted after successful merge

PR Description Requirements

Required Information:

  • Summary: Clear description of what the PR accomplishes

  • Changes Made: Detailed list of modifications

  • Testing: Description of testing performed

  • Breaking Changes: Any breaking changes and migration notes

  • Related Issues: Link to related issues or discussions

  • Screenshots: For UI changes, include before/after screenshots

  • Security Impact: Any security considerations or changes

PR Description Template:

## Summary
Brief description of the changes and their purpose.

## Changes Made
- [ ] Feature 1: Description
- [ ] Feature 2: Description
- [ ] Bug fix: Description

## Testing
- [ ] Unit tests added/updated
- [ ] Integration tests verified
- [ ] Manual testing completed
- [ ] Browser compatibility verified

## Breaking Changes
List any breaking changes and migration steps.

## Security Impact
Describe any security considerations or changes.

## Related Issues
Closes #123
Related to #456

## Screenshots (if applicable)
[Include relevant screenshots]

Code Quality Standards

Code Style

  1. Formatting: Use Prettier for consistent code formatting

  2. Linting: Follow ESLint rules defined in the project

  3. TypeScript: Maintain strict TypeScript compliance

  4. Comments: Write clear, meaningful comments for complex logic

Testing Requirements

  1. Unit Tests: Write unit tests for new functionality

  2. Integration Tests: Include integration tests for API endpoints

  3. Coverage: Maintain or improve code coverage

  4. Test Naming: Use descriptive test names and organize tests logically

Documentation

  1. Code Documentation: Document complex functions and classes

  2. README Updates: Update relevant README files for new features

  3. API Documentation: Update API documentation for endpoint changes

  4. Guide Updates: Update relevant guides in the /guides directory

Security Considerations

  1. Sensitive Data: Never commit sensitive data (API keys, passwords, etc.)

  2. Dependencies: Keep dependencies updated and scan for vulnerabilities

  3. Input Validation: Validate all user inputs

  4. Authentication: Follow established authentication patterns

  5. Environment Variables: Use environment variables for configuration

Release Management

  1. Versioning Scheme: Follow the project's versioning format:

    • Beta Releases: v0.#.#-beta (e.g., v0.9.06-beta)

      • First number: Always 0 for beta releases

      • Second number: Month (1-12)

      • Third number: Date (01-31)

    • Production Releases: v#.##.## (e.g., v1.01.00)

      • First number: Major release (breaking changes, major features)

      • Second number: Minor release (new features, enhancements)

      • Third number: Patch release (bug fixes, small improvements)

  2. Release Notes: Maintain comprehensive release notes for each version

  3. Changelog: Update README.md changelog for each release

  4. Tag Management: Use proper Git tags matching the version format (v0.#.#-beta or v#.##.##)

  5. Beta to Production: Beta versions should be thoroughly tested before removing the -beta suffix and promoting version numbers to production releases

  6. Release Immutability: Once a release is tagged and published, it is immutable and cannot be modified. If issues are discovered, create a new release with an incremented version number

Issue Management

  1. Issue Templates: Use provided issue templates

  2. Labels: Apply appropriate labels to issues

  3. Assignees: Assign issues to appropriate team members

  4. Milestones: Associate issues with relevant milestones

  5. Documentation: Link related documentation and PRs

Communication Guidelines

  1. Respectful Communication: Maintain professional and respectful communication

  2. Clear Communication: Be clear and specific in issue descriptions and comments

  3. Response Time: Respond to reviews and comments in a timely manner

  4. Code of Conduct: Follow the project's Code of Conduct at all times

Additional Best Practices

Performance Considerations

  • Profile performance impact of changes

  • Optimize database queries and API calls

  • Consider caching strategies for improved performance

Accessibility

  • Ensure UI changes meet accessibility standards

  • Test with screen readers and keyboard navigation

  • Include proper ARIA labels and semantic HTML

Error Handling

  • Implement comprehensive error handling

  • Provide meaningful error messages to users

  • Log errors appropriately for debugging

Monitoring and Observability

  • Include appropriate logging for new features

  • Consider monitoring and alerting needs

  • Document operational procedures for new services

Enforcement

Failure to follow these protocols may result in:

  • PR rejection and request for revision

  • Additional review requirements

  • Temporary restriction from contributing

Questions and Support

For questions about these protocols or development practices:

  • GitHub Issues: Open an issue with the question label

  • Email: Contact project administrators at dev@striae.org

  • Discord: Contact team members on the Striae Discord #development channel (private)

  • Documentation: Refer to the project documentation in the /guides directory

Internal Developer Program

If you're interested in becoming an internal developer with direct access to the development infrastructure:

  • Contact: Stephen at dev@striae.org

  • Benefits: Internal developers receive:

    • Pre-configured Environment: Complete .env files with all required variables

    • Cloudflare Access: Access to shared Cloudflare services (no separate account needed)

    • Pre-configured Services: Firebase authentication, MFA, and SendLayer API already set up

    • Configuration Files: All config.json, firebase.ts, and wrangler.jsonc files ready to use

    • Direct Repository Access: Push access to striae-org/striae-dev

    • Development Environment: Access to https://dev.striae.org for testing

    • Enhanced Development Privileges: Streamlined setup and deployment process

    • Private Communication Channels: Access to Discord #development channel

    • Faster Development Cycle: Skip complex setup steps and focus on coding

Internal Developer Workflow:

  1. Clone striae-org/striae-dev directly

  2. Use provided configuration files

  3. Create feature branches within the shared repository

  4. Submit pull requests within the same repository

  5. Test on the shared development environment

This guide is a living document and will be updated as the project evolves. Contributors are encouraged to suggest improvements to these protocols.

Updated on
Environment Variables Setup
API Reference