Skip to content

Latest commit

 

History

History
195 lines (132 loc) · 5.69 KB

CONTRIBUTING.md

File metadata and controls

195 lines (132 loc) · 5.69 KB
Raw

Contributing to paperless-gpt

Thank you for considering contributing to paperless-gpt! We welcome contributions of all kinds, including bug reports, feature requests, documentation improvements, and code contributions. By participating in this project, you agree to abide by our Code of Conduct.

Table of Contents

Code of Conduct

This project and everyone participating in it is governed by the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to the project maintainer.

How Can I Contribute?

Reporting Bugs

If you find a bug, please open an issue on GitHub. Before doing so, please check if the issue has already been reported.

  • Use a clear and descriptive title for the issue.
  • Describe the steps to reproduce the bug.
  • Include any relevant logs, screenshots, or code snippets.
  • Provide information about your environment (OS, Docker version, LLM provider, etc.).

Suggesting Enhancements

We appreciate new ideas and enhancements.

  • Search existing issues to see if your idea has already been discussed.
  • Open a new issue with a descriptive title.
  • Provide a detailed description of the enhancement and its benefits.

Submitting Pull Requests

We welcome pull requests (PRs). Please follow these guidelines:

  1. Fork the repository and create your branch from main.
  2. Ensure your code follows the Coding Guidelines.
  3. Write clear commit messages following the Conventional Commits specification.
  4. Test your changes thoroughly.
  5. Update documentation if necessary.
  6. Submit a pull request and provide a clear description of your changes.
  7. Link related issues in your PR description.

Development Setup

Prerequisites

  • Go (version 1.20 or later)
  • Node.js (version 18 or later)
  • npm (comes with Node.js)
  • Docker and Docker Compose

Backend Setup

  1. Clone the repository:

    git clone https://github.com/icereed/paperless-gpt.git
cd paperless-gpt

  2. Set environment variables:

    • Create a .env file in the project root.
    • Set the required environment variables as per the README.

  3. Install Go dependencies:

    go mod download

  4. Run the backend server:

    go run main.go

Frontend Setup

  1. Navigate to the frontend directory:

    cd web-app

  2. Install Node.js dependencies:

    npm install

  3. Start the frontend development server:

    npm run dev

The application should now be accessible at http://localhost:8080.

Coding Guidelines

  • Languages: Go for the backend, TypeScript with React for the frontend.
  • Formatting:
    • Use gofmt or goimports for Go code.
    • Use Prettier and ESLint for frontend code (npm run lint).
  • Code Structure:
    • Keep code modular and reusable.
    • Write clear and concise code with comments where necessary.
  • Dependencies:
    • Manage Go dependencies with go mod.
    • Manage frontend dependencies with npm.

Style Guidelines

  • Commit Messages:

    • Follow the Conventional Commits format.
      • Examples:
        • feat: add support for custom server-side prompts
        • fix: resolve API pagination issue for tags
    • Use the imperative mood in the subject line.

  • Branch Naming:

    • Use descriptive names:
      • feat/your-feature-name
      • fix/issue-number-description
      • docs/update-readme

  • Pull Requests:

    • Keep PRs focused; avoid unrelated changes.
    • Provide a detailed description of your changes.
    • Reference any related issues (Closes #123).

Testing

  • Backend Tests:

    • Write unit tests using Go's testing and github.com/stretchr/testify/assert packages.
    • Run tests with go test ./....

  • Frontend Tests:

    • Use testing libraries like Jest and React Testing Library.
    • Run tests with npm run test.

  • Continuous Integration:

    • Ensure all tests pass before submitting a PR.

Documentation

  • Update Documentation:

    • Update the README and other relevant docs for any user-facing changes.
    • Include usage examples and configuration instructions.

  • Comment Your Code:

    • Use clear and descriptive comments for complex logic.
    • Document exported functions and methods in Go.

Communication

  • GitHub Issues: Use for bug reports, feature requests, and questions.
  • Discussions: Engage in discussions for broader topics.
  • Contact Maintainer: For sensitive matters, contact the maintainer via email.

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank you for your interest in contributing to paperless-gpt! We value your input and look forward to your contributions.