PHP Class pchCommitMessageCheck, php-commit-hooks

The check implements by default the following grammar for commit messages, while it can be customized like shown later.


 Message       ::= Statement+ | Statement* Comment+
 Statement     ::= Reference | Fixed | Implemented | Documented | Tested
                 | Added | Translated

 Comment       ::= '# ' TextLine | '#\n'

 Reference     ::= '- Refs'         BugNr  ': ' TextLine Text?
 Fixed         ::= '- ' FixedString BugNr  ': ' TextLine Text?
 Implemented   ::= '- Implemented'  BugNr? ': ' TextLine Text?
 Documented    ::= '- Documented'   BugNr? ': ' TextLine Text?
 Tested        ::= '- Tested: '                 TextLine Text?
 Added         ::= '- Added: '                  TextLine Text?
 Translated    ::= '- Translated: '             TextLine Text?

 FixedString   ::= 'Fixed' | 'Closed'

 Text          ::= '  ' TextLine Text?
 BugNr         ::= ' #' [1-9]+[0-9]*
 TextLine      ::= [\x20-\x7E]+ "\n"

With one additional condition not mentioned in the grammar, that no line should ever exceed 79 characters per line. A textual description of the rules above:


 All messages should wrap at 79 characters per line. This means, if you are
 writing multiple lines after a message starting with a "- " each following
 line should be indented by exactly two spaces.

 Including descriptive text in your commit messages is generally important to
 offer a good overview on the commit when the issue tracker is not available
 (commit mails, history).

 All messages may include references to existing issues to add status updates
 to the issue, which should look like::

     - Refs #: 

 Where  references the ticket and the  describes what you did.

 Comments
 --------

 You may always append arbitrary comments in your commit messages, where each
 line should start with a number sign (#). Text in these lines won't be
 checked.

 Bug fix
 -------

 A bug fix commit message should follow the following scheme::

     - Fixed #: 

 Where  references the closed bug and  is a description of the
 bug and the fix. Keep in mind that the texts will be used for the changelog,
 so please check the spelling before committing.

 The bug number is not optional, which means that there should be an open bug
 in the issue tracker for *each* bug you fix.

 For compatibility with other issue tracker you may also use "Closed" instead
 of "Fixed" in your message, but "Fixed" is highly preferred.

 New features
 ------------

 If you implemented a new feature, your commit message should look like::

     - Implemented[ #]: 

 Where  is a short description of the feature you implemented, and
  may optionally reference a feature request in the bug tracker. Keep
 in mind that the texts will be used for the changelog, so please check the
 spelling before committing.

 Documentation
 -------------

 If you extended your documentation, your commit message should look like::

     - Documented[ #]: 

 Where  optionally specifies a documentation request, and the text
 describes what you documented.

 Additional tests
 ----------------

 If you added tests for some feature, your commit message should look like::

     - Tested: 

 Where  describes the feature(s) you are testing.

 Other commits
 -------------

 If your commit does not match any of the above rules you should only include a
 comment in your commit message or extend this document with your commit
 message of desire.

Even we have a contextfree grammar for the language, we implement the trivial parser using regular expressions. You can customize the allowed keywords in the commit messages and if a bug number is optional for each keyword, by providing your own specification array, like described in the constructor documentation.

Inheritance: extends pchCheck

Show file Open project: kore/php-commit-hooks Class Usage Examples

Protected Properties

Property	Type	Description
$result	array	Parsed result in processable form
$rules	array	Commit message validation rules

Public Methods

Method	Description
__construct ( array $specification = null ) : void	Construct parser
getEBNF ( ) : string	Return a string representation of the implemented EBNF
getResult ( ) : array	Get parse result
parse ( string $string ) : array	Parse a commit message
validate ( pchRepository $repository ) : void	Validate the current check

Protected Methods

Method	Description
normalizeWhitespaces ( string $string ) : string	Normalizes whitespaces in commit message
parseStatements ( string $string ) : array	Parse all statements
removeComments ( string $string ) : string	Removes comments from a commit message

Method Details

__construct() public method

You may optionally specify a custom specification array to introduce new keywords, or configure the available keywords differently. The specification array should look like:


 array(
     'Fixed'       => pchCommitMessageCheck::REQUIRED,
     'Implemented' => pchCommitMessageCheck::OPTIONAL,
     'Tested'      => pchCommitMessageCheck::PROHIBITED,
     ...
 );

public __construct ( array $specification = null ) : void
$specification	array
return	void

getEBNF() public method

Returns a string representation of the EBNF, based on the configured rules and the default settings, like the commit message length.

public getEBNF ( ) : string
return	string

getResult() public method

Get parse result

public getResult ( ) : array
return	array

normalizeWhitespaces() protected method

Even not defined in the grammar we do not care about additional newlines or empty lines anywhere.

protected normalizeWhitespaces ( string $string ) : string
$string	string
return	string

parse() public method

Parses a commit messages defined by the grammar documented in the class header. If a parse error occures an array with meesages will be returned. If the commit message matches the defined grammar an empty array will be returned.

public parse ( string $string ) : array
$string	string
return	array

parseStatements() protected method

If a parse error occures an array with meesages will be returned. If the commit message matches the defined grammar an empty array will be returned. A result array with all parsed messages will be stored in the following form and may be requested using the getResult() method:


 array(
     array(
         'type' => ,
         'bug'  =>  | null,
         'text' => ,
     ),
     ...
 )

protected parseStatements ( string $string ) : array
$string	string
return	array

removeComments() protected method

Removes all valid comments from a commit messages, as they are not of interest for the content extraction.

protected removeComments ( string $string ) : string
$string	string
return	string

validate() public method

Validate the check on the specified repository. Returns an array of found issues.

public validate ( pchRepository $repository ) : void
$repository	pchRepository
return	void

Property Details

$result protected property

Parsed result in processable form

protected array $result
return	array

$rules protected property

Commit message validation rules

protected array $rules
return	array