Skip to main content

Contributing Guide

Important Notice: This documentation is maintained as a reference for AI assistants and internal development purposes only. External contributions are not accepted for this project.

This guide outlines the development standards, workflows, and best practices that should be followed when working on this codebase.

Table of Contents​

Development Standards​

Code Style​

  • Follow TypeScript best practices and strict typing
  • Use functional programming patterns where appropriate
  • Write self-documenting code with clear variable/function names
  • Add JSDoc comments for complex functions
  • Keep functions small and focused (< 50 lines ideally)

File Organization​

  • Co-locate tests with source files
  • Organize by feature/domain, not by file type
  • Use absolute imports with ~/ alias
  • Follow the existing layered architecture

Code Quality Checklist​

Before marking any task as complete, ensure:

  • Code follows the project's code style
  • Self-review has been performed
  • Hard-to-understand areas are commented
  • Documentation has been updated
  • No new warnings or errors introduced
  • Tests prove the fix/feature works
  • All tests pass locally
  • Commit messages follow conventional commits format
  1. Issue that pull request!

Contributing Code​

Follow these steps to contribute code changes:

  1. Set up your development environment - See Setup Guide
  2. Find an issue - Look for issues labeled good first issue or help wanted
  3. Claim the issue - Comment on the issue that you'd like to work on it
  4. Create a branch - Follow the branching workflow
  5. Make your changes - Write code following our coding standards
  6. Test your changes - Ensure tests pass and functionality works
  7. Submit a pull request - Follow the PR template

Development Workflow​

We use GitHub Flow for our development workflow. All changes happen through branches and pull requests.

Branching Strategy​

1. Main Branch (master)​

  • Purpose: Production-ready code
  • Protection: Protected branch with required reviews
  • Deployment: Automatically deploys to production
  • Rules:
    • No direct commits allowed
    • All changes via Pull Requests
    • Requires passing CI/CD checks
    • Requires at least 1 approval

