Contributing Guidelines

Welcome Contributors

Contributions are welcome - code, docs, whatever it might be! If this is your first contribution to an Open Source project or you’re a core maintainer of multiple projects, your time and interest in contributing to this project is most welcome.

Before starting, please read the developer guide to understand the project structure and setup your development environment.

Getting Started

Prerequisites

Node.js: >=22.12.0 <23.0.0
pnpm: 10.6.1
PostgreSQL: Latest version
Redis: Latest version
Git: Latest version

Setup Development Environment

Fork the repository

Create a personal copy of the repository on your GitHub account.

# Visit https://github.com/gitroomhq/postiz-app and click "Fork"

Clone your fork

git clone https://github.com/YOUR_USERNAME/postiz-app.git
cd postiz-app

Install dependencies

pnpm install

Setup environment

cp .env.example .env
# Edit .env with your configuration

Start development services

# Start PostgreSQL and Redis
pnpm dev:docker

# Run database migrations
pnpm prisma-db-push

# Start development servers
pnpm dev

Contribution Workflow

1. Pick an Issue

Browse GitHub issues and pick one that interests you, or create a new issue if you have an idea. Good first issues are labeled with good first issue.

2. Discuss Before Coding

General Rule:

If a change is less than 3 lines: You’re probably safe to submit without discussion
If a change is more than 3 lines: Discuss in an issue or Discord first

This saves you time and avoids disappointment if your change can’t be accepted.

Best ways to interact with the community:

GitHub issues: For detailed, longer-written discussions
Discord chat: For quick questions and feedback

3. Create a Branch

Create a new branch for your changes:

git checkout -b feature/your-feature-name

Branch naming conventions:

feature/add-mastodon-provider - New features
fix/calendar-rendering-bug - Bug fixes
docs/update-api-guide - Documentation
refactor/improve-auth-flow - Refactoring

4. Make Your Changes

Follow the code standards and testing strategy while implementing your changes.

5. Test Your Changes

# Run linting
pnpm lint

# Run tests
pnpm test

# Test locally
pnpm dev

6. Commit Your Changes

Write clear, descriptive commit messages:

# Good commit messages
git commit -m "feat: add Mastodon integration provider"
git commit -m "fix: resolve calendar date rendering issue"
git commit -m "docs: update OAuth flow documentation"

# Bad commit messages
git commit -m "updates"  # Too vague
git commit -m "fixed stuff"  # Not descriptive

Commit message format:

<type>: <description>

[optional body]

[optional footer]

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

7. Push Your Changes

git push -u origin feature/your-feature-name

8. Create a Pull Request

Go to GitHub and create a pull request to the main branch. Pull Request Template:

## Description
Brief description of what this PR does

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
How has this been tested?

## Screenshots (if applicable)
Add screenshots for UI changes

## Checklist
- [ ] My code follows the project's code standards
- [ ] I have performed a self-review
- [ ] I have commented my code where necessary
- [ ] I have updated the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests
- [ ] All tests pass locally

Types of Contributions

Code Improvements

Bug Fixes:

Search for bugs in GitHub issues
Reproduce the bug locally
Fix and add regression tests
Submit PR with clear description

New Features:

Discuss feature in issue first
Break into smaller PRs if possible
Include tests and documentation
Update relevant docs

New Integrations:

See Creating a Provider
Test OAuth flow thoroughly
Include platform-specific documentation
Add platform logo and branding

Documentation Updates

Documentation improvements:

Fix typos and grammar
Add missing information
Improve clarity and examples
Update outdated content

Where to contribute docs:

/docs - Main documentation (this site)
README.md - Project README
Code comments - JSDoc/TSDoc comments
/CONTRIBUTING.md - This file

Feature Requests

Submit feature requests as GitHub issues:

Search existing issues first
Describe the feature clearly
Explain the use case
Provide examples if possible

Bug Reports

Report bugs with detailed information: Bug Report Template:

## Bug Description
Clear description of the bug

## Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. See error

## Expected Behavior
What should happen

## Actual Behavior
What actually happens

## Environment
- OS: [e.g., macOS 14.0]
- Browser: [e.g., Chrome 120]
- Node.js: [e.g., 22.12.0]
- Version: [e.g., 1.0.0]

## Screenshots
If applicable

