在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

kamranahmedse/developer-roadmap

菜单

开发者指南

相关源文件

本指南为希望为roadmap.sh平台贡献或扩展其功能的开发者提供了重要信息。它概述了本地开发设置、架构、贡献工作流程以及向存储库添加新内容的最佳实践。

有关具体内容指南的信息，请参阅内容指南。

本地开发设置

要开始在roadmap.sh存储库上进行本地开发，请按照以下步骤操作

  1. 克隆仓库

  2. 添加编辑器包并安装依赖项

  3. 启动开发服务器

应用程序将在 http://:3000 上提供。

来源： contributing.md129-142 package.json6-9

项目架构

高层架构

来源： .github/workflows/deployment.yml astro.config.mjs

核心系统和组件

roadmap.sh平台由几个相互关联的系统组成

  1. 内容系统：管理路线图定义、指南和最佳实践
  2. UI层：使用Astro和React组件渲染内容
  3. 进度跟踪：跟踪用户学习进度
  4. 身份验证：处理用户身份验证和授权
  5. 构建与部署：处理内容并部署应用程序

来源： astro.config.mjs package.json33-87

内容和渲染系统

来源： scripts/editor-roadmap-content-json.ts src/components/RoadmapTitleQuestion.tsx

贡献工作流程

贡献类型

roadmap.sh项目接受各种类型的贡献

  1. 新路线图：特定技术或角色的完整学习路径
  2. 现有路线图的改进：添加或删除节点，修复错别字
  3. 内容添加：为路线图主题添加解释和资源
  4. 错误修复：解决平台中的问题

来源： contributing.md11-26 .github/ISSUE_TEMPLATE/01-suggest-changes.yml

贡献流程

对于新路线图

  1. 通过在issue中提供文本大纲提交路线图，或
  2. 使用路线图编辑器创建交互式路线图，并在issue中提交链接

对于现有路线图

  1. 修复错别字：直接修改路线图markdown文件并提交PR
  2. 添加或删除节点：提交一个包含你建议的issue

对于内容添加

  1. 在相关路线图内找到内容目录
  2. 遵循内容指南创建或编辑markdown文件
  3. 提交包含你更改的PR

来源： contributing.md12-26 contributing.md50-60 .github/ISSUE_TEMPLATE/01-suggest-changes.yml

构建和测试路线图

构建项目

构建过程包括以下几个步骤

  1. 生成路线图渲染器

  2. 压缩图像（可选）

  3. 构建应用程序

来源： scripts/generate-renderer.sh .github/workflows/deployment.yml32-43

构建和部署系统

来源： .github/workflows/deployment.yml scripts/generate-renderer.sh scripts/editor-roadmap-content-json.ts

添加新路线图

添加新路线图的两种主要方法是

方法一：提交文本路线图

  1. 创建路线图的详细文本大纲
  2. 将其作为issue提交到存储库
  3. 遵循贡献指南提供的格式。

方法二：使用路线图编辑器

  1. 使用路线图编辑器创建交互式路线图
  2. 在issue中提交你的路线图链接

对于这两种方法，路线图都将经过审查，如果批准，将集成到平台中。

来源： contributing.md12-18

向路线图添加内容

路线图主题的内容应按照特定指南进行Structuring

内容结构

每个主题应包括

  1. 一个清晰、简洁的标题
  2. 简要说明（通常是一个段落）
  3. 用于进一步学习的外部资源列表

示例格式

其中 @type@ 是以下之一

  • @official@
  • @opensource@
  • @article@
  • @course@
  • @podcast@
  • @video@

来源： contributing.md50-83 src/data/roadmaps/php/content/reading-files@S9wTlkbv9-R6dohhZ47hs.md scripts/editor-roadmap-content-json.ts99-107

内容文件位置

路线图主题的内容文件存储在相应路线图的content目录中

src/data/roadmaps/<roadmap-id>/content/<topic-slug>@<node-id>.md

例如

src/data/roadmaps/php/content/reading-files@S9wTlkbv9-R6dohhZ47hs.md

来源： src/data/roadmaps/php/content/reading-files@S9wTlkbv9-R6dohhZ47hs.md scripts/editor-roadmap-content-json.ts99-107

脚本和实用工具

该存储库包含一些用于开发和维护的实用脚本

脚本描述
npm run dev启动开发服务器
npm run build为生产构建应用程序
npm run generate-renderer生成路线图渲染器
npm run roadmap-content处理路线图内容
npm run compress:images压缩图像
npm run generate:roadmap-content-json从路线图内容生成JSON文件

来源： package.json6-31

自动化工作流

该存储库使用GitHub Actions来自动化多个进程

部署工作流

部署工作流是手动触发的，并执行以下步骤

  1. 检出仓库
  2. 设置Node.js和pnpm
  3. 准备配置文件
  4. 安装依赖项
  5. 生成生产版本
  6. 将应用程序部署到EC2实例
  7. 清除CloudFront缓存

来源： .github/workflows/deployment.yml

依赖升级工作流

此工作流每周运行一次以升级依赖项

  1. 检出仓库
  2. 设置Node.js和pnpm
  3. 安装和升级依赖项
  4. 创建包含更新依赖项的PR

来源： .github/workflows/upgrade-dependencies.yml

内容刷新工作流

此工作流每天运行以刷新路线图内容JSON

  1. 检出仓库
  2. 设置pnpm和Node.js
  3. 生成更新的内容JSON文件
  4. 创建包含更新内容的PR

来源： .github/workflows/refresh-roadmap-content-json.yml

贡献最佳实践

在贡献 roadmap.sh 时，请遵循以下最佳实践

  1. 注重质量：只添加最相关和最有价值的内容
  2. 亲自评估资源：只推荐您使用过且认为有价值的资源
  3. 避免自我推广：不要仅为自我推广而提交 PR
  4. 使用有意义的提交消息：编写描述性的提交消息
  5. 检查现有问题/PR：在创建新的问题/PR 之前，先检查该问题是否已存在

来源： contributing.md85-108

许可注意事项

roadmap.sh 的内容受版权保护。在贡献时，请注意这些许可条款

  1. 内容仅可用于个人用途
  2. 以任何形式重新发布内容需要事先同意
  3. 许可不适用于为贡献目的而创建的 GitHub fork

为了使用灵活性，请联系项目维护者并详细说明您的预期用途。

来源： license

GitHub 仓库设置

roadmap.sh 仓库通过一些 GitHub 功能进行管理

  1. 问题模板：用于建议更改和报告错误的标准化模板
  2. 资金：该项目通过 GitHub Sponsors 获得资助
  3. 自动化标签：根据内容自动为问题添加标签
  4. 行为准则：本项目遵循贡献者公约行为准则

来源： .github/FUNDING.yml .github/workflows/label-issue.yml code_of_conduct.md

通过遵循此开发者指南，您应该能够设置您的本地开发环境，理解项目架构，并有效地为 roadmap.sh 平台做出贡献。