# Contributing to Foxel
We appreciate every minute you spend helping Foxel improve. This guide explains the contribution workflow so you can get started quickly.
## Table of Contents
- [How to Contribute](#how-to-contribute)
- [đ Report Bugs](#-report-bugs)
- [⨠Suggest Features](#-suggest-features)
- [đ ī¸ Contribute Code](#ī¸-contribute-code)
- [Development Environment](#development-environment)
- [Prerequisites](#prerequisites)
- [Backend (FastAPI)](#backend-fastapi)
- [Frontend (React + Vite)](#frontend-react--vite)
- [Contribution Guidelines](#contribution-guidelines)
- [Storage Adapters](#storage-adapters)
- [Frontend Apps](#frontend-apps)
- [Submission Rules](#submission-rules)
- [Git Branching](#git-branching)
- [Commit Message Format](#commit-message-format)
- [Pull Request Flow](#pull-request-flow)
---
## How to Contribute
### đ Report Bugs
If you discover a bug, open a ticket via [GitHub Issues](https://github.com/DrizzleTime/Foxel/issues) and include:
- **A clear title** that summarises the problem.
- **Reproduction steps** with enough detail to trigger the bug.
- **Expected vs actual behaviour** to highlight the gap.
- **Environment details** such as operating system, browser version, and the Foxel build you used.
### ⨠Suggest Features
To propose a new capability or an improvement, create an Issue and choose the "Feature Request" template. Document:
- **Problem statement** â what pain point will the feature solve?
- **Proposed solution** â how you expect it to work.
- **Supporting material** â screenshots, references, or related links if helpful.
### đ ī¸ Contribute Code
Follow the development setup below before opening a pull request. Keep changes focused and small so they are easier to review.
## Development Environment
### Prerequisites
Install the following tooling first:
- **Git** for version control
- **Python** 3.13 or newer
- **Bun** for frontend package management and scripts
### Backend (FastAPI)
1. **Clone the repository**
```bash
git clone https://github.com/DrizzleTime/foxel.git
cd Foxel
```
2. **Create and activate a virtual environment**
`uv` is recommended for performance and reproducibility:
```bash
uv venv
source .venv/bin/activate
# On Windows: .venv\Scripts\activate
```
3. **Install dependencies**
```bash
uv sync
```
4. **Prepare local resources**
- Create the data directory:
```bash
mkdir -p data/db
```
Ensure the application user can read and write to `data/db`.
- Create an `.env` file in the project root and provide the required secrets. Replace the sample values with your own random strings:
```dotenv
SECRET_KEY=EnsRhL9NFPxgFVc+7t96/y70DIOR+9SpntcIqQa90TU=
TEMP_LINK_SECRET_KEY=EnsRhL9NFPxgFVc+7t96/y70DIOR+9SpntcIqQa90TU=
```
5. **Start the development server**
```bash
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```
The API is available at `http://localhost:8000`, and the interactive docs live at `http://localhost:8000/docs`.
### Frontend (React + Vite)
1. **Enter the frontend directory**
```bash
cd web
```
2. **Install dependencies**
```bash
bun install
```
3. **Run the dev server**
```bash
bun run dev
```
The Vite dev server runs at `http://localhost:5173` and proxies `/api` requests to the backend.
## Contribution Guidelines
### Storage Adapters
Storage adapters integrate new storage providers (for example S3, FTP, or Alist).
1. Create a new module under [`domain/adapters/providers/`](domain/adapters/providers/) (for example `my_new_adapter.py`).
2. Implement a class that inherits from [`domain.adapters.providers.base.BaseAdapter`](domain/adapters/providers/base.py) and provide concrete implementations for the abstract methods such as `list_dir`, `get_meta`, `upload`, and `download`.
### Frontend Apps
Frontend apps enable in-browser previews or editors for specific file types.
1. Add a new folder in [`web/src/apps/`](web/src/apps/) for your app and expose a React component.
2. Implement the `FoxelApp` interface defined in [`web/src/apps/types.ts`](web/src/apps/types.ts).
3. Register the app in [`web/src/apps/registry.ts`](web/src/apps/registry.ts) and declare the MIME types or extensions it supports.
## Submission Rules
### Git Branching
Start your work from the latest `main` branch and push feature changes on a dedicated branch.
### Commit Message Format
We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification to drive release tooling.
```
():