## Additional Context
Any other information

Code Review Process

What Happens After Submitting PR

Automated Checks

CI/CD runs automated tests, linting, and builds.

Code Review

Maintainers review your code and provide feedback.

Revisions

Make requested changes and push updates.

Approval

Once approved, PR is merged to main branch.

Review Criteria

Your PR will be evaluated on:

Code quality: Follows standards, clean and readable
Tests: Adequate test coverage
Documentation: Updated relevant docs
Functionality: Works as intended
Performance: No significant performance regression
Security: No security vulnerabilities

Development Guidelines

Backend Development

Critical Rules:

Always follow Controller → Service → Repository pattern
Most logic goes in libraries/nestjs-libraries/src/services
Never skip layers in the architecture
Use dependency injection

See Backend Development for details.

Frontend Development

Critical Rules:

Never install UI components from npm - build custom components
Each SWR hook must be in a separate function
Always use useFetch hook for API calls
Check existing components before creating new ones
Use new color variables, not deprecated --color-custom*

See Frontend Development for details.

Integration Development

When adding a new social media integration:

Extend SocialAbstract class
Implement SocialProvider interface
Add OAuth flow
Implement post publishing
Add error handling
Include tests
Update documentation

See Creating a Provider for details.

Style Guidelines

Code Formatting

Linting: Run from root: pnpm lint
Auto-format: Prettier is configured
TypeScript: Required for all code
No any: Avoid any type, use proper types

Naming Conventions

Files:

PascalCase for components: Button.tsx, UserProfile.tsx
kebab-case for utilities: auth.service.ts, user.repository.ts

Variables:

const userName = 'John';      // camelCase
const MAX_RETRIES = 3;        // UPPER_SNAKE_CASE for constants
interface UserData {}         // PascalCase for types/interfaces

Functions:

function getUserById() {}     // camelCase
async function fetchPosts() {} // async prefix clear from usage

Communication

Discord Community

Join our Discord server for:

Quick questions
Feature discussions
Help with contributions
Community chat

GitHub Issues

Use GitHub issues for:

Bug reports
Feature requests
Detailed technical discussions
Long-form proposals

Code of Conduct

This project follows the Contributor Covenant Code of Conduct. Key points:

Be respectful and inclusive
Welcome newcomers
Accept constructive feedback
Focus on what’s best for the community

Report issues to: [email protected]

Recognition

Contributors are recognized in:

GitHub contributors list
Release notes
Community shout-outs

Thank you for contributing to Postiz!

Need Help?

Check these resources:

Your contributions help make Postiz better!

Next Steps

Code Standards

Follow code standards and conventions

Testing Strategy

Learn testing best practices

Architecture

Backend Development

Frontend Development

Integrations

Contributing

​Welcome Contributors

​Getting Started

​Prerequisites

​Setup Development Environment

​Contribution Workflow

​1. Pick an Issue

​2. Discuss Before Coding

​3. Create a Branch

​4. Make Your Changes

​5. Test Your Changes

​6. Commit Your Changes

​7. Push Your Changes

​8. Create a Pull Request

​Types of Contributions

​Code Improvements

​Documentation Updates

​Feature Requests

​Bug Reports

​Code Review Process

​What Happens After Submitting PR

​Review Criteria

​Development Guidelines

​Backend Development

​Frontend Development

​Integration Development

​Style Guidelines

​Code Formatting

​Naming Conventions

​Communication

​Discord Community

​GitHub Issues

​Code of Conduct

​Recognition

​Need Help?

​Next Steps

Code Standards

Testing Strategy

Build docs developers (and LLMs) love

Welcome Contributors

Getting Started

Prerequisites

Setup Development Environment

Contribution Workflow

1. Pick an Issue

2. Discuss Before Coding

3. Create a Branch

4. Make Your Changes

5. Test Your Changes

6. Commit Your Changes

7. Push Your Changes

8. Create a Pull Request

Types of Contributions

Code Improvements

Documentation Updates

Feature Requests

Bug Reports

Code Review Process

What Happens After Submitting PR

Review Criteria

Development Guidelines

Backend Development

Frontend Development

Integration Development

Style Guidelines

Code Formatting

Naming Conventions

Communication

Discord Community

GitHub Issues

Code of Conduct

Recognition

Need Help?

Next Steps