Repo naming conventions: Tier 1 Guideline

未关闭
#17 0 条评论 0 个 reaction 已指派 1 人 在 GitHub 查看

@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,通用步骤见我们的新手贡献指南。

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

Open-MBEE/opensysml.github.io 的其他 Issue

查看 Open-MBEE/opensysml.github.io 的全部 Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。