docs-starter-kit

文档入门套件

为任何项目生成完整、专业的文档。

核心工作流

1. 确定项目类型：开源公共项目、内部项目、库、应用程序
2. 选择模板：根据项目类型选择合适的文档
3. 自定义内容：填写项目专属信息
4. 添加章节：纳入与项目相关的章节
5. 检查完整性：确保包含所有必需文档
6. 统一格式：采用一致的风格和结构

必备文档文件

README.md（必需）

项目概述和入门指南

• 项目描述和用途
• 功能和能力
• 快速入门指南
• 安装说明
• 使用示例
• 配置选项
• 贡献指南链接
• 许可证信息

CONTRIBUTING.md（推荐）

贡献者指南

• 如何贡献
• 开发环境设置
• 代码风格指南
• 测试要求
• 拉取请求流程
• 行为准则链接

LICENSE（开源项目必需）

项目许可证

• MIT、Apache 2.0、GPL、BSD 等
• 版权持有人和年份

CODE_OF_CONDUCT.md（开源项目最佳实践）

社区准则

• 预期行为
• 不可接受的行为
• 执行程序
• 联系信息

SECURITY.md（推荐）

安全策略和漏洞报告

• 支持的版本
• 漏洞报告方式
• 响应时间
• 安全更新流程

CHANGELOG.md（推荐）

版本历史

• 每个版本的重要变更
• 突出显示破坏性变更
• 发布日期
• 遵循 Keep a Changelog 格式

README.md 模板

# Project Name

Brief description of what this project does and who it's for.

## Features

- ✨ Feature 1
- 🚀 Feature 2
- 🎯 Feature 3

## Quick Start

```bash
# Clone the repository
git clone https://github.com/username/project-name.git

# Install dependencies
npm install

# Run development server
npm run dev
```

安装

先决条件

• Node.js 20+
• npm 或 pnpm
• PostgreSQL 15+（如适用）

设置

1. 克隆并安装：

   git clone <repo>
   npm install
   

2. 配置环境：

   cp .env.example .env
   # Edit .env with your values
   

3. 设置数据库（如适用）：

   npm run db:migrate
   npm run db:seed
   

4. 启动开发环境：

   npm run dev
   

使用方法

基本示例

import { something } from "project-name";

const result = something();

高级用法

[更多详细示例]

配置

可用的环境变量：

变量	描述	默认值
API_KEY	API 身份验证密钥	-
PORT	服务端口	3000
DATABASE_URL	数据库连接	-

文档

• API 参考
• 架构
• 贡献指南

测试

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test file
npm test path/to/test

部署

[部署说明]

构建技术

• Next.js - React 框架
• Prisma - 数据库 ORM
• Tailwind CSS - 样式

贡献

欢迎贡献！请阅读 CONTRIBUTING.md，了解我们的行为准则以及提交拉取请求的流程。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

作者

• Your Name - 初始工作 - YourGitHub

致谢

• 感谢所有曾使用其代码的人
• 灵感来源
• 参考资料

## CONTRIBUTING.md Template

```markdown
# Contributing to [Project Name]

Thank you for your interest in contributing! This document provides guidelines for contributing to this project.

## Code of Conduct

This project adheres to a [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.

## How Can I Contribute?

### Reporting Bugs

Before creating bug reports, please check existing issues to avoid duplicates. When creating a bug report, include:

- Clear and descriptive title
- Detailed description of the issue
- Steps to reproduce
- Expected vs actual behavior
- Environment details (OS, Node version, etc.)
- Screenshots if applicable

### Suggesting Enhancements

Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, include:

- Clear and descriptive title
- Detailed description of the proposed feature
- Explanation of why this enhancement would be useful
- Possible implementation approach

### Pull Requests

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (`npm test`)
6. Commit using conventional commits (`git commit -m 'feat: add amazing feature'`)
7. Push to your fork (`git push origin feature/amazing-feature`)
8. Open a Pull Request

## Development Setup

See [README.md](README.md) for initial setup instructions.

### Development Workflow

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Run tests in watch mode
npm run test:watch

# Run linter
npm run lint

# Format code
npm run format

代码风格

• 遵循现有代码风格
• 所有新代码均使用 TypeScript
• 提交前运行 npm run lint 和 npm run format
• 按照 Conventional Commits 规范编写有意义的提交信息

提交信息格式

<type>(<scope>): <description>

[optional body]

[optional footer]

类型：feat、fix、docs、style、refactor、test、chore

测试

• 为所有新功能编写测试
• 将测试覆盖率保持在 80% 以上
• 提交 PR 前运行测试
• 适当时同时包含单元测试和集成测试

文档

• 添加功能时更新 README.md
• 记录新的环境变量
• 为公共 API 添加 JSDoc 注释
• 对重要变更更新 CHANGELOG.md

审查流程

1. 自动检查必须通过（测试、代码检查、构建）
2. 至少需要一位维护者批准
3. 解决所有审查意见
4. 获得批准后由维护者合并

有疑问？

欢迎提交 issue 提出问题，或联系 [email protected]。

许可证

参与贡献即表示你同意，你的贡献将采用与项目相同的许可证进行许可。

## SECURITY.md Template

```markdown
# Security Policy