2. Feature Branches (feature/*)​

  • Naming: feature/descriptive-name
  • Examples:
    • feature/whatsapp-integration
    • feature/user-authentication
    • feature/payment-flow
  • Lifecycle:
    1. Branch from master
    2. Develop and commit changes
    3. Open PR to master
    4. Review, test, merge
    5. Keep (Default)/Delete after merge

3. Hotfix Branches (hotfix/*)​

  • Naming: hotfix/issue-description
  • Example: hotfix/payment-webhook-crash
  • Purpose: Urgent production fixes
  • Lifecycle:
    1. Branch from master
    2. Fix the issue
    3. Fast-track PR review
    4. Merge and deploy immediately
    5. Delete after merge

Creating a Feature Branch​

# Ensure you're on master and up to date
git checkout master
git pull origin master

# Create a new feature branch
git checkout -b feature/descriptive-name

Committing Changes​

We use Conventional Commits format for all commits. This format enables automated changelog generation and better commit history.

Format​

<type>(<scope>): <subject>

<body>

<footer>

Types​

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting, no logic change)
  • refactor: Code refactoring
  • perf: Performance improvements
  • test: Adding or updating tests
  • build: Build system or dependency changes
  • ci: CI/CD configuration changes
  • chore: Other changes (maintenance)

Examples​

# Simple commit
git commit -m "feat(auth): add Google OAuth integration"

# Multi-line commit
git commit -m "feat(whatsapp): implement message parsing and analysis

- Parse WhatsApp chat exports
- Extract metadata and statistics
- Support multiple chat formats"

# Bug fix with issue reference
git commit -m "fix(payment): prevent duplicate subscription charges

Closes #123"

Note: The commit message format is enforced by commitlint. Commits that don't follow the format will be rejected.

Syncing Your Branch​

Regularly sync your feature branch with master to minimize merge conflicts:

git checkout master
git pull origin master
git checkout feature/your-branch
git merge master

Creating a Pull Request​

Before submitting a pull request:

  1. Update your branch with the latest master
  2. Run tests locally and ensure they pass
  3. Run linters and fix any issues
  4. Update documentation if you've changed APIs
  5. Add tests for new functionality
  6. Review your changes before submitting

When you're ready:

# Push your branch
git push origin feature/descriptive-name

Then go to GitHub and open a pull request following our PR template.

Pull Request Checklist​

Before requesting review, ensure:

  • Your code follows the project's code style
  • You have performed a self-review of your code
  • You have commented your code, particularly in hard-to-understand areas
  • You have made corresponding changes to the documentation
  • Your changes generate no new warnings or errors
  • You have added tests that prove your fix is effective or that your feature works
  • New and existing unit tests pass locally with your changes
  • Any dependent changes have been merged and published
  • Your commit messages follow the conventional commits format

Local Development​

Run these commands before pushing to ensure your changes are ready:

# Type checking
npm run type-check

# Lint all code
npm run lint:all

# Run tests
npm test

# Build the project
npm run build

Code Review Process​

For Contributors​

  1. Request reviews from maintainers or relevant team members
  2. Be responsive to review comments
  3. Make requested changes or discuss alternatives
  4. Keep PRs focused - one feature or fix per PR
  5. Keep PRs small - easier to review and less likely to cause conflicts

For Reviewers​

  1. Review promptly - within 24-48 hours if possible
  2. Be constructive - provide clear, actionable feedback
  3. Explain the why - help contributors understand the reasoning
  4. Approve when satisfied - don't block on minor nitpicks
  5. Test major changes - verify the functionality works as expected

Review Criteria​

When reviewing pull requests, check for:

  • Functionality: Does the code work as intended?
  • Code quality: Is the code clean, readable, and maintainable?
  • Tests: Are there adequate tests? Do they pass?
  • Documentation: Is the code well-documented? Are docs updated?
  • Performance: Are there any performance concerns?
  • Security: Are there any security vulnerabilities?
  • Style: Does the code follow project conventions?
  • Breaking changes: Are there any breaking changes? Are they documented?

Handling Review Feedback​

  1. Address all comments - either make changes or discuss
  2. Mark resolved comments - helps reviewers track progress
  3. Request re-review - when you've made significant changes
  4. Be patient - reviewers are volunteers

Merging​

After approval and all checks pass:

  1. Rebase with master (optional) - for cleaner history
  2. Merge using squash - to keep master history clean
  3. Delete your branch (optional) - after successful merge

Community Guidelines​

Our Pledge​

We as contributors and maintainers pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our Standards​

Positive behavior includes:

  • Being respectful and inclusive
  • Gracefully accepting constructive criticism
  • Focusing on what is best for the community
  • Showing empathy towards other community members

Unacceptable behavior includes:

  • Harassment, trolling, or derogatory comments
  • Personal or political attacks
  • Public or private harassment
  • Publishing others' private information
  • Any other unethical or unprofessional conduct

Responsibilities​

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Scope​

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

Enforcement​

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident.

Attribution​

This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html

Getting Help​

Documentation​

Asking Questions​

If you have questions:

  1. Search existing issues - Your question may have been answered
  2. Read the documentation - Most answers are in the docs
  3. Check the FAQ - Common questions are covered there
  4. Join our community - Connect with other contributors
  5. Ask in a discussion - Use GitHub Discussions for general questions

Reporting Issues​

When reporting issues:

  1. Search existing issues - Avoid duplicates
  2. Use the issue templates - Provide all requested information
  3. Be specific - Include steps to reproduce, expected vs actual behavior
  4. Include environment details - OS, browser, version numbers
  5. Add screenshots - Help illustrate the problem

Communication Channels​

  • GitHub Issues - For bugs and feature requests
  • GitHub Discussions - For questions and community discussion
  • Pull Requests - For code contributions and reviews

Additional Resources​

Recognition​

Contributors who make significant contributions will be recognized in:

  • README.md - Listed as contributors
  • Release notes - Credited for their work
  • Contributors section - Permanent recognition on the project

Thank you for contributing to AllMyChats! Your contributions make this project better for everyone.

Need more help? Check out our documentation or open an issue.