papra/CONTRIBUTING.md

Contributing to Papra

First off, thanks for taking the time to contribute to Papra! We welcome contributions of all types and encourage you to help make this project better for everyone.

Code of Conduct

This project adheres to the Contributor Covenant. By participating, you are expected to uphold this code. Please report unacceptable behavior to corentinth@proton.me

How Can I Contribute?

Reporting Issues

If you find a bug, have a feature request, or need help, feel free to open an issue in the GitHub Issue Tracker. You're also welcome to comment on existing issues.

Submitting Pull Requests

Please refrain from submitting pull requests that implement new features or fix bugs without first opening an issue. This will help us avoid duplicate work and ensure that your contribution is in line with the project's goals and prevents wasted effort on your part.

We follow a GitHub Flow model where all PRs should target the main branch, which is continuously deployed to production.

Guidelines for submitting PRs:

• Each PR should be small and atomic. Please avoid solving multiple unrelated issues in a single PR.
• Ensure that the CI is green before submitting. Some of the following checks are automatically run for each package: linting, type checking, testing, and building.
• If your PR fixes an issue, please reference the issue number in the PR description.
• If your PR adds a new feature, please include tests and update the documentation if necessary.
• Be prepared to address feedback and iterate on your PR.
• Resolving merge conflicts is part of the PR author's responsibility.
• Draft PRs are welcome to get feedback early on your work but only when requested, they'll not be reviewed.

Branching

• Main branch: This is the production branch. All pull requests must target this branch.
• Feature branches: Create a new branch for your feature (e.g., my-new-feature), make your changes, and then open a PR targeting main.

Commit Guidelines

We use Conventional Commits to keep commit messages consistent and meaningful. Please follow these guidelines when writing commit messages. While you can structure commits however you like, PRs will be squashed on merge.

i18n

We welcome contributions to improve and expand the app's internationalization (i18n) support. Below are the guidelines for adding a new language or updating an existing translation.

Adding a New Language

1. Create a Language File: To add a new language, create a TypeScript file named with the appropriate ISO language code followed by .dictionary.ts (e.g., fr.dictionary.ts for French) in the apps/papra-client/src/locales directory.

2. Use the Reference File: Refer to the en.dictionary.ts file, which contains all keys used in the app. Use it as a base to ensure consistency when creating your new language file. The English translations act as a fallback if a key is missing in the new language file.

3. Update the Locale List: After adding the new language file, include the language code in the locales array found in the apps/papra-client/src/modules/i18n/i18n.constants.ts file.

4. Submit a Pull Request: Once you've added the file and updated i18n.constants.ts, create a pull request (PR) with your changes. Ensure that your PR is clearly titled with the language being added (e.g., "Add French translations").

Updating an Existing Language

If you want to update an existing language file, you can do so directly in the corresponding TypeScript file in the apps/papra-client/src/locales directory. The translation keys are now fully type-safe with TypeScript, so you'll get immediate feedback if you add invalid keys or have syntax errors.

Tip

You can use the command pnpm script:sync-i18n-key-order to sync the order of the keys in the TypeScript i18n files, it'll also add the missing keys as comments.

Using Branchlet for Pluralization and Conditionals

Papra uses @branchlet/core for pluralization and conditional i18n string templates (a variant of ICU message format). Here are some common patterns:

• Basic interpolation: 'Hello {{ name }}!' with { name: 'World' }
• Conditionals: '{{ count, =0:no items, =1:one item, many items }}'
• Pluralization with variables: '{{ count, =0:no items, =1:{count} item, {count} items }}'
• Range conditions: '{{ score, [0-50]:bad, [51-75]:good, [76-100]:excellent }}'

See the branchlet documentation for more details on syntax and advanced usage.

Development Setup

Local Environment Setup

We recommend running the app locally for development. Follow these steps:

1. Clone the repository and navigate inside the project directory.

   git clone https://github.com/papra-hq/papra.git
   cd papra
   

2. Install dependencies:

   pnpm install
   

3. Build the monorepo packages:

   As the apps rely on internal packages, you need to build them first.

   pnpm build:packages
   

4. Start the development server for the backend:

   cd apps/papra-server
   # Run the migration script to create the database schema
   pnpm migrate:up 
   # Start the server
   pnpm dev
   

5. Start the frontend:

   cd apps/papra-client
   # Start the client
   pnpm dev
   

6. Open your browser and navigate to http://localhost:3000.

IDE Setup

ESLint Extension

We recommend installing the ESLint extension for VS Code to get real-time linting feedback and automatic code fixing. The linting configuration is based on @antfu/eslint-config, you can find specific IDE configurations in their repository.

Recommended VS Code Settings

Create or update your .vscode/settings.json file with the following configuration:

{
  // Disable the default formatter, use eslint instead
  "prettier.enable": false,
  "editor.formatOnSave": false,

  // Auto fix
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit",
    "source.organizeImports": "never"
  },

  // Silent the stylistic rules in your IDE, but still auto fix them
  "eslint.rules.customizations": [
    { "rule": "style/*", "severity": "off", "fixable": true },
    { "rule": "format/*", "severity": "off", "fixable": true },
    { "rule": "*-indent", "severity": "off", "fixable": true },
    { "rule": "*-spacing", "severity": "off", "fixable": true },
    { "rule": "*-spaces", "severity": "off", "fixable": true },
    { "rule": "*-order", "severity": "off", "fixable": true },
    { "rule": "*-dangle", "severity": "off", "fixable": true },
    { "rule": "*-newline", "severity": "off", "fixable": true },
    { "rule": "*quotes", "severity": "off", "fixable": true },
    { "rule": "*semi", "severity": "off", "fixable": true }
  ],

  // Enable eslint for all supported languages
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact",
    "vue",
    "html",
    "markdown",
    "json",
    "jsonc",
    "yaml",
    "toml",
    "xml",
    "gql",
    "graphql",
    "astro",
    "svelte",
    "css",
    "less",
    "scss",
    "pcss",
    "postcss"
  ]
}

Testing

We use Vitest for testing. Each package comes with its own testing commands.

• To run the tests for any package:

  pnpm test
  

• To run tests in watch mode:

  pnpm test:watch
  

All new features must be covered by unit or integration tests. Be sure to use business-oriented test names (avoid vague descriptions like it('should return true')).

Writing Documentation

If your code changes affect the documentation, you must update the docs. The documentation is powered by Astro Starlight.

To start the documentation server for local development:

1. Navigate to the packages/docs directory:

   cd apps/docs
   

2. Start the documentation server:

   pnpm dev
   

3. Open your browser and navigate to http://localhost:4321.

Coding Style

• Use functional programming where possible.
• Focus on clarity and maintainability over performance.
• Choose meaningful, relevant names for variables, functions, and components.

Issue Labels

Look out for issues tagged as good first issue or PR welcome for tasks that are well-suited for new contributors. Feel free to comment on existing issues or create new ones.

License

By contributing, you agree that your contributions will be licensed under the AGPL3, the same as the project itself.