From ca61889d4ac73e9864fbf637fb87ab2d5bc053ea Mon Sep 17 00:00:00 2001 From: codejedi365 Date: Wed, 6 Nov 2024 18:51:52 -0700 Subject: [PATCH] docs(commit-parsing): add `linked_merge_request` field to Parsed Commit definition --- docs/commit-parsing.rst | 68 ++++++++++++++++++++++++++++------------- 1 file changed, 46 insertions(+), 22 deletions(-) diff --git a/docs/commit-parsing.rst b/docs/commit-parsing.rst index 4d6c1747d..dc5d88afe 100644 --- a/docs/commit-parsing.rst +++ b/docs/commit-parsing.rst @@ -45,9 +45,12 @@ The following parsers are built in to Python Semantic Release: ``semantic_release.commit_parser.AngularCommitParser`` """""""""""""""""""""""""""""""""""""""""""""""""""""" -The default parser, which uses the `Angular commit style `_ with the following differences: +The default parser, which uses the +`Angular commit style `_ +with the following differences: - Multiple ``BREAKING CHANGE:`` paragraphs are supported + - ``revert`` is not currently supported The default configuration options for @@ -222,26 +225,41 @@ as the commit history of a repository is being parsed. Python Semantic Release d not raise an exception if a commit cannot be parsed. Python Semantic Release uses :py:class:`semantic_release.ParsedCommit` -as the return type of a successful parse operation, and :py:class:`semantic_release.ParseError` -as the return type from an unsuccessful parse of a commit. :py:class:`semantic_release.ParsedCommit` is a `namedtuple`_ which has the following fields: - -* bump: a :py:class:`semantic_release.LevelBump` indicating what type of change this commit introduces. -* type: the *type* of the commit as a string, per the commit message style. This is up to the - parser to implement; for example, the :py:class:`semantic_release.commit_parser.EmojiCommitParser` - parser fills this field with the emoji representing the most significant change for the commit. - The field is named after the representation in the Angular commit specification. -* scope: The scope, as a string, parsed from the commit. Commit styles which do not have a meaningful - concept of "scope" should fill this field with an empty string. -* descriptions: A list of paragraphs (strings) (delimited by a double-newline) from the commit message. -* breaking_descriptions: A list of paragraphs (strings) which are deemed to identify and describe - breaking changes by the parser. An example would be a paragraph which begins with the text - ``BREAKING CHANGE:``. -* commit: The original commit object that was parsed. +as the return type of a successful parse operation, and +:py:class:`semantic_release.ParseError` as the return type from an unsuccessful +parse of a commit. :py:class:`semantic_release.ParsedCommit` is a `namedtuple`_ +which has the following fields: + +* **bump**: a :py:class:`semantic_release.LevelBump` indicating what type of change + this commit introduces. + +* **type**: the *type* of the commit as a string, per the commit message style. This + is up to the parser to implement; for example, the + :py:class:`semantic_release.commit_parser.EmojiCommitParser` parser fills this field + with the emoji representing the most significant change for the commit. The field is + named after the representation in the Angular commit specification. + +* **scope**: The scope, as a string, parsed from the commit. Commit styles which do + not have a meaningful concept of "scope" should fill this field with an empty string. + +* **descriptions**: A list of paragraphs (strings) (delimited by a double-newline) + from the commit message. + +* **breaking_descriptions**: A list of paragraphs (strings) which are deemed to + identify and describe breaking changes by the parser. An example would be a + paragraph which begins with the text ``BREAKING CHANGE:``. + +* **commit**: The original commit object (a class defined by GitPython) that was parsed. + +* **linked_merge_request**: A pull request or merge request definition, if the commit is + labeled with a pull/merge request number. This is a string value which includes any + special character prefix used by the VCS (e.g. ``#`` for GitLab, ``!`` for Bitbucket). :py:class:`semantic_release.ParseError` is a `namedtuple`_ which has the following fields: -* commit: The original commit object that was parsed. -* error: A string with a meaningful error message as to why the commit parsing failed. +* **commit**: The original commit object that was parsed. + +* **error**: A string with a meaningful error message as to why the commit parsing failed. In addition, :py:class:`semantic_release.ParseError` implements an additional method, ``raise_error``. This method raises a :py:class:`semantic_release.CommitParseError` with the message contained in the @@ -252,10 +270,12 @@ attributes available, each implemented as a ``property`` which is computed, as a convenience for template authors - therefore custom implementations should ensure these properties can also be computed: -* message: the ``message`` attribute of the ``commit``; where the message is of type ``bytes`` - this should be decoded to a ``UTF-8`` string. -* hexsha: the ``hexsha`` attribute of the ``commit``, representing its hash. -* short_hash: the first 7 characters of the ``hexsha`` attribute of the ``commit``. +* **message**: the ``message`` attribute of the ``commit``; where the message is of type + ``bytes`` this should be decoded to a ``UTF-8`` string. + +* **hexsha**: the ``hexsha`` attribute of the ``commit``, representing its hash. + +* **short_hash**: the first 7 characters of the ``hexsha`` attribute of the ``commit``. In Python Semantic Release, the class :py:class:`semantic_release.ParseResult` is defined as ``ParseResultType[ParsedCommit, ParseError]``, as a convenient shorthand. @@ -268,7 +288,9 @@ type returned on an unsuccessful parse of the ``commit``. A custom parser result type, therefore, could be implemented as follows: * ``MyParsedCommit`` subclasses ``ParsedCommit`` + * ``MyParseError`` subclasses ``ParseError`` + * ``MyParseResult = ParseResultType[MyParsedCommit, MyParseError]`` Internally, Python Semantic Release uses ``isinstance`` to determine if the result @@ -326,8 +348,10 @@ the following: * A class-level attribute ``parser_options``, which must be set to :py:class:`semantic_release.ParserOptions` or a subclass of this. + * An ``__init__`` method which takes a single parameter, ``options``, that should be of the same type as the class' ``parser_options`` attribute. + * A method, ``parse``, which takes a single parameter ``commit`` that is of type `git.objects.commit.Commit `_, and returns :py:class:`semantic_release.token.ParseResult`, or a subclass of this.