Semantic Git Branching Code Recipe (CN)

示例代码的背景信息请参考 Semantic Git Branching (CN)

How to Define My Own Semantic Branching Rules

之前我们介绍了, 我们可以为自己项目定义一套 Semantic Branching Rule 的规则. 例如 feature/..., feat/... 对应 Feature Branch. aws_ops_alpha.vendor.semantic_branch.SemanticBranchRule 工具可以让你轻松定义自己的规则, 并且能检测某个 Git branch name 对应着哪个 Semantic branch, 并能判断某个 Git branch name 是不是对应着指定的 Semantic branch. 示例代码如下.

from aws_ops_alpha.api import SemanticBranchRule

# key is semantic branch name, value is prefix keywords
semantic_branch_rules = {
    "main": ["main", "master"],
    "feature": ["feature", "feat"],
    "fix": ["fix"],
    "doc": ["doc"],
    "app": ["app"],
    "release": ["release", "rls"],
    "cleanup": ["cleanup", "clean"],
}

semantic_branch_rule = SemanticBranchRule(
    rules=semantic_branch_rules,
)

semantic_branch_rule.is_certain_semantic_branch(git_branch_name="feat/f1", semantic_name="feature")

True

semantic_branch_rule.is_certain_semantic_branch(git_branch_name="release/2000-01-01", semantic_name="feature")

False

semantic_branch_rule.parse_semantic_name(git_branch_name="feat/f1")

'feature'

# This would raises an error
semantic_branch_rule.parse_semantic_name(git_branch_name="unknown/f1")

---------------------------------------------------------------------------
InvalidSemanticNameError                  Traceback (most recent call last)
Cell In[10], line 1
----> 1 semantic_branch_rule.parse_semantic_name(git_branch_name="unknown/f1")

File ~/Documents/GitHub/aws_ops_alpha-project/aws_ops_alpha/vendor/semantic_branch.py:409, in SemanticBranchRule.parse_semantic_name(self, git_branch_name)
    406         self._parse_semantic_name_cache[git_branch_name] = semantic_name
    407         return semantic_name
--> 409 raise InvalidSemanticNameError(
    410     f"branch {git_branch_name!r} doesn't match any semantic name in {list(self.rules)!r}"
    411 )

InvalidSemanticNameError: branch 'unknown/f1' doesn't match any semantic name in ['main', 'feature', 'fix', 'doc', 'app', 'release', 'cleanup']

Git Repo Helper

在 DevOps 中, 我们经常要通过运行一些 git CLI 命令来获得当前 Git 的一些信息, 例如当前的 Branch, 当前的 Commit ID. 在一些特定的 CI 系统中, 我们可能还会用到特殊的 Environment Variable 来获得这些信息. 例如在 GitHub Action 中, 我们 Git Branch 的信息储存在 GITHUB_REF_NAME 中. 结合前面介绍的 Semantic Branch 的概念, 我们还希望能获得当前的 Semantic Branch Name. aws_ops_alpha.git.impl.MultiGitRepo 或 aws_ops_alpha.git.impl.MonoGitRepo 封装了这些复杂的逻辑, 使得开发者可以轻松访问这些信息. 这种小工具本质上跟 Jenkins Plugin, GitHub Action Plugin, CircleCI Orb 插件没什么不同. 区别仅仅是 aws_ops_alpha 是基于 Python 的, 是 CI Agnostic 的, 可以轻松的迁徙到任何 CI 系统中. 而那些插件只能在特定平台上使用.

举例来说, 我们希望在任何名字类似于 feat, feature/description, feature-123/description 的 Git branch 都被视为 feature branch. 而在 feature branch 上我们的 CI 只负责对代码进行 unit test. 什么 artifacts 的构建, deployment 之类的一概不做. 而名字为 app/description 的 Git branch 被视为 app branch, 在 app branch 上我们除了进行 unit test, 还会部署 App, 以及进行 integration test.

在上面的例子中, feature 和 app 就是 semantic name, 也就是语义.

from aws_ops_alpha.api import MultiGitRepo, MonoGitRepo
# create git repo object
# this demo is based on MultiGitRepo,
# if you are using monorepo, pelease use MultiGitRepo, it assume that you use ``${project_name}/${semantic_branch_name}/${optional_description}

git_repo = MultiGitRepo(
    sem_branch_rule=semantic_branch_rule,
)

git_repo.git_branch_name

'main'

git_repo.git_commit_id

'fc6fb18325298000add56afba1ac7b2dae9717dc'

git_repo.git_commit_message

'c'

git_repo.print_git_info()

| Current git branch is 🔀 'main'
| Current git commit is # 'fc6fb18325298000add56afba1ac7b2dae9717dc'
| Current git commit message is 📜 'c'

git_repo.semantic_branch_part

'main'

git_repo.semantic_branch_name

'main'

git_repo.is_main_branch

True