From 16c24f17e347fbcc9c1e8da5aa9a04df4266cff6 Mon Sep 17 00:00:00 2001 From: GlenNicholls Date: Fri, 10 Mar 2023 22:13:35 +0000 Subject: [PATCH 1/2] docs: improve changelog to be automatically generated by towncrier Co-Authored-By: Unai Martinez-Corral --- docs/.gitignore | 1 - docs/conf.py | 2 +- docs/contributing.rst | 64 ++++++++++++++++++++++++++++------- docs/news.d/.gitkeep | 0 docs/release_notes.rst | 13 +++++++ pyproject.toml | 39 +++++++++++++++++++++ tools/create_release_notes.py | 19 ++++------- 7 files changed, 111 insertions(+), 27 deletions(-) create mode 100644 docs/news.d/.gitkeep create mode 100644 docs/release_notes.rst diff --git a/docs/.gitignore b/docs/.gitignore index ac8acf3cb..9469c1ec4 100644 --- a/docs/.gitignore +++ b/docs/.gitignore @@ -1,4 +1,3 @@ /_build/ /*.inc /license.rst -/release_notes.rst diff --git a/docs/conf.py b/docs/conf.py index b02f19d20..8dd1c2723 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -51,7 +51,7 @@ language = "en" -exclude_patterns = ["release_notes/*.*"] +exclude_patterns = ["release_notes/*.*", "news.d/*.*"] todo_include_todos = False diff --git a/docs/contributing.rst b/docs/contributing.rst index d7975044b..d893deead 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -189,26 +189,38 @@ A full list of test environments can be seen by issuing the following command: Making releases ~~~~~~~~~~~~~~~ +.. IMPORTANT:: + Reference :ref:`release_notes_instructions` for creating relevant news fragments that will be added to the :ref:`release_notes`. + Releases are automatically made by GitHub Actions on any ``master`` commit which is tagged. To create a new tagged release commit: -- Create corresponding release notes in ``docs/release_notes/X.Y.Z.rst``. - - The release notes files in ``docs/release_notes/`` are used to - automatically generate the :ref:`release notes `. +- Build the docs and review the content of ``docs/news.inc``. + + - If necessary, create additional news files and build the docs again. + +- Add the news summary as the release notes and remove news fragments: + + .. code-block::python + + mv docs/news.inc docs/release_notes/X.Y.Z.rst + git add docs/release_notes/X.Y.Z.rst + git rm -f docs/news.d/*.rst + - Execute ``python tools/release.py create X.Y.Z``. - - Will make commit with the new ``about.py`` version and release notes and tag it. - - Will make another commit setting ``about.py`` to the next pre release candidate version. + - Will make and tag a commit with the new ``about.py`` version, the release notes and removed news files. + - Will make another commit setting ``about.py`` to the next development version. + - Push the tag to remote to trigger the release build. - - ``git push origin vX.Y.Z`` -- If the release build is successful, you can push the two commits to master. - - ``git push origin master`` - - If, in the meantime, a new commit has come into origin/master the two - commits have to be merged into origin/master. + - ``git push origin vX.Y.Z`` +- If the release build is successful, you can push the two commits to master. + - ``git push origin master`` + - If, in the meantime, a new commit has come into origin/master the two commits have to be merged into origin/master. -The CI service makes a release by uploading a new package to PyPI when a tag -named ``vX.Y.Z`` is found in Git. A new release will not be made if: +The CI service makes a release by uploading a new package to PyPI when a tag named ``vX.Y.Z`` is found in Git. +A new release will not be made if: - The ``X.Y.Z`` release is already on PyPI. - The repo tag does not exist. @@ -222,3 +234,31 @@ Therefore, when bumping the submodules, maintainers/contributors need to remembe version. Furthermore, since OSVVM is tagged periodically, bumping from tag to tag is strongly suggested. + +.. _release_notes_instructions: + +Release Notes Instructions +-------------------------- + +The :vunit_file:`release notes directory ` contains "newsfragments" which +are short (`reST formatted +`_) files that +contain information for users. + +Make sure to use full sentences in the **past or present tense** and use punctuation. + +Each file should be named like ``..rst``, where ```` is the +GitHub issue or pull request number, and ```` is one of: + +* ``breaking``: a change which may break existing functionality, such as feature removal + or behavior change +* ``bugfix``: fixes a bug +* ``change``: backwards compatible features or improvements +* ``deprecation``: feature deprecation +* ``misc``: a ticket was closed, but it is not necessarily important for the user + +For example: ``123.feature.rst``, ``456.bugfix.rst``. + +``towncrier`` preserves multiple paragraphs and formatting +(code blocks, lists, and so on), but for entries other than features, it is usually +better to stick to a single paragraph to keep it concise. diff --git a/docs/news.d/.gitkeep b/docs/news.d/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/docs/release_notes.rst b/docs/release_notes.rst new file mode 100644 index 000000000..7f89f628f --- /dev/null +++ b/docs/release_notes.rst @@ -0,0 +1,13 @@ +.. _release_notes: + +Release notes +============= + +.. NOTE:: For installation instructions read :ref:`this `. + +:vunit_commit:`Next ` +----------------------------- + +.. include:: news.inc + +.. include:: release_notes.inc diff --git a/pyproject.toml b/pyproject.toml index f94bdc461..9f860a53f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -8,6 +8,44 @@ build-backend = "setuptools.build_meta" [tool.black] line-length = 120 +[tool.towncrier] +package = "vunit" +package_dir = "vunit" +single_file = false +filename="docs/news.inc" +directory = "docs/news.d/" +title_format = false +issue_format = ":vunit_issue:`{issue}`" +underlines = ["-", "~"] + + [[tool.towncrier.section]] + path = "" + + [[tool.towncrier.type]] + directory = "breaking" + name = "Breaking Changes" + showcontent = true + + [[tool.towncrier.type]] + directory = "bugfix" + name = "Bug Fixes" + showcontent = true + + [[tool.towncrier.type]] + directory = "change" + name = "Changes" + showcontent = true + + [[tool.towncrier.type]] + directory = "deprecation" + name = "Deprecations" + showcontent = true + + [[tool.towncrier.type]] + directory = "misc" + name = "Miscellaneous" + showcontent = true + [tool.tox] legacy_tox_ini = """ [tox] @@ -34,6 +72,7 @@ deps= docs: furo docs: sphinx docs: sphinx-argparse + docs: towncrier setenv= acceptance-activehdl: VUNIT_SIMULATOR=activehdl diff --git a/tools/create_release_notes.py b/tools/create_release_notes.py index ae44d1c97..28f75277b 100644 --- a/tools/create_release_notes.py +++ b/tools/create_release_notes.py @@ -11,7 +11,7 @@ from pathlib import Path from os.path import relpath from glob import glob -from subprocess import check_output, CalledProcessError +from subprocess import check_call, check_output, CalledProcessError from shutil import which import datetime @@ -33,22 +33,15 @@ def create_release_notes(): """ source_path = Path(__file__).parent.parent / "docs" + check_call(["towncrier", "build", "--keep"], cwd=source_path.parent) + releases = get_releases(source_path) latest_release = releases[0] - with (source_path / "release_notes.rst").open("w", encoding="utf-8") as fptr: + with (source_path / "release_notes.inc").open("w", encoding="utf-8") as fptr: fptr.write( - f""" -.. _release_notes: - -Release notes -============= - -.. NOTE:: For installation instructions read :ref:`this `. - -`Commits since last release `__ - -""" + "`Commits since last release " + f"`__" ) fptr.write("\n\n") From cabe6dc3369020386e395e324a85ef9e48133b52 Mon Sep 17 00:00:00 2001 From: GlenNicholls Date: Fri, 10 Mar 2023 22:13:35 +0000 Subject: [PATCH 2/2] docs/news.d: add 921.misc --- docs/news.d/921.misc.rst | 2 ++ 1 file changed, 2 insertions(+) create mode 100644 docs/news.d/921.misc.rst diff --git a/docs/news.d/921.misc.rst b/docs/news.d/921.misc.rst new file mode 100644 index 000000000..dbd2f108d --- /dev/null +++ b/docs/news.d/921.misc.rst @@ -0,0 +1,2 @@ +Improved release notes by adding sections to aid in finding relevant information +about releases and updated contributing guide with instructions.