Repo naming conventions: Tier 1 Guideline
@Honyii 已经在做这个了。
开始于 2026年10月29日。
评估
这个 Issue 还没有评估数据。
描述
This issue is to establish a consistent, descriptive, and maintainable repo naming guideline for higher tiers and the convention should make repo easier to understand and discover while maintaining the project's identity.
Here are general/default rules we can adapt
- Lowercase by default.
- Use lowercase numbers and letters, separated by hyphens. For instance, imagine a project called OpenMBEE Model Manager with three repositories:
| Component | Consistent naming | Inconsistent naming |
|---|---|---|
| Web application | model-manager-web | ModelManager_Web |
| API | model-manager-api | ModelManagerAPI |
| Documentation | model-manager-docs | Model_Manager_Docs |
- Descriptive.
- The name should communicate the project's purpose, product, or component. For instance, imagine a project providing tools for validating SysML models:
| Component | Descriptive naming | Vague naming |
|---|---|---|
| Model validator | sysml-model-validator | project-tool |
| Model examples | sysml-model-examples | examples2 |
| Validation rules | sysml-validation-rules | misc |
- Prefix only when useful.
- Use an established product or architecture prefix where it adds meaningful context. For instance, imagine a product called Flexo MMS with components that belong to that product and a shared utility used across several products:
| Component | Appropriate prefix | Unnecessary or unclear prefix |
|---|---|---|
| Layer 1 service | flexo-mms-layer1-service | openmbee-flexo-mms-layer1-service |
| SysML v2 integration | flexo-mms-sysmlv2 | sysmlv2-integration |
| Shared logging utility | logging-utils | flexo-mms-logging-utils |
The shared utility doesn't need the Flexo MMS prefix if it serves the wider ecosystem rather than that specific product.
- No unnecessary abbreviations.
- Use established domain abbreviations such as SysML, API, and MMS, but avoid obscure shorthand.
| Component | Clear naming | Unclear naming |
|---|---|---|
| Model validator | sysml-model-validator | smv |
| API documentation | model-api-docs | mad |
| Model examples | sysml-model-examples | sme-repo |
The aim isn't to eliminate all abbreviations but to use terms that contributors in the ecosystem will understand.
- Avoid temporary labels.
- Don't use names like new, final, latest, test2, or v2 unless that label is genuinely part of the project's identity.
| Purpose | Appropriate naming | Temporary or confusing naming |
|---|---|---|
| Main integration | sysmlv2-integration | sysmlv2-new |
| Replacement implementation | sysmlv2-integration | sysmlv2-final |
| Automated test suite | sysmlv2-integration-tests | sysmlv2-test2 |
- One naming pattern per component family.
- Related repositories should use consistent ordering of product, component, and role. For instance, imagine a project called Flexo MMS with three components:
| Component | Consistent naming | Inconsistentnaming |
|---|---|---|
| Layer 1 service | flexo-mms-layer1-service | flexo-mms-layer1-service |
| SysML v2 integration | flexo-mms-sysmlv2 | sysmlv2-flexo-integration |
- Preserve established names.
- Existing names can remain where they are recognized, externally referenced, or required by a platform.
- Document exceptions.
- A maintainer or designated repository owner should explain and approve deviations for new Tier 1 repositories.
Action Items for all
- Review the proposed naming rules and examples.
- Discuss whether the proposed repository tiers and their criteria make sense.
- Suggest changes, edge cases, and exceptions based on existing projects and workflows.
- Agree on the default naming format and who approves exceptions.
Action item for me; @Honyii
- [ ] Incorporate feedback and update the policy and examples.
- 主要语言
- HTML
- 星标
- 2
- 派生
- 0
- 平均合并
- 15 小时 17 分钟
- 30 天内合并 PR
- 5
环境准备
这个项目没有提供开发容器、Dockerfile 或贡献指南,环境需要你自己搭建:先看它的 README,通用步骤见我们的新手贡献指南。
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
Open-MBEE/opensysml.github.io 的其他 Issue
-
难度 3/5 1-2 天 新手友好度 68/100
Open-MBEE/opensysml.github.io#20 · 1 条评论 ·
-
难度 3/5 半天 新手友好度 35/100
-
Slack: Create a welcoming onboarding and introducing new channels可能已有人在做 @Honyii 于 18 天前认领。 未关闭
难度 4/5 3-5 天 新手友好度 44/100
Open-MBEE/opensysml.github.io#14 · 2 条评论 · 2 个 reaction · 已指派 1 人 ·