From 50d549992f87deb592a9095a54b6e8cdaa52cf5b Mon Sep 17 00:00:00 2001 From: hu-qi Date: Sat, 6 Sep 2025 04:00:10 +0800 Subject: [PATCH 1/8] =?UTF-8?q?feat:=20=E5=AE=8C=E6=88=90=E8=A1=8C?= =?UTF-8?q?=E4=B8=BA=E8=A7=84=E8=8C=83=E6=96=87=E6=A1=A3=E5=AE=9E=E7=8E=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 替换"正在制定中……"占位内容为完整的行为规范文档 - 基于 freeCodeCamp 行为规范和参与者公约 2.0 版 - 包含6大核心条款：法律合规、反骚扰、尊重交流、隐私保护、内容质量、社区参与 - 添加举报渠道和执行机制说明 - 符合项目 MDX 格式和 Bootstrap 样式规范 - 已集成到网站导航系统中 Closes #22 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- CLAUDE.md | 386 ++++++++++++++++++++++++++++++ pages/article/code-of-conduct.mdx | 81 ++++++- 2 files changed, 466 insertions(+), 1 deletion(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..81e62ca --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,386 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +**Open Source Bazaar** (开源市集) is an open-source project showcase platform built with Next.js 15, TypeScript, React Bootstrap, and MobX. The platform serves as a comprehensive hub for open-source collaboration, featuring license filtering tools, Wiki knowledge base integration, volunteer showcases, and GitHub repository management. + +### Key Features + +- **License Filter Tool**: Interactive multi-step license selection process with comprehensive i18n support +- **Wiki Knowledge Base**: Integration with GitHub ContentModel to access policy documents +- **Volunteer Showcase**: GitHub organization contributor displays with OSS Insight widgets +- **Project Repository**: GitHub repository listings and management +- **Multi-language Support**: Full i18n with Chinese (Simplified/Traditional) and English +- **Lark Integration**: Enterprise collaboration platform integration +- **PWA Support**: Progressive Web App capabilities + +## Repository Structure + +### Important Directories + +- **`pages/`** - Next.js pages and API routes + - `index.tsx` - Homepage with animated welcome content + - `license-filter.tsx` - Interactive license selection tool + - `policy/` - Wiki/policy document pages + - `volunteer.tsx` - Contributor showcase + - `project.tsx` - GitHub repository listings + - `api/` - API routes for external integrations + +- **`components/`** - Reusable React components with Bootstrap styling + - `Layout/` - Page layout components (PageHead, Navigation, Footer) + - `Git/` - GitHub-related components + - `Navigator/` - Navigation components + - `PageContent/` - Content display components + - `License/` - License filter components + +- **`models/`** - MobX stores and data models + - `Base.ts` - Core configuration and client setup + - `Repository.ts` - GitHub repository data models + - `Translation.ts` - i18n translation models + - `Wiki.ts` - Wiki content models + - `System.ts` - System configuration models + +- **`translation/`** - i18n language files + - `zh-CN.ts` - Simplified Chinese + - `zh-TW.ts` - Traditional Chinese + - `en-US.ts` - English + +- **`styles/`** - CSS and styling files +- **`public/`** - Static assets and PWA manifest +- **`types/`** - TypeScript type definitions + +### Configuration Files + +- **`package.json`** - Dependencies and scripts +- **`next.config.ts`** - Next.js configuration with MDX, PWA, and proxy rewrites +- **`tsconfig.json`** - TypeScript configuration +- **`eslint.config.ts`** - ESLint configuration with spell checking +- **`babel.config.js`** - Babel configuration for decorators +- **`.github/copilot-instructions.md`** - Detailed development guidelines + +## Technology Stack + +### Core Technologies + +- **Next.js 15** - React framework with App Router +- **TypeScript 5.9** - Type-safe JavaScript +- **React 19.1** - UI library with hooks +- **React Bootstrap 2.10** - UI component library +- **MobX 6.13** - State management +- **PNPM** - Package manager + +### Key Dependencies + +- **MobX Ecosystem**: + - `mobx-github` - GitHub API integration + - `mobx-i18n` - Internationalization + - `mobx-restful` - RESTful API client + - `mobx-restful-table` - Data table components + - `mobx-lark` - Lark integration + - `mobx-react` - React bindings + +- **Content Processing**: + - `@mdx-js/react` - MDX support + - `marked` - Markdown processing + - `yaml` - YAML front-matter processing + +- **Development Tools**: + - `eslint` - Code linting + - `prettier` - Code formatting + - `husky` - Git hooks + - `lint-staged` - Pre-commit linting + +- **Utilities**: + - `web-utility` - Web utility functions + - `license-filter` - License filtering logic + - `koajax` - HTTP client + - `idea-react` - React utilities + +## Development Environment + +### Critical Requirements + +⚠️ **MANDATORY NODE.JS VERSION**: This project requires **Node.js >=20** + +- Check Node.js version: `node --version` +- Development and linting commands work on Node.js 20+ +- Use **PNPM** as package manager, not NPM or Yarn + +### Initial Setup + +1. **Install global pnpm**: `npm install -g pnpm` +2. **Install dependencies**: `pnpm install` -- takes 1-3 minutes. NEVER CANCEL +3. **Verify setup**: `pnpm --version` (should be 10.x+) + +**Important**: If you see "node_modules missing" error, you MUST run `pnpm install` first before any other commands. + +### Development Workflow + +```bash +# Development +pnpm dev # Start development server (5-15s) on http://localhost:3000 +pnpm build # Production build (30s-2min) +pnpm start # Start production server + +# Code Quality +pnpm lint # Run ESLint with auto-fix (15s) +pnpm test # Run tests (lint-staged + lint, 15s) + +# Git Hooks +pnpm prepare # Install husky hooks +``` + +## Development Standards + +### Architecture and Code Organization + +#### Component Standards + +- **ALWAYS use React Bootstrap components** instead of custom HTML elements +- Use utilities from established libraries: 'web-utility' +- Import `'./Base'` in model files for proper configuration +- Use semantic HTML structure: `
`, `
`, `
` + +#### Import Patterns + +```typescript +// ✅ Correct - use React Bootstrap components +import { Button, Badge, Breadcrumb, Card, Container } from 'react-bootstrap'; + +// ✅ Correct - import from established sources +import { ContentModel } from 'mobx-github'; +import { githubClient } from 'mobx-github'; +import { treeFrom } from 'web-utility'; +import './Base'; // For GitHub client setup + +// ❌ Wrong - custom HTML elements +Edit +{label} +``` + +#### Error Handling + +- **Natural error throwing** for static generation - let errors bubble up to catch build issues +- Ensure build passes before pushing - resolve issues at compile time + +### Translation and Internationalization + +#### Critical Requirements + +- **ALL user-facing text** MUST be translated using i18n system +- Use the `t()` function from I18nContext for all translations +- This includes button text, labels, error messages, placeholder text, and dynamic content + +#### Translation Patterns + +```typescript +// ✅ Correct - use translation function + + +// ❌ Wrong - hardcoded text + +``` + +#### Translation Key Management + +- Use generic terms unless specifically scoped: `t('knowledge_base')` not `t('policy_documents')` +- Add translation keys to ALL language files: `zh-CN.ts`, `en-US.ts`, `zh-TW.ts` +- Remove unused translation keys when replacing with generic ones + +### Data Modeling and GitHub Integration + +#### Content Model Patterns + +- Use ContentModel with configured client from mobx-github +- Import configuration via `'./Base'` to ensure proper GitHub client setup +- Handle Base64 content decoding when processing GitHub API responses + +#### GitHub API Usage + +```typescript +// ✅ Correct - use configured client +import { githubClient } from './models/Base'; + +// ❌ Wrong - create separate instances +const client = new GitHubClient(); +``` + +#### Authentication and Rate Limiting + +- GitHub API authentication is configured in `models/Base.ts` +- Use the configured client to avoid rate limiting and authentication issues +- Don't create separate GitHub API instances + +### Code Quality Standards + +#### Modern ECMAScript Features + +- Use optional chaining and modern JavaScript features +- Let TypeScript infer types when possible to avoid verbose annotations +- Use modern ECMAScript patterns for cleaner, more maintainable code + +#### Import and Type Management + +- Import from established sources: ContentModel from mobx-github, utilities from web-utility +- Import configuration files where needed: `'./Base'` for GitHub client setup +- Use minimal exports and avoid unnecessary custom implementations + +### Build and Development Process + +#### Pre-commit Standards + +1. **Run linting**: `pnpm lint` to auto-fix formatting +2. **Check build**: Ensure `pnpm build` passes +3. **Validate translations**: Verify all text is properly translated +4. **Remove unused code**: Clean up unused imports and translation keys + +#### Testing Requirements + +After making ANY changes, ALWAYS validate by running through these scenarios: + +1. **Start development server**: `pnpm dev` and verify it starts without errors +2. **Navigate to homepage**: Visit http://localhost:3000 and verify page loads +3. **Test core pages**: + - License filter: http://localhost:3000/license-filter + - Wiki pages: http://localhost:3000/policy + - Volunteer page: http://localhost:3000/volunteer + - Projects: http://localhost:3000/project +4. **Test API endpoints**: Verify GitHub API integrations work +5. **Check responsive design**: Test mobile/desktop layouts +6. **Verify i18n functionality**: Check language switching works + +## Project-Specific Patterns + +### Wiki System Architecture + +- Uses GitHub ContentModel to access policy documents from `fpsig/open-source-policy` repository +- Renders markdown content with front-matter metadata +- Supports hierarchical document structure with breadcrumb navigation +- Uses `treeFrom` utility from web-utility for hierarchical data structures + +### License Filter Integration + +- Interactive multi-step license selection process +- Uses `license-filter` package for license recommendation logic +- Supports multiple languages with comprehensive i18n coverage +- Complex state management with MobX stores + +### Volunteer Management + +- Displays GitHub organization contributors +- Integrates with OSS Insight widgets for contributor analytics +- Uses GitHub API for real-time contributor data +- Features contributor cards with activity metrics + +### Proxy Configuration + +The project includes proxy rewrites for external services: +- GitHub API and raw content +- Alibaba Geo Data services +- Lark API integration + +## Common Issues and Solutions + +### Build and Development Issues + +- **"Unsupported engine" warnings**: Expected on Node.js <22, development still works +- **Build hangs**: Never cancel builds - they may take several minutes, set appropriate timeouts +- **Missing dependencies**: Always run `pnpm install` first + +### Component and Styling Issues + +- **Custom HTML not working**: Replace with React Bootstrap components +- **Translation not showing**: Ensure all text uses `t()` function and keys exist in all language files +- **GitHub API errors**: Verify you're using configured `githubClient` from `models/Base.ts` + +### Data and Content Issues + +- **Base64 content errors**: Use `atob(item.content)` to decode GitHub API responses +- **Missing content**: Check ContentModel configuration and repository access +- **Tree structure problems**: Use `treeFrom()` utility from web-utility + +### Development Environment Setup + +- Clear browser cache if components don't render properly +- Restart development server after major configuration changes +- Verify all translation files are updated when adding new keys + +## Deployment and CI/CD + +### Vercel Deployment + +- Project is configured for Vercel deployment +- Uses GitHub Actions for CI/CD pipeline +- PWA support enabled for offline functionality + +### Environment Variables + +- `NODE_ENV` - Environment detection +- `CI` - Continuous integration flag +- `GithubToken` - GitHub API authentication +- `API_Host` - Backend API host +- `LARK_API_HOST` - Lark API host + +## Contributing Guidelines + +### Code Review Process + +- **Follow exact code suggestions** from reviews when provided +- Use **minimal approach** - only include explicitly requested functionality +- **Don't add extra features** not specified in requirements +- **Address reviewer feedback completely** before requesting re-review + +### Pull Request Template + +```markdown +Checklist（清单）: + +- [ ] Labels +- [ ] Assignees +- [ ] Reviewers + +Closes #XXXXX +``` + +### Quality Gates + +- [ ] All tests pass +- [ ] Code follows project conventions +- [ ] No linting errors +- [ ] Build succeeds +- [ ] Translations are complete +- [ ] Responsive design verified +- [ ] API integrations working + +## Resources and Documentation + +### Internal Resources + +- **`.github/copilot-instructions.md`** - Detailed development guidelines +- **`README.md`** - Project overview and quick start +- **`package.json`** - Complete dependency list +- **Translation files** - All supported languages and keys + +### External Dependencies + +- [Next.js Documentation](https://nextjs.org/) +- [React Bootstrap Documentation](https://react-bootstrap.github.io/) +- [MobX Documentation](https://mobx.js.org/) +- [TypeScript Documentation](https://www.typescriptlang.org/) +- [PNPM Documentation](https://pnpm.io/) + +### Key Repository Links + +- [Upstream Project](https://github.com/idea2app/Lark-Next-Bootstrap-ts) +- [GitHub Actions CI/CD](https://github.com/Open-Source-Bazaar/Open-Source-Bazaar.github.io/actions) +- [Live Demo](https://bazaar.fcc-cd.dev/) + +## Contact and Support + +For project-specific questions, refer to the existing documentation and GitHub issues. For development guidance, follow the patterns and conventions established in the codebase and the detailed copilot instructions. \ No newline at end of file diff --git a/pages/article/code-of-conduct.mdx b/pages/article/code-of-conduct.mdx index fc55d21..ac45d18 100644 --- a/pages/article/code-of-conduct.mdx +++ b/pages/article/code-of-conduct.mdx @@ -1,3 +1,82 @@ # 行为规范 -正在制定中…… +## 引言 + +开源市集致力于创建一个友好、包容、协作的开源社区环境。我们相信，通过建立明确的行为准则，可以促进健康的交流氛围，让每位参与者都能在相互尊重的基础上共同成长。 + +## 适用范围 + +本行为规范适用于开源市集的所有互动场景，包括但不限于： +- 微信群和飞书群讨论 +- 线下活动现场 +- GitHub 组织和仓库 +- 其他官方社区渠道 + +**所有参与者（包括但不限于共创方、志愿者、观众）参与开源市集，即表示其同意遵守以下行为规范。** + +### 1. 法律合规 +应严格遵守中华人民共和国及当地的法律法规。我们期望所有参与者在社区互动中遵守当地法律，维护社区的法律合规性。 + +### 2. 反骚扰条款 +不应公开或私下骚扰他人，不论其年龄、体型、身体条件、民族、性征、性别认同与表现、经验水平、教育程度、社会地位、国籍、相貌、种族、宗教信仰、政治主张及性取向如何。 + +**骚扰内容包括但不限于**： +- 与性相关的语言和图片 +- 蓄意恐吓、跟踪、辱骂 +- 令人不适的关注 +- 诽谤以及任何恶意攻击或社交行为 + +### 3. 尊重交流 +不得挑衅他人，包括但不限于发布煽动性言论，以引起不良情绪反应或破坏讨论。我们鼓励： +- 建设性的意见交流 +- 礼貌的辩论和讨论 +- 对不同观点的尊重和理解 + +### 4. 隐私保护 +尊重隐私。未获明确授权，不得擅自发布他人的资料，如地址、电子邮箱等隐私信息。我们承诺： +- 保护参与者的个人信息 +- 不未经允许分享私人联系方式 +- 尊重个人边界和隐私权 + +### 5. 内容质量 +不得随意发布垃圾信息，包括但不限于与开源、开放式协作或公益无关的信息。我们提倡： +- 分享有价值的开源相关内容 +- 避免频繁的广告或无关信息 +- 保持讨论主题的相关性 + +### 6. 社区参与 +开源市集作为一个开源社群，鼓励每位参与者在己所能及的情况下，参与社群共创，或为他人提供帮助，但这不是一个强制性要求。 + +**参与方式包括**： +- 分享技术经验和知识 +- 帮助新手解决问题 +- 参与项目贡献和改进 +- 组织或参与社区活动 + +## 举报与执行 + +### 举报渠道 +如果你在开源市集的任何地方发现有人违反以上行为规范，请立即通知社群管理小组： +- **微信群或飞书群管理员** +- **活动出品人** +- **GitHub 组织维护者** + +### 执行措施 +管理小组将根据违规情况的严重程度，采取适当措施，包括但不限于： +- 口头警告和提醒 +- 临时禁言或限制权限 +- 永久移除违反者从开源市集社群中 + +## 来源与参考 + +本行为规范改编自以下优秀开源项目的行为准则： + +- [freeCodeCamp 行为规范](https://chinese.freecodecamp.org/news/code-of-conduct/) +- [参与者公约 2.0 版](https://www.contributor-covenant.org/zh-cn/version/2/0/code_of_conduct.html) + +我们感谢这些项目为开源社区行为准则建设做出的贡献。 + +--- + +**最后更新：** 2025年9月 +**版本：** 1.1 From 24b174ead9d3718d1e274fb0a074db8eb9d25b4b Mon Sep 17 00:00:00 2001 From: huqi Date: Mon, 8 Sep 2025 09:16:52 +0800 Subject: [PATCH 2/8] Apply suggestions from code review Co-authored-by: South Drifter --- pages/article/code-of-conduct.mdx | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/pages/article/code-of-conduct.mdx b/pages/article/code-of-conduct.mdx index ac45d18..2f38aa4 100644 --- a/pages/article/code-of-conduct.mdx +++ b/pages/article/code-of-conduct.mdx @@ -7,10 +7,11 @@ ## 适用范围 本行为规范适用于开源市集的所有互动场景，包括但不限于： -- 微信群和飞书群讨论 -- 线下活动现场 +- 微信、飞书群讨论 +- 线上线下会议 +- 线上线下活动 - GitHub 组织和仓库 -- 其他官方社区渠道 +- 其它官方社区渠道 **所有参与者（包括但不限于共创方、志愿者、观众）参与开源市集，即表示其同意遵守以下行为规范。** @@ -18,7 +19,7 @@ 应严格遵守中华人民共和国及当地的法律法规。我们期望所有参与者在社区互动中遵守当地法律，维护社区的法律合规性。 ### 2. 反骚扰条款 -不应公开或私下骚扰他人，不论其年龄、体型、身体条件、民族、性征、性别认同与表现、经验水平、教育程度、社会地位、国籍、相貌、种族、宗教信仰、政治主张及性取向如何。 +不应公开或私下骚扰他人，不论其年龄、体型、身体条件、民族、性征、性别认同与表现、性取向、经验水平、教育程度、社会地位、国籍、相貌、种族、宗教信仰、政治主张如何。 **骚扰内容包括但不限于**： - 与性相关的语言和图片 @@ -33,7 +34,7 @@ - 对不同观点的尊重和理解 ### 4. 隐私保护 -尊重隐私。未获明确授权，不得擅自发布他人的资料，如地址、电子邮箱等隐私信息。我们承诺： +尊重隐私。未获明确授权，不得擅自发布他人的资料，如地址、电子邮箱、手机等隐私信息。我们承诺： - 保护参与者的个人信息 - 不未经允许分享私人联系方式 - 尊重个人边界和隐私权 @@ -45,7 +46,7 @@ - 保持讨论主题的相关性 ### 6. 社区参与 -开源市集作为一个开源社群，鼓励每位参与者在己所能及的情况下，参与社群共创，或为他人提供帮助，但这不是一个强制性要求。 +开源市集作为一个开放社群，鼓励每位参与者在己所能及的情况下，参与社群共创，或为他人提供帮助，但这不是一个强制性要求。 **参与方式包括**： - 分享技术经验和知识 @@ -57,15 +58,15 @@ ### 举报渠道 如果你在开源市集的任何地方发现有人违反以上行为规范，请立即通知社群管理小组： -- **微信群或飞书群管理员** -- **活动出品人** +- **微信或飞书群管理员** +- **活动组织者** - **GitHub 组织维护者** ### 执行措施 管理小组将根据违规情况的严重程度，采取适当措施，包括但不限于： - 口头警告和提醒 - 临时禁言或限制权限 -- 永久移除违反者从开源市集社群中 +- 从开源市集社群中永久移除违反者 ## 来源与参考 @@ -76,7 +77,5 @@ 我们感谢这些项目为开源社区行为准则建设做出的贡献。 ---- - -**最后更新：** 2025年9月 -**版本：** 1.1 +> - **最后更新**：2025年9月 +> - **版本**：1.0 From 62afe1fb00ae154b504c89a0c2a4b36fb97f8c96 Mon Sep 17 00:00:00 2001 From: hu-qi Date: Mon, 8 Sep 2025 10:04:17 +0800 Subject: [PATCH 3/8] =?UTF-8?q?fix:=20=E4=BF=AE=E6=AD=A3=E7=89=88=E6=9C=AC?= =?UTF-8?q?=E4=BF=A1=E6=81=AF?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- pages/article/code-of-conduct.mdx | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/pages/article/code-of-conduct.mdx b/pages/article/code-of-conduct.mdx index 2f38aa4..72eac09 100644 --- a/pages/article/code-of-conduct.mdx +++ b/pages/article/code-of-conduct.mdx @@ -1,5 +1,14 @@ +--- +title: "行为规范" +last_updated: "2025年9月" +version: "1.0" +--- + # 行为规范 +> - **最后更新**：2025年9月 +> - **版本**：1.0 + ## 引言 开源市集致力于创建一个友好、包容、协作的开源社区环境。我们相信，通过建立明确的行为准则，可以促进健康的交流氛围，让每位参与者都能在相互尊重的基础上共同成长。 @@ -76,6 +85,3 @@ - [参与者公约 2.0 版](https://www.contributor-covenant.org/zh-cn/version/2/0/code_of_conduct.html) 我们感谢这些项目为开源社区行为准则建设做出的贡献。 - -> - **最后更新**：2025年9月 -> - **版本**：1.0 From 3775d1e289bca6a7b42f9dc7af485d9b87dad258 Mon Sep 17 00:00:00 2001 From: hu-qi Date: Mon, 8 Sep 2025 10:04:38 +0800 Subject: [PATCH 4/8] =?UTF-8?q?fix:=20=E7=A7=BB=E9=99=A4=20CLAUDE.md=20?= =?UTF-8?q?=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 386 ------------------------------------------------------ 1 file changed, 386 deletions(-) delete mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 81e62ca..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,386 +0,0 @@ -# CLAUDE.md - -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - -**Open Source Bazaar** (开源市集) is an open-source project showcase platform built with Next.js 15, TypeScript, React Bootstrap, and MobX. The platform serves as a comprehensive hub for open-source collaboration, featuring license filtering tools, Wiki knowledge base integration, volunteer showcases, and GitHub repository management. - -### Key Features - -- **License Filter Tool**: Interactive multi-step license selection process with comprehensive i18n support -- **Wiki Knowledge Base**: Integration with GitHub ContentModel to access policy documents -- **Volunteer Showcase**: GitHub organization contributor displays with OSS Insight widgets -- **Project Repository**: GitHub repository listings and management -- **Multi-language Support**: Full i18n with Chinese (Simplified/Traditional) and English -- **Lark Integration**: Enterprise collaboration platform integration -- **PWA Support**: Progressive Web App capabilities - -## Repository Structure - -### Important Directories - -- **`pages/`** - Next.js pages and API routes - - `index.tsx` - Homepage with animated welcome content - - `license-filter.tsx` - Interactive license selection tool - - `policy/` - Wiki/policy document pages - - `volunteer.tsx` - Contributor showcase - - `project.tsx` - GitHub repository listings - - `api/` - API routes for external integrations - -- **`components/`** - Reusable React components with Bootstrap styling - - `Layout/` - Page layout components (PageHead, Navigation, Footer) - - `Git/` - GitHub-related components - - `Navigator/` - Navigation components - - `PageContent/` - Content display components - - `License/` - License filter components - -- **`models/`** - MobX stores and data models - - `Base.ts` - Core configuration and client setup - - `Repository.ts` - GitHub repository data models - - `Translation.ts` - i18n translation models - - `Wiki.ts` - Wiki content models - - `System.ts` - System configuration models - -- **`translation/`** - i18n language files - - `zh-CN.ts` - Simplified Chinese - - `zh-TW.ts` - Traditional Chinese - - `en-US.ts` - English - -- **`styles/`** - CSS and styling files -- **`public/`** - Static assets and PWA manifest -- **`types/`** - TypeScript type definitions - -### Configuration Files - -- **`package.json`** - Dependencies and scripts -- **`next.config.ts`** - Next.js configuration with MDX, PWA, and proxy rewrites -- **`tsconfig.json`** - TypeScript configuration -- **`eslint.config.ts`** - ESLint configuration with spell checking -- **`babel.config.js`** - Babel configuration for decorators -- **`.github/copilot-instructions.md`** - Detailed development guidelines - -## Technology Stack - -### Core Technologies - -- **Next.js 15** - React framework with App Router -- **TypeScript 5.9** - Type-safe JavaScript -- **React 19.1** - UI library with hooks -- **React Bootstrap 2.10** - UI component library -- **MobX 6.13** - State management -- **PNPM** - Package manager - -### Key Dependencies - -- **MobX Ecosystem**: - - `mobx-github` - GitHub API integration - - `mobx-i18n` - Internationalization - - `mobx-restful` - RESTful API client - - `mobx-restful-table` - Data table components - - `mobx-lark` - Lark integration - - `mobx-react` - React bindings - -- **Content Processing**: - - `@mdx-js/react` - MDX support - - `marked` - Markdown processing - - `yaml` - YAML front-matter processing - -- **Development Tools**: - - `eslint` - Code linting - - `prettier` - Code formatting - - `husky` - Git hooks - - `lint-staged` - Pre-commit linting - -- **Utilities**: - - `web-utility` - Web utility functions - - `license-filter` - License filtering logic - - `koajax` - HTTP client - - `idea-react` - React utilities - -## Development Environment - -### Critical Requirements - -⚠️ **MANDATORY NODE.JS VERSION**: This project requires **Node.js >=20** - -- Check Node.js version: `node --version` -- Development and linting commands work on Node.js 20+ -- Use **PNPM** as package manager, not NPM or Yarn - -### Initial Setup - -1. **Install global pnpm**: `npm install -g pnpm` -2. **Install dependencies**: `pnpm install` -- takes 1-3 minutes. NEVER CANCEL -3. **Verify setup**: `pnpm --version` (should be 10.x+) - -**Important**: If you see "node_modules missing" error, you MUST run `pnpm install` first before any other commands. - -### Development Workflow - -```bash -# Development -pnpm dev # Start development server (5-15s) on http://localhost:3000 -pnpm build # Production build (30s-2min) -pnpm start # Start production server - -# Code Quality -pnpm lint # Run ESLint with auto-fix (15s) -pnpm test # Run tests (lint-staged + lint, 15s) - -# Git Hooks -pnpm prepare # Install husky hooks -``` - -## Development Standards - -### Architecture and Code Organization - -#### Component Standards - -- **ALWAYS use React Bootstrap components** instead of custom HTML elements -- Use utilities from established libraries: 'web-utility' -- Import `'./Base'` in model files for proper configuration -- Use semantic HTML structure: `
`, `
`, `
` - -#### Import Patterns - -```typescript -// ✅ Correct - use React Bootstrap components -import { Button, Badge, Breadcrumb, Card, Container } from 'react-bootstrap'; - -// ✅ Correct - import from established sources -import { ContentModel } from 'mobx-github'; -import { githubClient } from 'mobx-github'; -import { treeFrom } from 'web-utility'; -import './Base'; // For GitHub client setup - -// ❌ Wrong - custom HTML elements -Edit -{label} -``` - -#### Error Handling - -- **Natural error throwing** for static generation - let errors bubble up to catch build issues -- Ensure build passes before pushing - resolve issues at compile time - -### Translation and Internationalization - -#### Critical Requirements - -- **ALL user-facing text** MUST be translated using i18n system -- Use the `t()` function from I18nContext for all translations -- This includes button text, labels, error messages, placeholder text, and dynamic content - -#### Translation Patterns - -```typescript -// ✅ Correct - use translation function - - -// ❌ Wrong - hardcoded text - -``` - -#### Translation Key Management - -- Use generic terms unless specifically scoped: `t('knowledge_base')` not `t('policy_documents')` -- Add translation keys to ALL language files: `zh-CN.ts`, `en-US.ts`, `zh-TW.ts` -- Remove unused translation keys when replacing with generic ones - -### Data Modeling and GitHub Integration - -#### Content Model Patterns - -- Use ContentModel with configured client from mobx-github -- Import configuration via `'./Base'` to ensure proper GitHub client setup -- Handle Base64 content decoding when processing GitHub API responses - -#### GitHub API Usage - -```typescript -// ✅ Correct - use configured client -import { githubClient } from './models/Base'; - -// ❌ Wrong - create separate instances -const client = new GitHubClient(); -``` - -#### Authentication and Rate Limiting - -- GitHub API authentication is configured in `models/Base.ts` -- Use the configured client to avoid rate limiting and authentication issues -- Don't create separate GitHub API instances - -### Code Quality Standards - -#### Modern ECMAScript Features - -- Use optional chaining and modern JavaScript features -- Let TypeScript infer types when possible to avoid verbose annotations -- Use modern ECMAScript patterns for cleaner, more maintainable code - -#### Import and Type Management - -- Import from established sources: ContentModel from mobx-github, utilities from web-utility -- Import configuration files where needed: `'./Base'` for GitHub client setup -- Use minimal exports and avoid unnecessary custom implementations - -### Build and Development Process - -#### Pre-commit Standards - -1. **Run linting**: `pnpm lint` to auto-fix formatting -2. **Check build**: Ensure `pnpm build` passes -3. **Validate translations**: Verify all text is properly translated -4. **Remove unused code**: Clean up unused imports and translation keys - -#### Testing Requirements - -After making ANY changes, ALWAYS validate by running through these scenarios: - -1. **Start development server**: `pnpm dev` and verify it starts without errors -2. **Navigate to homepage**: Visit http://localhost:3000 and verify page loads -3. **Test core pages**: - - License filter: http://localhost:3000/license-filter - - Wiki pages: http://localhost:3000/policy - - Volunteer page: http://localhost:3000/volunteer - - Projects: http://localhost:3000/project -4. **Test API endpoints**: Verify GitHub API integrations work -5. **Check responsive design**: Test mobile/desktop layouts -6. **Verify i18n functionality**: Check language switching works - -## Project-Specific Patterns - -### Wiki System Architecture - -- Uses GitHub ContentModel to access policy documents from `fpsig/open-source-policy` repository -- Renders markdown content with front-matter metadata -- Supports hierarchical document structure with breadcrumb navigation -- Uses `treeFrom` utility from web-utility for hierarchical data structures - -### License Filter Integration - -- Interactive multi-step license selection process -- Uses `license-filter` package for license recommendation logic -- Supports multiple languages with comprehensive i18n coverage -- Complex state management with MobX stores - -### Volunteer Management - -- Displays GitHub organization contributors -- Integrates with OSS Insight widgets for contributor analytics -- Uses GitHub API for real-time contributor data -- Features contributor cards with activity metrics - -### Proxy Configuration - -The project includes proxy rewrites for external services: -- GitHub API and raw content -- Alibaba Geo Data services -- Lark API integration - -## Common Issues and Solutions - -### Build and Development Issues - -- **"Unsupported engine" warnings**: Expected on Node.js <22, development still works -- **Build hangs**: Never cancel builds - they may take several minutes, set appropriate timeouts -- **Missing dependencies**: Always run `pnpm install` first - -### Component and Styling Issues - -- **Custom HTML not working**: Replace with React Bootstrap components -- **Translation not showing**: Ensure all text uses `t()` function and keys exist in all language files -- **GitHub API errors**: Verify you're using configured `githubClient` from `models/Base.ts` - -### Data and Content Issues - -- **Base64 content errors**: Use `atob(item.content)` to decode GitHub API responses -- **Missing content**: Check ContentModel configuration and repository access -- **Tree structure problems**: Use `treeFrom()` utility from web-utility - -### Development Environment Setup - -- Clear browser cache if components don't render properly -- Restart development server after major configuration changes -- Verify all translation files are updated when adding new keys - -## Deployment and CI/CD - -### Vercel Deployment - -- Project is configured for Vercel deployment -- Uses GitHub Actions for CI/CD pipeline -- PWA support enabled for offline functionality - -### Environment Variables - -- `NODE_ENV` - Environment detection -- `CI` - Continuous integration flag -- `GithubToken` - GitHub API authentication -- `API_Host` - Backend API host -- `LARK_API_HOST` - Lark API host - -## Contributing Guidelines - -### Code Review Process - -- **Follow exact code suggestions** from reviews when provided -- Use **minimal approach** - only include explicitly requested functionality -- **Don't add extra features** not specified in requirements -- **Address reviewer feedback completely** before requesting re-review - -### Pull Request Template - -```markdown -Checklist（清单）: - -- [ ] Labels -- [ ] Assignees -- [ ] Reviewers - -Closes #XXXXX -``` - -### Quality Gates - -- [ ] All tests pass -- [ ] Code follows project conventions -- [ ] No linting errors -- [ ] Build succeeds -- [ ] Translations are complete -- [ ] Responsive design verified -- [ ] API integrations working - -## Resources and Documentation - -### Internal Resources - -- **`.github/copilot-instructions.md`** - Detailed development guidelines -- **`README.md`** - Project overview and quick start -- **`package.json`** - Complete dependency list -- **Translation files** - All supported languages and keys - -### External Dependencies - -- [Next.js Documentation](https://nextjs.org/) -- [React Bootstrap Documentation](https://react-bootstrap.github.io/) -- [MobX Documentation](https://mobx.js.org/) -- [TypeScript Documentation](https://www.typescriptlang.org/) -- [PNPM Documentation](https://pnpm.io/) - -### Key Repository Links - -- [Upstream Project](https://github.com/idea2app/Lark-Next-Bootstrap-ts) -- [GitHub Actions CI/CD](https://github.com/Open-Source-Bazaar/Open-Source-Bazaar.github.io/actions) -- [Live Demo](https://bazaar.fcc-cd.dev/) - -## Contact and Support - -For project-specific questions, refer to the existing documentation and GitHub issues. For development guidance, follow the patterns and conventions established in the codebase and the detailed copilot instructions. \ No newline at end of file From c9c2230a2029517af2f21d12411ff8ba4189cb33 Mon Sep 17 00:00:00 2001 From: huqi Date: Mon, 8 Sep 2025 10:06:56 +0800 Subject: [PATCH 5/8] Apply suggestions from code review Co-authored-by: Steven Ding <1139274654@qq.com> --- pages/article/code-of-conduct.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/pages/article/code-of-conduct.mdx b/pages/article/code-of-conduct.mdx index 72eac09..2feb278 100644 --- a/pages/article/code-of-conduct.mdx +++ b/pages/article/code-of-conduct.mdx @@ -16,10 +16,10 @@ version: "1.0" ## 适用范围 本行为规范适用于开源市集的所有互动场景，包括但不限于： -- 微信、飞书群讨论 +- 微信、飞书群等线上群组讨论 - 线上线下会议 - 线上线下活动 -- GitHub 组织和仓库 +- GitHub 等代码托管平台的组织和仓库 - 其它官方社区渠道 **所有参与者（包括但不限于共创方、志愿者、观众）参与开源市集，即表示其同意遵守以下行为规范。** @@ -41,6 +41,7 @@ version: "1.0" - 建设性的意见交流 - 礼貌的辩论和讨论 - 对不同观点的尊重和理解 +- 就事论事，不进行人身攻击 ### 4. 隐私保护 尊重隐私。未获明确授权，不得擅自发布他人的资料，如地址、电子邮箱、手机等隐私信息。我们承诺： From 49c786665348295c86b60737e969b504bb409e64 Mon Sep 17 00:00:00 2001 From: huqi Date: Mon, 8 Sep 2025 10:54:39 +0800 Subject: [PATCH 6/8] Apply suggestions from code review Co-authored-by: miyaliu666 --- pages/article/code-of-conduct.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/article/code-of-conduct.mdx b/pages/article/code-of-conduct.mdx index 2feb278..3b0b76d 100644 --- a/pages/article/code-of-conduct.mdx +++ b/pages/article/code-of-conduct.mdx @@ -46,7 +46,7 @@ version: "1.0" ### 4. 隐私保护 尊重隐私。未获明确授权，不得擅自发布他人的资料，如地址、电子邮箱、手机等隐私信息。我们承诺： - 保护参与者的个人信息 -- 不未经允许分享私人联系方式 +- 在未经参与者允许的情况下，不分享参与者的私人联系方式 - 尊重个人边界和隐私权 ### 5. 内容质量 From e236e8a64a5471b970695bc2ac64f7574d484ed7 Mon Sep 17 00:00:00 2001 From: South Drifter Date: Mon, 8 Sep 2025 19:13:54 +0800 Subject: [PATCH 7/8] Update pages/article/code-of-conduct.mdx --- pages/article/code-of-conduct.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/article/code-of-conduct.mdx b/pages/article/code-of-conduct.mdx index 3b0b76d..b70b013 100644 --- a/pages/article/code-of-conduct.mdx +++ b/pages/article/code-of-conduct.mdx @@ -1,6 +1,6 @@ --- title: "行为规范" -last_updated: "2025年9月" +date: 2025-09-08 version: "1.0" --- From f55c8a31c6811d7b0074a312e26d75a37b84cac2 Mon Sep 17 00:00:00 2001 From: huqi Date: Mon, 8 Sep 2025 22:53:05 +0800 Subject: [PATCH 8/8] Apply suggestions from code review Co-authored-by: Steven Ding <1139274654@qq.com> --- pages/article/code-of-conduct.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/article/code-of-conduct.mdx b/pages/article/code-of-conduct.mdx index b70b013..d10a8f2 100644 --- a/pages/article/code-of-conduct.mdx +++ b/pages/article/code-of-conduct.mdx @@ -6,7 +6,7 @@ version: "1.0" # 行为规范 -> - **最后更新**：2025年9月 +> - **最后更新**：2025 年 9 月 > - **版本**：1.0 ## 引言