Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
199 lines (134 loc) · 5.3 KB

CONTRIBUTING.md

File metadata and controls

199 lines (134 loc) · 5.3 KB
Raw

Contributing to astro-loader-pocketbase

Thank you for your interest in contributing to astro-loader-pocketbase! This guide will help you get started with contributing to the project.

Getting Started

Prerequisites

  • Node.js (see .nvmrc for the required version)
  • npm
  • Git

Setup

  1. Fork the repository on GitHub
  2. Clone your fork locally: 
    git clone https://github.com/your-username/astro-loader-pocketbase.git
cd astro-loader-pocketbase
  3. Install dependencies: 
    npm install

Development Workflow

Code Style and Quality

Before making any changes, familiarize yourself with our code quality requirements:

  • Formatting: Run npm run format to format code with Oxfmt
  • Linting: Run npm run lint:fix to lint code with oxlint (and type-check at the same time)
  • Type Checking: Run npm run typecheck to check TypeScript types

These checks are enforced by pre-commit hooks and must pass before any commit.

Making Changes

  1. Create a new branch for your feature or fix:

    git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

  2. Make your changes following our code conventions:

    • Use strict TypeScript configuration
    • Define types in the types/ directory
    • Use relative imports and descriptive function names
    • Keep functions small and focused
    • Place utility functions in appropriate utils/ files
    • Update documentation and test cases as needed

  3. Ensure your code passes all quality checks:

    npm run format
npm run lint:fix
npm run typecheck

Commit Messages

We use Conventional Commits for commit messages. The format is:

<type>(scope): <description>

[optional body]

[optional footer(s)]

Types:

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

Scopes:

  • loader: Core loading functionality
  • schema: Schema-related changes
  • Or custom scopes as appropriate

Examples:

feat(loader): add support for file attachments
fix(schema): handle missing updated field correctly
docs(README): update installation instructions
test(utils): add tests for slugify function
refactor(loader): extract entry parsing logic

Testing

Unit Tests

Write unit tests for all new features and bug fixes. Unit tests should:

  • Cover happy paths, edge cases, and error scenarios.
  • Be located in the test/ directory with the .spec.ts suffix.

E2E Tests

For PocketBase interactions, create e2e tests using a real PocketBase instance. E2E tests should:

  • Verify integration with PocketBase.
  • Be located in the test/ directory with the .e2e-spec.ts suffix.

Running Tests

Run tests locally before submitting a PR:

npm run test

For e2e tests, you need a PocketBase instance running locally. The serve command blocks the terminal, so use two separate terminal sessions:

# Terminal 1 — download binary (once) and start the server (blocks)
npm run test:e2e:setup
./.pocketbase/pocketbase serve

# Terminal 2 — run the tests
npm run test:e2e

Ensure all tests pass and add new tests for your changes.

Pull Request Process

Before Submitting

  1. Ensure all code quality checks pass
  2. Rebase your branch on the latest next / master branch
  3. Test your changes thoroughly

Creating a Pull Request

  1. Push your branch to your fork:

    git push origin feature/your-feature-name

  2. Create a pull request on GitHub using our PR template (target the next branch)

  3. In your PR description, follow the PR template:

    • Clearly describe what your changes do and why
    • Reference any related issues
    • Include any breaking changes or migration notes
    • Confirm manual testing and automated test coverage

Review Process

  • All PRs require review before merging (maybe also including a review from Copilot)
  • Please address feedback promptly and push additional commits as needed
  • Once approved, a maintainer will merge your PR into the next branch and create a pre-release for beta testing
  • We may squash commits to keep the git history clean

Issue Reporting

Before Creating an Issue

  • Search existing issues to avoid duplicates
  • Check if the issue exists in the latest version (older versions may have bugs that are fixed already)
  • Gather relevant information about your environment

Creating Issues

Use our issue templates for:

  • Feature Requests: Propose new functionality
  • Bug Reports: Report problems or unexpected behavior

Provide as much detail as possible to help us understand and reproduce the issue.

Code of Conduct

Please be respectful and constructive in all interactions. We want to maintain a welcoming environment for all contributors.

While it's okay to use AI tools like Copilot (we provide instructions for agents in .github/copilot-instructions.md), please ensure that the code you submit adheres to our quality standards and conventions.

Questions?

If you have questions about contributing, feel free to:

  • Open an issue for discussion
  • Look at existing issues and PRs for examples
  • Review the codebase to understand patterns and conventions

Thank you for contributing to astro-loader-pocketbase!