Self-hosted personal gallery application with online photo management and albums, supporting Live/Motion Photos, EXIF parsing, geolocation recognition, and an explore map.
TypeScript albumsexif-extractiongeocodinglive-photomotion-photophoto-galleryphoto-sharingwebgl-viewer
docs: align the contribution guide with the 1.0.0 workflow
Timothy Yin607ce48e6f73
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex bcd269f8..b459cefc 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -1,349 +1,72 @@-# Contributing Guide+# Contributing-> This file **will not** be regularly updated to reflect minor changes. For the latest and most accurate information, please refer to the [official documentation](https://chronoframe.bh8.ga/guide/contributing.html).+Contributions to code, documentation and translations are welcome. The detailed guide is available in [English](https://chronoframe.bh8.ga/development/contributing) and [简体中文](https://chronoframe.bh8.ga/zh/development/contributing).-## Environment Requirements+Use Node.js 22, matching the Docker build, and the project's pinned pnpm 10.34.1. This repository contains workspace packages; install dependencies with pnpm.-### Required Software+## Run locally-- **Node.js**: 20.0+-- **pnpm**: 9.0+ (preferred package manager)-- **Git**: Latest version-- **Docker**: Optional, for containerized development--## Clone and Install--### 1. Clone Repository+Fork the repository on GitHub, then clone your fork (replace `YOUR_USERNAME` below):```bash-# Using HTTPS-git clone https://github.com/HoshinoSuzumi/chronoframe.git--# Or using SSH-git clone [email protected]:HoshinoSuzumi/chronoframe.git--# Enter project directory+git clone https://github.com/YOUR_USERNAME/chronoframe.gitcd chronoframe--# Set upstream remote repositorygit remote add upstream https://github.com/HoshinoSuzumi/chronoframe.git-```--### 2. Install Dependencies--```bash-# Install pnpm (if not already installed)-npm install -g pnpm--# Install project dependencies-pnpm install-```--### 3. Configure Environment Variables--```bash-# Copy environment variable template-cp .env.example .env--# Edit environment variables-nano .env # Or use your preferred editor-```--#### Minimal Development Configuration--```bash-# === Admin Account ===-CFRAME_ADMIN_NAME=Developer-CFRAME_ADMIN_PASSWORD=dev123456--# === Authentication Settings ===-NUXT_OAUTH_GITHUB_CLIENT_ID=your-dev-github-client-id-NUXT_OAUTH_GITHUB_CLIENT_SECRET=your-dev-github-client-secret-NUXT_SESSION_PASSWORD=your-32-character-development-key--# === Storage Settings (can use MinIO for development) ===-NUXT_STORAGE_PROVIDER=s3-NUXT_PROVIDER_S3_ENDPOINT=http://localhost:9000-NUXT_PROVIDER_S3_BUCKET=chronoframe-dev-NUXT_PROVIDER_S3_REGION=us-east-1-NUXT_PROVIDER_S3_ACCESS_KEY_ID=minioadmin-NUXT_PROVIDER_S3_SECRET_ACCESS_KEY=minioadmin--# === Map Services (optional) ===-NUXT_PUBLIC_MAPBOX_ACCESS_TOKEN=pk.your-development-token-NUXT_MAPBOX_ACCESS_TOKEN=sk.your-development-token-```--## Project Architecture--### Directory Structure--```-chronoframe/-├── app/ # Nuxt 4 application directory-│ ├── components/ # Vue components-│ │ ├── ui/ # Common UI components-│ │ ├── photo/ # Photo-related components-│ │ ├── masonry/ # Masonry layout components-│ │ └── ...-│ ├── pages/ # Route pages-│ ├── composables/ # Vue composables-│ ├── stores/ # Pinia state management-│ ├── layouts/ # Layout templates-│ ├── plugins/ # Nuxt plugins-│ └── utils/ # Utility functions-├── packages/-│ └── webgl-image/ # WebGL image viewer package-│ ├── src/-│ │ ├── core/ # Core engine-│ │ ├── components/ # Vue components-│ │ └── types/ # Type definitions-│ └── package.json-├── server/ # Nitro server-side-│ ├── api/ # API routes-│ │ ├── photos/ # Photo management API-│ │ ├── auth/ # Authentication API-│ │ └── system/ # System API-│ ├── database/ # Database related-│ │ ├── schema.ts # Database schema-│ │ └── migrations/ # Migration files-│ ├── services/ # Business logic services-│ │ ├── storage/ # Storage services-│ │ ├── image/ # Image processing-│ │ ├── location/ # Geolocation-│ │ └── pipeline-queue/ # Processing queue-│ ├── tasks/ # Background tasks-│ └── utils/ # Server-side utilities-├── shared/ # Shared code between frontend and backend-│ ├── types/ # TypeScript type definitions-│ └── utils/ # Shared utilities-├── docs/ # Project documentation-├── scripts/ # Build and deployment scripts-└── Configuration files...-```--### Technology Stack--#### Frontend Technologies--- **Nuxt 4**: Vue.js full-stack framework-- **TypeScript**: Type-safe JavaScript-- **TailwindCSS**: Utility-first CSS framework--#### Backend Technologies--- **Nitro**: Server-side framework-- **SQLite**: Lightweight database-- **Drizzle ORM**: Type-safe ORM-- **Sharp**: High-performance image processing-- **ExifTool**: EXIF data extraction--## Development Workflow--### Start Development Server--```bash-# Start complete development server+corepack enable+pnpm install --frozen-lockfilepnpm dev--# Or start step by step-pnpm build:deps # Build WebGL package-pnpm dlx nuxi@latest dev # Start Nuxt development server only```-### Database Operations--```bash-# Generate migration files-pnpm db:generate--# Execute database migrations-pnpm db:migrate-```+Open `http://localhost:3000` and use the wizard to create an administrator and choose local storage. `./data/storage` works for development. Database migrations run at startup; you do not need to generate migrations or fill out a minimal environment configuration just to run the app.-### Build Project+## Commands```bash-# Build WebGL dependency package+pnpm lint+pnpm fmt:checkpnpm build:deps--# Build complete projectpnpm build--# Preview production buildpnpm preview+pnpm docs:dev+pnpm docs:build```-## Testing Environment--### Local MinIO Storage--Run local MinIO service using Docker:--```bash-# Start MinIO-docker run -d \- --name minio \- -p 9000:9000 \- -p 9001:9001 \- -e "MINIO_ROOT_USER=minioadmin" \- -e "MINIO_ROOT_PASSWORD=minioadmin" \- minio/minio server /data --console-address ":9001"-```--Access MinIO console: http://localhost:9001--### GitHub OAuth App--1. Visit GitHub Settings > Developer settings > OAuth Apps-2. Create new OAuth app-3. Set callback URL: `http://localhost:3000/api/auth/github`-4. Copy Client ID and Client Secret to `.env` file--### Mapbox Development Tokens--1. Register [Mapbox account](https://account.mapbox.com/)-2. Create development access tokens-3. Set URL restriction: `http://localhost:3000`-4. Add tokens to `.env` file--## Code Standards--### TypeScript Standards--```typescript-// ✅ Good practice-interface PhotoMetadata {- id: string- title?: string- width: number- height: number- createdAt: Date-}--// ❌ Avoid using any-const processPhoto = (photo: any) => { ... }--// ✅ Use specific types-const processPhoto = (photo: PhotoMetadata) => { ... }-```--### Vue Component Standards--```vue-<!-- ✅ Recommended component structure -->-<script setup lang="ts">-// Imports-import { ref, computed } from 'vue'-import type { Photo } from '~/types'--// Props and Emits-interface Props {- photos: Photo[]- loading?: boolean-}+`pnpm dev` runs the WebGL package development build alongside Nuxt. Once the dependency package is built, use `pnpm dev:only` to start Nuxt alone. Code checks use Oxlint; formatting uses Oxfmt.-interface Emits {- select: [photo: Photo]- delete: [photoId: string]-}+After changing the database schema, run `pnpm db:generate` and review the generated SQL. `pnpm db:migrate` applies migrations manually. Keep local databases, photos and credentials out of Git.-const props = withDefaults(defineProps<Props>(), {- loading: false,-})+## Where code lives-const emit = defineEmits<Emits>()+- `app/`: pages, components, composables and Pinia stores.+- `packages/webgl-image/`: the WebGL image viewer.+- `server/api/`: API routes; `server/services/`: storage, settings and photo processing.+- `server/database/`: Drizzle schema and migrations.+- `shared/`: shared types; `i18n/`: translations.+- `docs/`: English and Chinese documentation.-// Reactive data-const selectedPhoto = ref<Photo | null>(null)+For new dashboard settings, read [Adding a setting](docs/development/how-to-add-setting.md). Enter test credentials for S3, OpenList, maps or GitHub login in the dashboard. Use `http://localhost:3000/api/auth/github` as the local OAuth callback.-// Computed properties-const photoCount = computed(() => props.photos.length)+## Submit a change-// Methods-const handlePhotoClick = (photo: Photo) => {- selectedPhoto.value = photo- emit('select', photo)-}-</script>+Create a branch for your change:-<template>- <div class="photo-grid">- <!-- Template content -->- </div>-</template>--<style scoped>-/* Component styles */-</style>-```--### Database Calls--When using database operations in `server`, use `useDB()` to get the Drizzle instance. This composable is globally auto-imported on the server side:--```typescript-const db = useDB()--const photos = await db.select().from(photosTable)-```--### Commit Message Standards--Use [Conventional Commits](https://www.conventionalcommits.org/) standard:--```-feat: add photo batch delete functionality-fix: fix WebGL viewer compatibility issue in Safari-docs: update deployment documentation-style: unify code formatting-refactor: refactor storage service interface-test: add unit tests for photo upload-chore: update dependency versions+```bash+git checkout -b feature/your-change```-## Contribution Guidelines--### Development Process--1. **Fork Project**: Fork the project on GitHub-2. **Create Branch**: `git checkout -b feature/new-feature`-3. **Develop Feature**: Write code and tests-4. **Commit Changes**: Use standard commit messages-5. **Push Branch**: `git push origin feature/new-feature`-6. **Create PR**: Create Pull Request on GitHub--### Pull Request Checklist--Before submitting PR, ensure:--- Code passes all tests-- Follows code standards-- Updates relevant documentation-- Adds appropriate test cases-- PR description is clear with change explanations--## Contribution Opportunities--### Beginner-friendly Tasks--Look for Issues labeled with:--- `good first issue`: Tasks suitable for beginners-- `help wanted`: Tasks needing community help-- `documentation`: Documentation-related improvements+Keep changes focused and use Conventional Commits. Explain the problem, resulting behavior and verification in your PR. Include screenshots for UI changes and update both language versions for documentation changes. Issues marked `good first issue` or `help wanted` are useful starting points.-## Useful Resources+Before opening a pull request:-### Official Documentation+- Run `pnpm lint` and `pnpm fmt:check`. Use `pnpm lint:fix` and `pnpm fmt` when needed, keeping unrelated formatting changes out of the PR.+- For application changes, build the WebGL package and application with `pnpm build:deps` and `pnpm build`, then check the affected behavior.+- For documentation changes, run `pnpm docs:build` and check the relevant pages and links.+- For database changes, review the migration SQL and check both a fresh installation and an upgrade from existing data.+- Add or update tests where they help verify the change. There is no project-wide test command in `package.json`; report the specific checks you performed.+- Keep credentials, local databases and uploaded files out of commits. Include screenshots for UI changes and describe any compatibility changes.-- [Nuxt 4 Documentation](https://nuxt.com/)-- [Vue 3 Documentation](https://vuejs.org/)-- [Drizzle ORM Documentation](https://orm.drizzle.team/)-- [TailwindCSS Documentation](https://tailwindcss.com/)+Push your branch to your fork and open a pull request. State what problem it solves, how behavior changes and what you verified. If it fixes an issue, link that issue in the description.-### Community Resources+## Report an issue or discuss an idea-- [GitHub Issues](https://github.com/HoshinoSuzumi/chronoframe/issues)-- [GitHub Discussions](https://github.com/HoshinoSuzumi/chronoframe/discussions)+Use the [issue template chooser](https://github.com/HoshinoSuzumi/chronoframe/issues/new/choose) to report bugs or request features. For a bug, include the version, deployment method, storage type, reproduction steps and relevant logs with secrets removed. Use [GitHub Discussions](https://github.com/HoshinoSuzumi/chronoframe/discussions) or [Discord](https://discord.gg/MM4ZK4Ed7s) for questions and ideas.