Getting Started with Open Source Collaboration

[Openspace-ea]

Getting Started with Open Source Collaboration

A hands-on course for your first community contribution. Estimated time: ~2 hours. Prerequisites: a computer with Git installed, a GitHub account, and no prior open-source experience required.

---

本材料中文版见文末「开源协作入门（中文版）」。

---

Course Outline

Module	Topic	Time
1	Open source basics: licenses, roles and workflow	15 min
2	Git essentials: the five commands you will use every day	30 min
3	Issues: how to ask, report and claim work	20 min
4	The Fork → Branch → PR workflow	35 min
5	Practice: your first contribution, end to end	20 min

---

Module 1 · Open Source Basics

Open source means the source code is public and licensed so that anyone may use, study, modify and redistribute it. For OSEA projects the software default license is Apache-2.0, which permits commercial use while requiring attribution and preserving the license notice.

Who is who:

• Maintainer — reviews and merges contributions, owns releases and roadmap.
• Contributor — anyone who submits an issue, a document fix, or code. That includes you.
• Community — everyone who discusses, answers questions and shares results.

The workflow you will learn is the same one used by nearly every project hosted on GitHub:

Issue (find or create)  →  Fork  →  Branch  →  Commit  →  Push  →  Pull Request  →  Review  →  Merge

Module 2 · Git Essentials

2.1 Install and configure

