Contributing Guide

Version: 1.0.0

This guide covers code style, git workflow, and contribution guidelines for notifito.

Code Style

PHP

<?php

declare(strict_types=1);

namespace App\Domain\Catalog;

enum NotifyPolicy: string
{
    case All = 'all';
    case CapacityMultiple = 'capacity_multiple';
}

JavaScript

// Good
export function fetchSchema(key, itemType) {
    return fetch(`/v1/widget/schema?key=${key}&item_type=${itemType}`)
        .then(response => response.json());
}

// Bad - avoid comments
// Fetch the schema from the API
export function fetchSchema(key, itemType) {
    // ...
}

Blade Templates

{{-- Good --}}
<div>
    <h1>{{ $itemTypeName }}</h1>
    <livewire:item-type-list />
</div>

{{-- Bad - avoid complex logic in templates --}}
<div>
    @if(count($itemTypes) > 0)
        @foreach($itemTypes as $type)
            @if($type['attribute_count'] > 0)
                <p>{{ $type['name'] }}</p>
            @endif
        @endforeach
    @endif
</div>

Git Workflow

Branch Naming

Type Format Example
Feature feature/description feature/add-sms-driver
Bugfix fix/description fix/subscription-expiry
Hotfix hotfix/description hotfix/security-patch
Docs docs/description docs/api-reference

Commit Messages

Follow Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types: - feat: New feature - fix: Bug fix - docs: Documentation - style: Formatting, missing semicolons, etc. - refactor: Code change that neither fixes a bug nor adds a feature - test: Adding missing tests - chore: Updating build tasks, configs, etc.

Examples:

feat(core): add SMS channel driver

fix(dispatch): handle Postmark rate limiting

docs(api): update edge API reference

test(core): add subscription matcher tests

Pull Request Process

  1. Create Branch: Create a feature branch from main
  2. Make Changes: Implement your changes
  3. Write Tests: Add tests for new functionality
  4. Run Tests: Ensure all tests pass
  5. Update Docs: Update documentation if needed
  6. Create PR: Create a pull request
  7. Code Review: Wait for review
  8. Address Feedback: Make requested changes
  9. Merge: Merge after approval

Pull Request Template

## Description

Brief description of changes.

## Type of Change

- [ ] Bug fix
- [ ] New feature
- [ ] Documentation update
- [ ] Refactoring
- [ ] Test addition

## Testing

- [ ] Unit tests pass
- [ ] Feature tests pass
- [ ] E2E tests pass (if applicable)

## Checklist

- [ ] Code follows style guidelines
- [ ] Self-review completed
- [ ] Documentation updated
- [ ] No breaking changes

Code Review Guidelines

For Reviewers

  1. Be Constructive: Provide helpful feedback
  2. Explain Why: Explain the reasoning behind suggestions
  3. Ask Questions: Ask for clarification when needed
  4. Approve Quickly: Don't block on minor issues
  5. Test Locally: Test changes locally if possible

For Authors

  1. Self-Review: Review your own code first
  2. Small PRs: Keep pull requests small and focused
  3. Respond Promptly: Address feedback quickly
  4. Explain Decisions: Explain non-obvious decisions
  5. Be Open: Accept constructive criticism

Review Checklist

Issue Reporting

Bug Reports

Use the bug report template:

## Description

Clear description of the bug.

## Steps to Reproduce

1. Go to '...'
2. Click on '...'
3. Scroll down to '...'
4. See error

## Expected Behavior

What you expected to happen.

## Actual Behavior

What actually happened.

## Environment

- OS: [e.g., Ubuntu 24.04]
- Browser: [e.g., Chrome 120]
- Version: [e.g., 1.0.0]

## Additional Context

Any other context about the problem.

Feature Requests

Use the feature request template:

## Description

Clear description of the feature.

## Problem

What problem does this solve?

## Proposed Solution

How should this be implemented?

## Alternatives Considered

Other solutions you've considered.

## Additional Context

Any other context about the feature request.

Development Workflow

Starting a New Feature

# Update main branch
git checkout main
git pull origin main

# Create feature branch
git checkout -b feature/my-feature

# Make changes
# ...

# Run tests
./bin/test packages/contracts
./bin/test apps/core
./bin/test apps/edge
./bin/test apps/dispatch
./bin/test apps/dashboard

# Commit changes
git add .
git commit -m "feat(core): add my feature"

# Push to remote
git push origin feature/my-feature

# Create pull request

Fixing a Bug

# Update main branch
git checkout main
git pull origin main

# Create fix branch
git checkout -b fix/my-fix

# Make changes
# ...

# Run tests
./bin/test apps/core

# Commit changes
git add .
git commit -m "fix(core): fix the bug"

# Push to remote
git push origin fix/my-fix

# Create pull request

Updating Documentation

# Update main branch
git checkout main
git pull origin main

# Create docs branch
git checkout -b docs/my-docs

# Make changes
# ...

# Commit changes
git add .
git commit -m "docs: update documentation"

# Push to remote
git push origin docs/my-docs

# Create pull request

Project Structure

Monorepo Layout

notifito/
├── apps/
│   ├── core/           # Domain logic
│   ├── edge/           # Public API
│   ├── dispatch/       # Email delivery
│   └── dashboard/      # Seller UI
├── packages/
│   └── contracts/      # Shared DTOs
├── widget/             # JavaScript widget
├── docker/             # Docker configs
├── bin/                # Dev scripts
└── docs/               # Documentation

Adding a New Service

  1. Create directory in apps/
  2. Add composer.json with path repository to contracts
  3. Add Docker service to docker-compose.yml
  4. Add test script to bin/test
  5. Update documentation

Adding a New Package

  1. Create directory in packages/
  2. Add composer.json
  3. Add path repository to all apps
  4. Add tests
  5. Update documentation

Security

Reporting Security Issues

Do NOT open a public issue for security vulnerabilities.

Instead, email security issues to: turker@gmail.com

Security Guidelines

  1. Never commit secrets: API keys, passwords, tokens
  2. Use environment variables: For all sensitive configuration
  3. Validate input: Always validate user input
  4. Escape output: Always escape output to prevent XSS
  5. Use HTTPS: Always use HTTPS in production
  6. Keep dependencies updated: Regularly update dependencies

Communication

Channels

Getting Help

  1. Check Documentation: Read the docs first
  2. Search Issues: Search existing issues
  3. Ask Questions: Open a discussion or issue
  4. Be Patient: Maintainers are volunteers

License

This project is proprietary. All rights reserved.

Documentation Updates

Converting Documentation

After updating markdown files, convert them to HTML:

# Local conversion (requires Pandoc)
./bin/docs-convert

# Docker conversion (no dependencies)
./bin/docs-convert-docker

Viewing Documentation

# Start local server
./bin/docs-serve

# Or open directly
open site/index.html

Cleaning Generated Files

# Remove generated HTML files
./bin/docs-clean

Testing Documentation Links

# Test all documentation links
./bin/docs-test

Documentation Structure

Adding New Pages

  1. Create markdown file in docs/
  2. Add to navigation in templates/documentation.html
  3. Run conversion script

Related Documentation