## Supported Versions

| Version | Supported          |
| ------- | ------------------ |
| 2.x.x   | :white_check_mark: |
| 1.x.x   | :x:                |

## Reporting a Vulnerability

We take security seriously. If you discover a security vulnerability, please follow these steps:

### Do Not

- Open a public GitHub issue
- Disclose the vulnerability publicly before we've addressed it

### Do

1. **Email us** at [email protected]
2. **Include details:**
   - Description of the vulnerability
   - Steps to reproduce
   - Potential impact
   - Suggested fix (if any)

### What to Expect

- **Acknowledgment:** Within 48 hours
- **Initial assessment:** Within 1 week
- **Regular updates:** Every 2 weeks
- **Resolution:** Depends on severity and complexity

### Disclosure Policy

- We will investigate and respond promptly
- We will work with you to understand the issue
- We will keep you informed of our progress
- We will credit you for the discovery (unless you prefer to remain anonymous)

### Security Update Process

1. Patch is developed and tested
2. Security advisory is prepared
3. New version is released
4. Advisory is published
5. Users are notified

## Best Practices

When using this project:

- Keep dependencies up to date
- Use environment variables for secrets
- Enable security features in production
- Follow principle of least privilege
- Regularly review access logs

## Known Security Considerations

[Document any known security considerations or limitations]

## Security-Related Configuration

[Document security-related configuration options]

CODE_OF_CONDUCT.md 模板

# Code of Conduct

## Our Pledge

We pledge to make participation in our project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

## Our Standards

### Positive Behavior

- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
- Gracefully accepting constructive criticism
- Focusing on what is best for the community
- Showing empathy towards other community members

### Unacceptable Behavior

- Trolling, insulting/derogatory comments, and personal attacks
- Public or private harassment
- Publishing others' private information without permission
- Other conduct which could reasonably be considered inappropriate

## Our Responsibilities

Project maintainers are responsible for clarifying standards of acceptable behavior and will take appropriate and fair corrective action in response to unacceptable behavior.

## Scope

This Code of Conduct applies within all project spaces and when representing the project or its community.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project team at [[email protected]]. All complaints will be reviewed and investigated promptly and fairly.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.0.

LICENSE 模板

MIT License

MIT License

Copyright (c) [year] [fullname]

Permission is hereby granted, free of charge, to any person obtaining a copy...

Apache 2.0

Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/

CHANGELOG.md 模板

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- New feature X

### Changed

- Updated dependency Y

### Fixed

- Bug Z

## [1.0.0] - 2024-01-15

### Added

- Initial release
- Feature A
- Feature B

### Security

- Fixed vulnerability in dependency

[unreleased]: https://github.com/user/project/compare/v1.0.0...HEAD
[1.0.0]: https://github.com/user/project/releases/tag/v1.0.0

补充文档

API.md

API 参考文档

ARCHITECTURE.md

系统设计与架构

DEPLOYMENT.md

部署说明

DEVELOPMENT.md

开发环境设置

FAQ.md

常见问题

TROUBLESHOOTING.md

常见问题与解决方案

文档最佳实践

1. 保持更新：每次发布时检查文档
2. 简明扼要：清晰直截了当
3. 使用示例：展示而非仅仅讲述
4. 关联相关文档：适当添加交叉引用
5. 考虑受众：根据用户的水平撰写
6. 保持格式一致：遵循风格指南
7. 加入视觉内容：图表、截图、示例

项目类型差异

库/软件包

重点关注：API 参考、使用示例、安装

应用程序

重点关注：设置、配置、部署

CLI 工具

重点关注：命令、选项、示例

内部工具

重点关注：访问、身份验证、公司特定流程

检查清单

完整项目文档应包括：

• README.md，包含清晰的说明和快速入门
• CONTRIBUTING.md，包含开发指南
• LICENSE 文件（如为开源项目）
• CODE_OF_CONDUCT.md（如为开源项目）
• SECURITY.md，说明如何报告漏洞
• CHANGELOG.md，记录版本历史
• .github/ISSUE_TEMPLATE/，用于提交错误报告和功能请求
• .github/PULL_REQUEST_TEMPLATE.md
• docs/ 文件夹，用于存放补充文档
• API 参考（如为库）
• 架构文档（如项目较复杂）