Install Git from [git-scm.com](https://git-scm.com/downloads), then set your identity once:

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

2.2 The five commands you will use daily

git clone <repo-url>      # copy a repository to your machine
git status                # see what changed
git add <file>            # stage changes (git add . for everything)
git commit -m "message"   # record a snapshot with a message
git push                  # upload your commits to the remote

2.3 Branches

A branch is an isolated line of work. Never commit directly to main:

git checkout -b fix/issue-123   # create and switch to a new branch
git switch main                 # go back to main
git branch                      # list branches

2.4 Keeping your fork up to date

git remote add upstream <original-repo-url>
git fetch upstream
git switch main
git merge upstream/main

2.5 Commit messages

Use [Conventional Commits](https://www.conventionalcommits.org/) — one logical change per commit:

feat: add orbital visibility report
fix: correct TLE parsing for low-inclination orbits
docs: clarify token application steps
chore: bump dependencies

A good message completes the sentence: "If applied, this commit will …"

Module 3 · Issues

3.1 Finding work

Browse the open issues of the organization: [github.com/issues?q=is:issue is:open user:Openspace-ea](https://github.com/issues?q=is%3Aissue+is%3Aopen+user%3AOpenspace-ea).

Look for labels such as good first issue or help wanted — they are explicitly left for newcomers. Comment on the issue to say you are working on it, so nobody duplicates the effort.

3.2 Reporting a good issue

• Search first — avoid duplicates.
• Title — specific and searchable: Satellite Watcher: map fails to render at zoom level 3.
• Reproduce — numbered steps, exact commands, expected vs. actual result.
• Environment — OS, runtime / browser version, commit hash.
• Evidence — logs, screenshots, stack traces.

3.3 Asking a question well

State what you are trying to achieve, what you already tried, and the exact error. A question with a minimal reproduction usually gets an answer within hours.

Module 4 · The Fork → Branch → PR Workflow

Step 1 · Fork

Click Fork on the repository page. This creates your own copy.

Step 2 · Clone your fork

git clone https://github.com/<your-username>/<repo>.git
cd <repo>

Step 3 · Create a branch

git checkout -b fix/issue-123

Step 4 · Make the change and verify it

Edit the files, then run the project's tests or lint command described in its README.

Step 5 · Commit and push

git add .
git commit -m "fix: resolve map rendering at low zoom"
git push -u origin fix/issue-123

Step 6 · Open the Pull Request

In the GitHub UI (a link appears after pushing):

• Base repository: the original project. Head: your branch.
• Title in Conventional Commit style.
• Description: what changed, why, and how you tested it. Link the issue with Closes #123.
• Keep it focused — one purpose per PR.

Step 7 · Review, revise, merge

A maintainer reviews your PR and may request changes. Address the feedback by pushing additional commits to the same branch — the PR updates automatically. Once approved and green, it is merged and you are a contributor.

Etiquette

• Be patient; reviewers are volunteers.
• Do not open a PR for someone else's issue without asking.
• Never commit secrets, tokens or large binaries.

Module 5 · Practice: Your First Contribution

Complete this once and the workflow becomes muscle memory.

1. Pick a good first issue, or improve a typo in a README.
2. Fork and clone the repository.
3. Create a branch named docs/fix-typo.
4. Edit the file, then run git status and git diff to review your change.
5. Commit using docs: fix typo in README.
6. Push and open a Pull Request linking the issue.
7. Respond to the reviewer's comment and get merged.

Checklist before you push

• Branch name describes the change.
• Commit message follows the convention.
• Only intended files are changed (git status is clean of surprises).
• No secrets, keys or credentials are included.
• Tests / lint pass locally.

Where to Go Next

• Community discussion and Q&A: [GitHub Discussions](https://github.com/Openspace-ea/community/discussions)
• How to participate in OSEA projects: [Contributing Guide](./CONTRIBUTING.md)
• Community behaviour expectations: [Code of Conduct](./CODE_OF_CONDUCT.md)

---

开源协作入门（中文版）

面向第一次参与社区贡献的实操课程。预计用时 约 2 小时。
前置条件：已安装 Git 的电脑、一个 GitHub 账号，无需任何开源经验。

课程大纲

模块	主题	时长
1	开源基础：许可证、角色与协作流程	15 分钟
2	Git 基础：每天都会用到的五个命令	30 分钟
3	Issue：如何提问、反馈与认领任务	20 分钟
4	Fork → 分支 → PR 全流程	35 分钟
5	实战：完整走通你的第一次贡献	20 分钟

---

模块 1 · 开源基础

开源意味着源代码公开，并通过许可证允许任何人使用、研究、修改与再分发。OSEA 项目软件默认采用 Apache-2.0 许可证：允许商业使用，但要求署名并保留许可证声明。

角色说明：

• 维护者（Maintainer） — 评审并合并贡献，负责版本发布与路线图。
• 贡献者（Contributor） — 提交 Issue、修正文档或代码的任何人，包括你。
• 社区（Community） — 参与讨论、解答问题、分享成果的所有人。

你将学到的流程，与 GitHub 上几乎所有项目使用的流程一致：

Issue（寻找或创建）→ Fork → 分支 → 提交 → 推送 → Pull Request → 评审 → 合并

模块 2 · Git 基础

2.1 安装与配置

从 [git-scm.com](https://git-scm.com/downloads) 安装 Git，然后一次性设置身份信息：

git config --global user.name "你的名字"
git config --global user.email "you@example.com"

2.2 每天都会用到的五个命令

git clone <仓库地址>       # 把仓库复制到本地
git status                # 查看当前改动
git add <文件>            # 暂存改动（git add . 暂存全部）
git commit -m "提交信息"   # 生成一次带说明的快照
git push                  # 把本地提交推送到远端

2.3 分支

分支是一条独立的工作线。永远不要直接在 main 上提交：

git checkout -b fix/issue-123   # 创建并切换到新分支
git switch main                 # 回到 main 分支
git branch                      # 列出所有分支

2.4 保持你的 Fork 与上游同步

git remote add upstream <原仓库地址>
git fetch upstream
git switch main
git merge upstream/main

2.5 提交信息规范

推荐使用 [Conventional Commits](https://www.conventionalcommits.org/)，一次提交只做一件事：

feat: 新增轨道可见性报告
fix: 修复低倾角轨道的 TLE 解析
docs: 澄清 Token 申请步骤
chore: 升级依赖版本

好的提交信息应能补全这句话：“本次提交将会……”。

模块 3 · Issue

3.1 寻找可参与的任务

浏览组织下的开放 Issue：[github.com/issues?q=is:issue is:open user:Openspace-ea](https://github.com/issues?q=is%3Aissue+is%3Aopen+user%3AOpenspace-ea)。

优先关注 good first issue、help wanted 等标签——它们正是留给新人的入口。选定后请在 Issue 下留言说明你正在处理，避免多人重复劳动。

3.2 如何提交一个好的 Issue

• 先搜索 — 避免重复提交。
• 标题 — 具体且可被检索，例如：Satellite Watcher：缩放级别 3 时地图无法渲染。
• 复现步骤 — 编号列出步骤与命令，说明预期结果与实际结果。
• 环境信息 — 操作系统、运行时 / 浏览器版本、提交哈希。
• 证据 — 日志、截图、堆栈信息。

3.3 如何提出一个好问题

说明你想达成什么、已经尝试过什么、报错信息是什么。附带最小可复现示例的提问，通常几小时内就会得到回应。

模块 4 · Fork → 分支 → PR 全流程

第 1 步 · Fork

在仓库页面点击 Fork，这会创建一份属于你的副本。

第 2 步 · 克隆你的 Fork

git clone https://github.com/<你的用户名>/<仓库名>.git
cd <仓库名>

第 3 步 · 创建分支

git checkout -b fix/issue-123

第 4 步 · 修改并自测

编辑文件，然后运行该仓库 README 中说明的测试或检查命令。

第 5 步 · 提交并推送

git add .
git commit -m "fix: 修复低缩放级别下的地图渲染"
git push -u origin fix/issue-123

第 6 步 · 发起 Pull Request

在 GitHub 界面中（推送后会提示创建入口）：

• 目标仓库为原项目，来源分支为你的分支。
• 标题遵循 Conventional Commits 风格。
• 描述说明改了什么、为什么改、如何测试；用 Closes #123 关联 Issue。
• 保持聚焦——一个 PR 只解决一件事。

第 7 步 · 评审、修改、合并

维护者会评审你的 PR，可能提出修改意见。你只需在同一分支继续提交，PR 会自动更新。通过评审与 CI 后即被合并，你也就成为了项目贡献者。

协作礼仪

• 保持耐心，评审者是志愿者。
• 未事先沟通，不要直接替他人提交 Issue 对应的 PR。
• 切勿提交密钥、Token 或大型二进制文件。

模块 5 · 实战：你的第一次贡献

完整走一遍，流程就会变成本能。

1. 挑选一个 good first issue，或修正 README 中的一处笔误。
2. Fork 并克隆该仓库。
3. 创建分支，命名为 docs/fix-typo。
4. 修改文件，用 git status 与 git diff 检查改动。
5. 使用 docs: 修正 README 笔误 提交。
6. 推送并发起 Pull Request，关联对应 Issue。
7. 回应评审意见，最终完成合并。

推送前自查清单

• 分支名能说明改动内容。
• 提交信息符合规范。
• 只改动了预期文件（git status 无意外变更）。
• 未包含密钥、Token 或凭证。
• 本地测试 / 检查已通过。

延伸阅读

• 社区讨论与问答：[GitHub Discussions](https://github.com/Openspace-ea/community/discussions)
• 参与 OSEA 项目的方式：[贡献指南](./CONTRIBUTING.md)
• 社区行为规范：[行为准则](./CODE_OF_CONDUCT.md)