Contributing Guide

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

Code Style

PHP

php
<?php

declare(strict_types=1);

namespace App\Domain\Catalog;

enum NotifyPolicy: string

{

case All = 'all';

case CapacityMultiple = 'capacity_multiple';

}

JavaScript

javascript
// Good

export function fetchSchema(key, itemType) {

return fetch(/v1/widget/schema?key=${key}&item_type=${itemType})

.then(response => response.json());

}

Blade Templates

blade
{{-- Good --}}

<div>

<h1>{{ $itemTypeName }}</h1>

<livewire:item-type-list />

</div>


Git Workflow

Branch Naming

TypeFormatExample
Featurefeature/descriptionfeature/add-sms-driver
Bugfixfix/descriptionfix/subscription-expiry
Hotfixhotfix/descriptionhotfix/security-patch
Docsdocs/descriptiondocs/api-reference

Commit Messages

Follow Conventional Commits:

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

[optional body]

[optional footer]

Types: 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

markdown
## 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


Development Workflow

Starting a New Feature

bash
# 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

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

bash
# 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

bash
# 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

│ └── admin/ # Admin 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

Documentation

Building Documentation

bash
# Generate HTML from markdown

node docs/build-html.js

Start local server to preview

open docs/html/index.html

Adding New Pages

  1. Create markdown file in docs/
  2. Add to pages list in docs/build-html.js
  3. Run build script
  4. Commit both markdown and generated HTML