towncrier - 清水川のScrapbox

towncrier

CHANGELOGの中身はKeep a Changelogに従うとよさそう。

towncrier is a utility to produce useful, summarised news files for your project. Rather than reading the Git history as some newer tools to produce it, or having one single file which developers all write to, towncrier reads “news fragments” which contain information useful to end users.

news fragmentsの拡張子と意味

.feature: Signifying a new feature.

.bugfix: Signifying a bug fix.

.doc: Signifying a documentation improvement.

.removal: Signifying a deprecation or removal of public API.

.misc: A ticket has been closed, but it is not of interest to users.

カスタムフラグメント

上記のデフォルトのみ使う場合は、 pyproject.toml に定義を書かなくて良い

pyproject.toml に1つでも定義すると、上記のデフォルトは使われないため再定義が必要

採用プロジェクト

pip

設定 https://github.com/pypa/pip/blob/master/pyproject.toml

断片 https://github.com/pypa/pip/tree/master/news

pipenv

設定 https://github.com/pypa/pipenv/blob/master/pyproject.toml

pytest

設定 https://github.com/pytest-dev/pytest/blob/master/pyproject.toml

shimizukawa.icon自分でも使ってみた

1. sshhのchangelog

2. お仕事コード

https://gyazo.com/708d4b951957326ac29e542dd1025451

towncrier を使うと上記ファイルとタグと現在日付から CHANGELOG.rst を自動生成

https://gyazo.com/93e7c9eafee69ff799d137788bf66b56

テンプレートファイル

code:_templates.rst

{% for section in sections %}{% set underline = "-" %}{% if section %}{{section}}

{{ underline * 2 * section|length }}{% set underline = "~" %}

{% endif %}{% if sectionssection %}{% for category, val in definitions.items() if category in sectionssection %}

{% if definitionscategory'showcontent' %}{% for text, values in sectionssectioncategory|dictsort(by='value') %}{% set issue_joiner = joiner(', ') %}- {% for value in values|sort %}{{ issue_joiner() }}{{ value }} <https://xxxx.planio.jp/issues/{{ value[1:] }}>_{% endfor %}: {{ text }}

{% endfor %}{% else %}- {{ sectionssectioncategory''|sort|join(', ') }}

{% endif %} {% if sectionssectioncategory|length == 0 %}

No significant changes.

{% else %} {% endif %} {% endfor %} {% else %}

No significant changes.

{% endif %} {% endfor %}

README.rst

code:README.rst

このディレクトリには、更新差分の断片を格納します。

内容は1行の文面で、reSTフォーマットで書いてください。

本番リリース時にその内容が、ファイル名で分類されて CHANGELOG.rst ファイルに統合されます。

CHANGELOGは本番にリリースした履歴として読まれます。

このプロジェクトはエンドユーザーが直接更新履歴を読むものではないですが、要件を依頼した人が見て分かる言葉・用語で書いてください。

いくつか書き方を紹介します。

1600.bugfix.rst::

本番エラー XXX確定時のXXXXファイル名競合

リリース実施前に SELECT COUNT(*) FROM proof GROUP BY file_data HAVING COUNT(*) > 1; が0件なことを確認すること

832.migration.rst::

XXXのためモデル変更とAPIに影響がないようにリポジトリ変更

リリース時には以下に注意してください。

1. 実装担当者が立ち会うこと

2. 念のため SELECT COUNT(*) FROM foobar WHERE ... が0件なことを確認する

チケット番号はファイル名から取得されて、リンク形式でCHANGELOG.rstに書かれるので、ファイル内には書かなくても大丈夫です。

ファイル名は、 <ISSUE>.<TYPE>.rst の形式で、上記例のように 1600.bugfix.rst のようなファイル名です。

<ISSUE> にはplanioのチケット番号、 <TYPE> には以下のいずれかを使って下さい。

* feature: 新機能、あるいは機能変更など

* migration: モデルやDBの変更と、それにともなうrepositoryコード変更

* bugfix: 既存機能のバグ修正

* doc: ドキュメントの更新

* deprecation: 機能を今後廃止するために、コードでDeprecationWarningを設定した場合

* removal: 機能を削除した場合

* vendor: 依存パッケージの種類やバージョンを変更する場合

* trivial: ちょっとした修正（タイポや、機能に影響を与えない内部の変更）

CHANGELOG.rst ファイルを生成するには以下の手順でコマンドを実行します::

$ git tag rel-20190325-prod-release # タグを付けた直後にtowncrierを実行する

$ towncrier # ファイルを自動削除するには --yes オプションを付ける

$ git add CHANGELOG.rst changelog # 更新を保存する

$ git commit -m "update changes"

この様な内容が CHANGELOG.rst の先頭に追加されます::

rel-20190312-prd-release (2019-03-25)

=====================================

マイグレーション

----------------

- #832 <https://xxxxx.planio.jp/issues/832>_: XXXのためモデル変更とAPIに影響がないようにリポジトリ変更

リリース時には以下に注意してください。

1. 実装担当者が立ち会うこと

2. 念のため SELECT COUNT(*) FROM foobar WHERE ... が0件なことを確認する

バグ修正

--------

- #1600 <https://xxxxx.planio.jp/issues/1600>_: 本番エラー XXX確定時のXXXXファイル名競合

リリース実施前に SELECT COUNT(*) FROM proof GROUP BY file_data HAVING COUNT(*) > 1; が0件なことを確認すること