GithubBackup/Foxel

Fork 0

mirror of https://github.com/DrizzleTime/Foxel.git synced 2026-05-06 18:22:44 +08:00

Files

shiyu ad6b335169 feat: enhance README with detailed core features and usage instructions

2026-02-09 17:56:50 +08:00

5.5 KiB

Raw Permalink Blame History

English | 简体中文

Contributing to Foxel

We appreciate every minute you spend helping Foxel improve. This guide explains the contribution workflow so you can get started quickly.

How to Contribute
Development Environment
Contribution Guidelines
- Storage Adapters
- Frontend Apps
Submission Rules

How to Contribute

🐛 Report Bugs

If you discover a bug, open a ticket via GitHub 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.14 or newer
Bun for frontend package management and scripts

Backend (FastAPI)

Clone the repository

git clone https://github.com/DrizzleTime/foxel.git
cd Foxel

Create and activate a virtual environment

uv is recommended for performance and reproducibility:
```
uv venv
source .venv/bin/activate
# On Windows: .venv\Scripts\activate
```
Install dependencies
```
uv sync
```
Prepare local resources
- Create the data directory:
```
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:
```
SECRET_KEY=EnsRhL9NFPxgFVc+7t96/y70DIOR+9SpntcIqQa90TU=
TEMP_LINK_SECRET_KEY=EnsRhL9NFPxgFVc+7t96/y70DIOR+9SpntcIqQa90TU=
```
Start the development server
```
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)

Enter the frontend directory
```
cd web
```
Install dependencies
```
bun install
```
Run the dev server
```
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).

Create a new module under domain/adapters/providers/ (for example my_new_adapter.py).
Implement a class that inherits from domain.adapters.providers.base.BaseAdapter 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.

Add a new folder in web/src/apps/ for your app and expose a React component.
Implement the FoxelApp interface defined in web/src/apps/types.ts.
Register the app in 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 specification to drive release tooling.

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

type: e.g. feat, fix, docs, style, refactor, test, chore.
scope (optional): the area impacted by the change, such as adapter, ui, or api.
subject: a concise summary written in the imperative mood.

Examples:

feat(adapter): add support for Alist storage

fix(ui): correct display issue in file list view

Pull Request Flow

Fork the repository and clone it locally.
Create and switch to your feature branch.
Implement the change and run relevant checks.
Push the branch to your fork.
Open a pull request against main in the Foxel repository.
Explain the change set, its motivation, and reference related Issues in the PR description.

Maintainers will review your pull request as soon as possible.

5.5 KiB Raw Permalink Blame History Unescape Escape