releaseup

一种从两个git标签之间的注释和docstrings中提取生成版本说明的NLP方法。

releaseup使用git diff提取所有注释和docstrings，然后对输出进行预处理，最后使用sklearn的TfidfVectorizer和spacy生成版本说明！生成的版本说明绝对不是抽象的，这是releaseup未来希望实现的目标。

目前，releaseup是一个假期项目（仅用了2天时间完成），但我确实打算在未来维护它。releaseup确实可以工作，但前提是你的注释写得很好。

通过其文档了解更多关于releaseup的信息。

结构

• 所有提取和预处理工作都使用extract模块完成。
• 所有提取的NLP工作都在nlp_backend模块内完成。
• releaseup还提供了一个高级API，位于high_level模块中。

请参阅示例获取更多信息。

安装

使用 pip 魔法

releaseup 使用现代 Python 打包方式，可以通过 pip 安装 ——

python -m pip install releaseup

对于开发者安装，请参阅我们的贡献指南。

示例

高级 API

import releaseup

tag = ["v0.8.0", "v0.9.0"]  # can also be commits
path = "././mypackage/"  # to ignore changes made to other folders (./github/, docs/, etc) and files
comments_filename = "COMMENTS.txt"

# extract added comments and docstrings
comments = releaseup.extract_release_comments(tags, path, comments_filename)

release_filename = "RELEASE_NOTES.txt"

# generate release notes
notes = releaseup.generate_release_notes(
    comments,
    release_filename,
    model_name="en_core_web_trf",  # any spacy model
    threshold=0.3,  # percentage of comments to be selected
)

低级 API

from releaseup.extract import (
    extract_additions,
    get_comments_and_docstrings,
    get_diff,
    preprocess_additions,
)
from releaseup.nlp_backend import get_release_notes, get_tfid_scores

tag = ["v0.8.0", "v0.9.0"]  # can also be commits
path = "././mypackage/"  # to ignore changes made to other folders (./github/, docs/, etc) and files
comments_filename = "COMMENTS.txt"

# extract added comments and docstrings
get_diff(tags, path, comments_filename)
extracted_additions = extract_additions(comments_filename)
preprocessed_additions = preprocess_additions(extracted_additions)
comments = get_comments_and_docstrings(preprocessed_additions)

release_filename = "RELEASE_NOTES.txt"

word_score = get_tfid_scores(comments)
release_notes = get_release_notes(
    comments,
    word_score,
    release_filename,
    model_name="en_core_web_trf",  # any spacy model
    threshold=0.3,  # percentage of comments to be selected
)

测试

TODO：添加测试

激活 pre-commit

releaseup 使用一组 pre-commit 钩子和 pre-commit 机器人来格式化、类型检查和美化代码库。这些钩子可以通过以下方式本地安装 ——

pre-commit install

这将在创建本地提交时运行检查。检查将仅针对该提交修改的文件运行，但可以使用以下命令触发所有文件的检查 ——

pre-commit run --all-files

如果您想跳过失败的检查并推送代码以进行进一步讨论，请使用 git commit 的 --no-verify 选项。

记录 releaseup

releaseup 的文档主要采用 docstrings 和 Markdown 的形式。docstrings 包含类或函数的描述、参数、示例、返回值和属性，而 .md 文件使我们能够在 releaseup 的文档网站上渲染这些文档。

releaseup 主要使用 MkDocs 和 mkdocstrings 在其网站上渲染文档。MkDocs 的配置文件（mkdocs.yml）可以在这里找到。文档部署在 https://readthedocs.io 这里。

理想情况下，随着每个新功能添加到 releaseup 中，应使用注释、docstrings 和 .md 文件添加文档。

本地构建文档

文档位于主存储库的 docs 文件夹中。可以使用以下方式使用 releaseup 的 docs 依赖项生成此文档 ——

mkdocs serve

上面执行的命令将清理任何现有的文档构建，创建一个新的构建（在 ./site/ 中），并在您的 localhost 上提供服务。要仅构建文档，请使用 ——

mkdocs build

Nox

开始开发最快的方式是使用 nox。如果您没有 nox，可以使用 pipx run nox 来运行它而无需安装，或者使用 pipx install nox。如果您没有 pipx（应用程序的 pip），则可以使用 pip install pipx 安装（这是唯一一个使用常规 pip 安装应用程序是合理的情况）。如果您使用 macOS，则 pipx 和 nox 都在 brew 中，使用 brew install pipx nox。

要使用，请运行 nox。这将使用系统上安装的每个 Python 版本进行 lint 和测试，跳过未安装的版本。您也可以运行特定的任务

$ nox -s lint  # Lint only
$ nox -s tests-3.9  # Python 3.9 tests only
$ nox -s docs -- serve  # Build and serve the docs
$ nox -s build  # Make an SDist and wheel

默认会话（lint 和 tests）可以使用以下命令执行 ——

nox

持续集成

releaseup 使用 GitHub Actions 作为 CI 提供商来运行测试、构建文档、在 PyPI 上发布、测试软件包等。所有 GitHub Actions 的配置都写成 YAML，位于 .github/ 目录中。CI 在每次向 main 分支提交拉取请求或推送时运行。

持续部署

releaseup 使用 Read The Docs 作为 CD 提供商来部署文档。所有 Read The Docs 的配置都写成 YAML，位于 .readthedocs.yml 文件中。CD 在每次向 main 分支推送时运行。

致谢

标志图像致谢：Taufik Ramadhan（从 canva 获取）