Contributing Guide
This guide covers code style, git workflow, and contribution guidelines for notifito.
Code Style
PHP
- PSR-12: Follow PSR-12 coding standard
- Strict Types: Always declare
declare(strict_types=1);at the top of every PHP file - Type Hints: Use type hints for all parameters, return types, and properties
- Readonly Properties: Use
readonlywhere appropriate - Enums: Use backed enums for closed sets
<?php
declare(strict_types=1);
namespace App\Domain\Catalog;
enum NotifyPolicy: string
{
case All = 'all';
case CapacityMultiple = 'capacity_multiple';
}
JavaScript
- ESLint: Follow ESLint configuration
- No Frameworks: Widget uses vanilla JavaScript only
- ES Modules: Use ES module syntax
- No Comments: Code should be self-documenting
// Good
export function fetchSchema(key, itemType) {
return fetch(/v1/widget/schema?key=${key}&item_type=${itemType})
.then(response => response.json());
}
Blade Templates
- Laravel Conventions: Follow Laravel Blade conventions
- Livewire: Use Livewire components for interactive UI
- Minimal Logic: Keep logic in components, not templates
{{-- Good --}}
<div>
<h1>{{ $itemTypeName }}</h1>
<livewire:item-type-list />
</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]
feat: New featurefix: Bug fixdocs: Documentationstyle: Formatting, missing semicolons, etc.refactor: Code change that neither fixes a bug nor adds a featuretest: Adding missing testschore: Updating build tasks, configs, etc.
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
- Create Branch: Create a feature branch from
main - Make Changes: Implement your changes
- Write Tests: Add tests for new functionality
- Run Tests: Ensure all tests pass
- Update Docs: Update documentation if needed
- Create PR: Create a pull request
- Code Review: Wait for review
- Address Feedback: Make requested changes
- 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
- Be Constructive: Provide helpful feedback
- Explain Why: Explain the reasoning behind suggestions
- Ask Questions: Ask for clarification when needed
- Approve Quickly: Don't block on minor issues
- Test Locally: Test changes locally if possible
For Authors
- Self-Review: Review your own code first
- Small PRs: Keep pull requests small and focused
- Respond Promptly: Address feedback quickly
- Explain Decisions: Explain non-obvious decisions
- Be Open: Accept constructive criticism
Review Checklist
- [ ] Code follows style guidelines
- [ ] Tests are included
- [ ] Documentation is updated
- [ ] No security issues
- [ ] No performance issues
- [ ] No breaking changes
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
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
│ └── admin/ # Admin UI
├── packages/
│ └── contracts/ # Shared DTOs
├── widget/ # JavaScript widget
├── docker/ # Docker configs
├── bin/ # Dev scripts
└── docs/ # Documentation
Adding a New Service
- Create directory in
apps/ - Add
composer.jsonwith path repository to contracts - Add Docker service to
docker-compose.yml - Add test script to
bin/test - Update documentation
Adding a New Package
- Create directory in
packages/ - Add
composer.json - Add path repository to all apps
- Add tests
- 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
- Never commit secrets: API keys, passwords, tokens
- Use environment variables: For all sensitive configuration
- Validate input: Always validate user input
- Escape output: Always escape output to prevent XSS
- Use HTTPS: Always use HTTPS in production
- Keep dependencies updated: Regularly update dependencies
Documentation
Building Documentation
# Generate HTML from markdown
node docs/build-html.js
Start local server to preview
open docs/html/index.html
Adding New Pages
- Create markdown file in
docs/ - Add to pages list in
docs/build-html.js - Run build script
- Commit both markdown and generated HTML