#!/usr/bin/python2

#

# Copyright (C) 2015 Red Hat, Inc.

#

# This copyrighted material is made available to anyone wishing to use,

# modify, copy, or redistribute it subject to the terms and conditions of

# the GNU General Public License v.2, or (at your option) any later version.

# This program is distributed in the hope that it will be useful, but WITHOUT

# ANY WARRANTY expressed or implied, including the implied warranties of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General

# Public License for more details.  You should have received a copy of the

# GNU General Public License along with this program; if not, write to the

# Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA

# 02110-1301, USA.  Any Red Hat trademarks that are incorporated in the

# source code or documentation are not subject to the GNU General Public

# License and may only be used or replicated with the express permission of

# Red Hat, Inc.

#

r"""A script intended to update release notes.

Works on Python >= 2.7 and < 3.0.

This module, when run as a script, provides a command line interface.

The interface usage is::

    usage: prog [-h]

    Extend the list of issues of the next version in release notes. It

    updates the release notes found in the DNF repository which contains

    this module. The module location is obtained from the __file__

    variable. The version number is parsed from the spec file. If the

    release notes already contains given issue, it is not added again.

    Otherwise, it is added to the beginning of the list. If the release

    notes does not contain the next version, a new section is appended

    right before the first section. The diff between the new release

    notes and the Git index is printed to the standard error stream. The

    message starts with "INFO Update finished. See the diff to the Git

    index: ".

    optional arguments:

      -h, --help  show this help message and exit

    If the version is already released or if another error occurs the

    exit status is non-zero.

:var LOGGER: the logger used by this script

:type LOGGER: logging.Logger

:var SPEC_FN: a name of the DNF spec file relative to the working

   directory of the Git repository which contains this script

:type SPEC_FN: str

:var TAG_PAT: a string pattern of DNF tags where the "{version}" field

   should be replaced with the given version of DNF

:type TAG_PAT: str

:var ISSUE_RE: a regular expression matching numbers of resolved issues

   in the first line of a commit message

:type ISSUE_RE: re.RegexObject

:var RELATED_RE: a regular expression matching numbers of related issues

   in a commit message

:type RELATED_RE: re.RegexObject

:var SIMILAR_RE: a regular expression matching numbers which look like a

   number of an issue referred in a commit message

:type SIMILAR_RE: re.RegexObject

:var NOTES_FN: a name of the DNF release notes file relative to the

   working directory of the Git repository which contains this script

:type NOTES_FN: str

:var TITLE_PAT: a string pattern of a DNF release notes section title

   (including a trailing "\n") where the "{version}" field should be

   replaced with the given release version

:type TITLE_PAT: str

:var ISSUE_PAT: a string pattern of a reference to a resolved issue in

   DNF release notes (including a trailing "\n") where the "{number}"

   field should be replaced with the number of the given issue

:type ISSUE_PAT: str

:var OVERLINE_RE: a regular expression matching a section title overline

   in a line of DNF release notes

:type OVERLINE_RE: re.RegexObject

:var TITLE_RE_PAT: a string pattern of a regular expression matching a

   section title in a line of DNF release notes where the "{maxlen}"

   field should be replaced with the maximum expected length of the

   release version

:type TITLE_RE_PAT: str

"""

from __future__ import absolute_import

import argparse

import contextlib

import io

import itertools

import logging

import os

import re

import shutil

import sys

import tempfile

import unittest

import git

import rpm

import tests.mock

LOGGER = logging.getLogger(sys.argv[0])

SPEC_FN = 'dnf.spec'

TAG_PAT = 'dnf-{version}-1'

ISSUE_RE = re.compile(ur'(?

RELATED_RE = re.compile(ur'Related: RhBug:(\d+)')

SIMILAR_RE = re.compile(ur'\d{6,}')

NOTES_FN = os.path.join('doc', 'release_notes.rst')

TITLE_PAT = '{version} Release Notes\n'

ISSUE_PAT = '* :rhbug:`{number}`\n'

OVERLINE_RE = re.compile('^(=+)\n$')

TITLE_RE_PAT = '^(.{{,{maxlen}}}) Release Notes\n$'

@contextlib.contextmanager

def _safe_overwrite(name):

    """Open a file in order to overwrite it safely.

    Until the context manager successfully exits, the file remains

    unchanged.

    :param name: name of the file

    :type name: str

    :returns: a context manager that returns a readable text file object

        intended to read the content of the file and a writable text

        file object intended to write the new content of the file

    :rtype: contextmanager[tuple[file, file]]

    :raises exceptions.IOError: if the file cannot be opened

    """

    with open(name, 'rt+') as file_, tempfile.TemporaryFile('wt+') as tmpfile:

        yield file_, tmpfile

        tmpfile.seek(0)

        file_.seek(0)

        shutil.copyfileobj(tmpfile, file_)

def detect_repository():

    """Detect the DNF Git repository which contains this module.

    The module location is obtained from :const:`__file__`.

    :returns: the repository

    :rtype: git.Repo

    """

    dirname = os.path.dirname(__file__)

    # FIXME remove this once we can get rid of supporting GitPython < 0.3.5

    try:

        return git.Repo(dirname, search_parent_directories=True)

    except TypeError:

        return git.Repo(dirname)

def detect_version(repository):

    """Detect the DNF version from its spec file.

    :param repository: a non-bare DNF repository which contains the spec

       file

    :type repository: git.Repo

    :returns: the detected version

    :rtype: str

    """

    filename = os.path.join(repository.working_dir, SPEC_FN)

    return rpm.spec(filename).sourceHeader[rpm.RPMTAG_VERSION]

def find_tag(repository, version):

    """Find the Git tag corresponding to a DNF version.

    :param repository: a DNF repository

    :type repository: git.Repo

    :returns: the name of the tag

    :rtype: str | None

    """

    tagname = TAG_PAT.format(version=version)

    return tagname if tagname in repository.tags else None

def iter_unreleased_commits(repository):

    """Iterate over the commits that were not tagged as a release.

    :param repository: a repository

    :type repository: git.Repo

    :returns: a generator yielding the commits

    :rtype: generator[git.Commit]

    """

    tagshas = {tag.commit.hexsha for tag in repository.tags}

    for commit in repository.iter_commits():

        if commit.hexsha in tagshas:

            # FIXME encode() once we get rid of supporting GitPython < 0.3.4

            LOGGER.debug(

                'Unreleased commits iteration stopped on the first tagged '

                'commit: %s', commit.hexsha.encode())

            break

        yield commit

def parse_issues(commits):

    """Parse the numbers of the resolved DNF issues from commit messages.

    :param commits: the DNF commits

    :type commits: collections.Iterable[git.Commit]

    :returns: a generator yielding the issue numbers

    :rtype: generator[str]

    """

    for commit in commits:

        firstline = commit.message.splitlines()[0]

        valid = {match.group(1) for match in ISSUE_RE.finditer(firstline)}

        for issue in valid:

            issue = issue.encode()

            # FIXME decode() once we get rid of supporting GitPython < 0.3.4

            LOGGER.debug(

                'Recognized %s in commit %s.', issue,

                commit.hexsha.decode().encode())

            yield issue.encode()

        valid |= {mat.group(1) for mat in RELATED_RE.finditer(commit.message)}

        for match in SIMILAR_RE.finditer(commit.message):

            if match.group(0) not in valid:

                # FIXME decode once we get rid of supporting GitPython < 0.3.4

                LOGGER.warning(

                    'Skipped %s in commit %s which looks like an issue '

                    'number.', match.group(0).encode(),

                    commit.hexsha.decode().encode())

def extend_releases(releases, version, issues):

    r"""Extend the list of issues of a release version in release notes.

    The issues are appended to the beginning of the list. If an issue is

    already in the list of the release version, it is not added again.

    If the release version is not found, the release version

    (``version, '\n', issues, '\n'``) is yielded right before the first

    release version in the release notes.

    :param releases: the version, the description, the list of issue

       numbers and the epilog for each release version in release notes

    :type releases: collections.Iterable[tuple[str | None, str, list[str], str]]

    :param version: the release version to be extended

    :type version: str

    :param issues: the issues to be added

    :type issues: collections.Iterable[str]

    :returns: a generator yielding the modified release notes

    :rtype:  generator[tuple[str | None, str, list[str], str]]

    """

    releases, issues = list(releases), list(issues)

    prepend = not any(release[0] == version for release in releases)

    for version_, description, issues_, epilog in releases:

        if prepend and version_ is not None:

            yield version, '\n', issues, '\n'

            prepend = False

        elif version_ == version:

            issues_ = issues_[:]

            for issue in reversed(issues):

                if issue not in issues_:

                    issues_.insert(0, issue)

        yield version_, description, issues_, epilog

def format_release(version, description, issues, epilog):

    """Compose a string in form of DNF release notes from a release.

    The order of issues is preserved.

    :param version: the version of the release

    :type version: str | None

    :param description: the description of the release

    :type description: str

    :param issues: the list of issue numbers of the release

    :type issues: list[str]

    :param epilog: the epilog of the release

    :type epilog: str

    :returns: the formatted string

    :rtype: str

    """

    titlestr = ''

    if version:

        title = TITLE_PAT.format(version=version)

        length = len(title) - 1

        titlestr = '{}\n{}{}\n'.format('=' * length, title, '=' * length)

    issuestr = ''.join(ISSUE_PAT.format(number=issue) for issue in issues)

    return ''.join([titlestr, description, issuestr, epilog])

def update_notes():

    r"""Extend the list of issues of the next version in release notes.

    It updates the release notes found in the DNF repository which

    contains this module. The module location is obtained from

    :const:`__file__`. The version number is parsed from the spec file.

    If the release notes already contains given issue, it is not added

    again. Otherwise, it is added to the beginning of the list. If the

    release notes does not contain the next version, a new section is

    appended right before the first section. The diff between the new

    release notes and the Git index is logged to :const:`.LOGGER` with

    level :const:`INFO`. The message starts with "Update finished. See

    the diff to the Git index:\n".

    :raises exceptions.ValueError: if the version is already released

    """

    repository = detect_repository()

    LOGGER.info('Detected the repository at: %s', repository.working_dir)

    notesfn = os.path.join(repository.working_dir, NOTES_FN)

    version = detect_version(repository)

    LOGGER.info('Detected DNF version (from the spec file): %s', version)

    issues = parse_issues(iter_unreleased_commits(repository))

    parser = ReleaseNotesParser()

    tagname = find_tag(repository, version)

    if tagname:

        LOGGER.warning('Found a tag matching the current version: %s', tagname)

        LOGGER.error('Extending an already released version is not allowed!')

        raise ValueError('version already released')

    with _safe_overwrite(notesfn) as (source, destination):

        releases = extend_releases(parser.parse_lines(source), version, issues)

        for version_, desc, issues_, epilog in releases:

            destination.write(format_release(version_, desc, issues_, epilog))

    diff = repository.index.diff(None, NOTES_FN, create_patch=True)[0].diff

    LOGGER.info(

        'Update finished. See the diff to the Git index:\n%s',

        re.sub(r'^', '    ', diff, flags=re.M))

def main():

    """Start the main loop of the command line interface.

    The root logger is configured to write DEBUG+ messages into the

    directory where is this module located if not configured otherwise.

    A handler that writes INFO+ messages to :data:`sys.stderr` is added

    to :const:`.LOGGER`.

    The interface usage is::

        usage: prog [-h]

        Extend the list of issues of the next version in release notes.

        It updates the release notes found in the DNF repository which

        contains this module. The module location is obtained from the

        __file__ variable. The version number is parsed from the spec

        file. If the release notes already contains given issue, it is

        not added again. Otherwise, it is added to the beginning of the

        list. If the release notes does not contain the next version, a

        new section is appended right before the first section. The diff

        between the new release notes and the Git index is printed to

        the standard error stream. The message starts with "INFO Update

        finished. See the diff to the Git index: ".

        optional arguments:

          -h, --help  show this help message and exit

        If the version is already released or if another error occurs

        the exit status is non-zero.

    :raises exceptions.SystemExit: with a non-zero exit status if an

       error occurs

    """

    logging.basicConfig(

        filename='{}.log'.format(__file__),

        filemode='wt',

        format='%(asctime)s.%(msecs)03d:%(levelname)s:%(name)s:%(message)s',

        datefmt='%Y%m%dT%H%M%S',

        level=logging.DEBUG)

    handler = logging.StreamHandler()

    handler.setLevel(logging.INFO)

    handler.setFormatter(logging.Formatter('%(levelname)s %(message)s'))

    LOGGER.addHandler(handler)

    argparser = argparse.ArgumentParser(

        description='Extend the list of issues of the next version in release '

                    'notes. It updates the release notes found in the DNF '

                    'repository which contains this module. The module '

                    'location is obtained from the __file__ variable. The '

                    'version number is parsed from the spec file. If the '

                    'release notes already contains given issue, it is not '

                    'added again. Otherwise, it is added to the beginning of '

                    'the list. If the release notes does not contain the next '

                    'version, a new section is appended right before the first'

                    ' section. The diff between the new release notes and the '

                    'Git index is printed to the standard error stream. The '

                    'message starts with "INFO Update finished. See the diff '

                    'to the Git index:\n".',

        epilog='If the version is already released or if another error occurs '

               'the exit status is non-zero.')

    argparser.parse_args()

    try:

        update_notes()

    except ValueError:

        sys.exit(1)

class ReleaseNotesParser(object):

    """A class able to parse DNF release notes.

    :ivar _needline: an expected line which represents the end of a

       section title

    :type _needline: str | None

    :ivar _version: a version parsed from a potential next section title

    :type _version: str | None

    :ivar version: a version parsed from the last section title

    :type version: str | None

    :ivar description: lines parsed from the last section description

    :type description: list[str]

    :ivar issues: numbers of resolved issues parsed from the last

       section

    :type issues: list[str]

    :ivar epilog: lines parsed from the last section epilog

    :type epilog: list[str]

    """

    def __init__(self):

        """Initialize the parser."""

        super(ReleaseNotesParser, self).__init__()

        self._needline = None

        self._version = None

        self.version = None

        self.description = []

        self.issues = []

        self.epilog = []

    @property

    def _last_version(self):

        """The last parsed release version.

        :returns: the version, the description, the list of issue

           numbers and the epilog of the release

        :rtype: tuple[str | None, str, list[str], str]

        """

        return (

            self.version,

            ''.join(self.description),

            self.issues,

            ''.join(self.epilog))

    def _cancel_title(self):

        """Cancel expectations of a next section title.

        It modifies :attr:`_needline` and :attr:`_version`.

        :returns: the old values of :attr:`_needline` and

           :attr:`_version`

        :rtype: tuple[str | None, str | None]

        """

        needline, version = self._needline, self._version

        self._needline = self._version = None

        return needline, version

    def _parse_overline(self, line):

        """Parse the overline of the next section title from a line.

        It changes the state of the parser.

        :param line: the line to be parsed

        :type line: str

        :returns: returns :data:`True` if the line contains an

            overline, otherwise it returns :data:`False`

        :rtype: bool

        """

        match = OVERLINE_RE.match(line)

        if not match:

            return False

        self._cancel_title()

        self._needline = match.group(1)

        return True

    def _parse_title(self, line):

        """Parse the title from a line.

        It changes the state of the parser even if the line does not

        contain a title.

        :param line: the line to be parsed

        :type line: str

        :returns: returns :data:`True` if the line contains a title,

           otherwise it returns :data:`False`

        :rtype: bool

        """

        maxlen = len(self._needline) - len(' Release Notes')

        match = re.match(TITLE_RE_PAT.format(maxlen=maxlen), line)

        if not match:

            self._cancel_title()

            return False

        self._version = match.group(1)

        return True

    def _parse_underline(self, line):

        """Parse the underline of the next section title from a line.

        It changes the state of the parser.

        :param line: the line to be parsed

        :type line: str

        :returns: the version, the description, the list of issue

           numbers and the epilog of the previous release

        :rtype: tuple[str | None, str, list[str], str] | None

        """

        needline, version = self._cancel_title()

        if line != '{}\n'.format(needline):

            return None

        previous_version = self._last_version

        self.version = version

        self.description, self.issues, self.epilog = [], [], []

        return previous_version

    def _parse_issue(self, line):

        """Parse an issue number from a line.

        It changes the state of the parser.

        :param line: the line to be parsed

        :type line: str

        :returns: returns :data:`True` if the line refers to an issue,

           otherwise it returns :data:`False`

        :rtype: bool

        """

        match = re.match(r'^\* :rhbug:`(\d+)`\n$', line)

        if not match:

            return False

        self.issues.append(match.group(1))

        return True

    def _parse_line(self, line):

        """Parse a line of DNF release notes.

        It changes the state of the parser.

        :param line: the line to be parsed

        :type line: str

        :returns: the version, the description, the list of issue

           numbers and the epilog of the previous release

        :rtype: tuple[str | None, str, list[str], str] | None

        """

        needtitle = self._needline and self._version

        if not needtitle and self._parse_overline(line):

            return None

        if self._needline and not self._version and self._parse_title(line):

            return None

        if self._needline and self._version:

            previous_version = self._parse_underline(line)

            if previous_version:

                return previous_version

        if not self.epilog and self._parse_issue(line):

            return None

        if not self.issues:

            self.description.append(line)

            return None

        self.epilog.append(line)

    def parse_lines(self, lines):

        """Parse the lines of DNF release notes.

        :param lines: the line to be parsed

        :type lines: collections.Iterable[str]

        :returns: a generator yielding the version, the description, the

           list of issue numbers and the epilog of each release version

        :rtype: generator[tuple[str | None, str, list[str], str]]

        """

        self._needline = None

        self._version = None

        self.version = None

        self.description = []

        self.issues = []

        self.epilog = []

        for line in lines:

            previous_version = self._parse_line(line)

            if previous_version:

                yield previous_version

        yield self._last_version

class TestCase(unittest.TestCase):

    """A test fixture common to all tests.

    Among other things, the fixture contains a non-bare DNF repository

    with a spec file specifying an unreleased version, a tag dnf-1.0.1-1

    matching the version 1.0.1, one extra commit which resolves an issue

    and release notes matching the revision 9110490 of DNF.

    :cvar VERSION: the unreleased version specified in the spec file

    :type VERSION: str

    :cvar ISSUE: the number of the issue resolved by the extra commit

    :type ISSUE: str

    :ivar repository: the testing repository

    :type repository: git.Repo

    :ivar commit: the extra commit

    :type commit: unicode

    """

    VERSION = '999.9.9'

    ISSUE = '123456'

    def setUp(self):

        """Prepare the test fixture.

        :const:`__file__` is needed to prepare the fixture.

        """

        dirname = tempfile.mkdtemp()

        self.addCleanup(shutil.rmtree, dirname)

        self.repository = detect_repository().clone(dirname)

        self.repository.head.reset(

            '9110490d690bbad10977b86e7ffbe1feeae26e03', working_tree=True)

        with open(os.path.join(dirname, SPEC_FN), 'wt') as specfile:

            specfile.write(

                'Name: dnf\n' +

                'Version: {}\n'.format(self.VERSION) +

                'Release: 1\n'

                'Summary: Package manager forked from Yum\n'

                'License: GPLv2+ and GPLv2 and GPL\n'

                '%description\n'

                'Package manager forked from Yum, using libsolv.\n'

                '%files\n')

        self.repository.index.add([SPEC_FN])

        self.commit = self.repository.index.commit(

            u'Version (RhBug:{})'.format(self.ISSUE.decode()))

    @staticmethod

    @contextlib.contextmanager

    def _read_copy(name):

        """Create and open a readable copy of a file.

        :param name: name of the file

        :type name: str

        :returns: the readable copy

        :rtype: file

        :raises exceptions.IOError: if the file cannot be opened

        """

        with tempfile.TemporaryFile('wt+') as copy:

            with open(name, 'rt') as original:

                shutil.copyfileobj(original, copy)

            copy.seek(0)

            yield copy

    @contextlib.contextmanager

    def _patch_file(self):

        """Temporarily set :const:`__file__` to point to the testing repo.

        :returns: a context manager

        :rtype: contextmanager

        """

        filename = os.path.join(

            self.repository.working_dir, 'scripts', 'update_releasenotes.py')

        original = __file__

        with tests.mock.patch('update_releasenotes.__file__', filename):

            assert __file__ != original, 'double check that the patch works'

            yield

    @contextlib.contextmanager

    def _assert_logs(self, level, regex):

        """Test whether a message matching an expression is logged.

        :param level: the level of the message

        :type level: int

        :param regex: the regular expression to be matched

        :type regex: re.RegexObject

        :returns: a context manager which represents the block in which

           the message should be logged

        :rtype: contextmanager

        :raises exceptions.AssertionError: if the test fails

        """

        class Handler(logging.Handler):

            def __init__(self, regex):

                super(Handler, self).__init__()

                self.regex = regex

                self.found = False

            def emit(self, record):

                if not self.found:

                    self.found = self.regex.match(record.getMessage())

        handler = Handler(regex)

        LOGGER.setLevel(level)

        LOGGER.addHandler(handler)

        yield

        self.assertTrue(handler.found)

    @contextlib.contextmanager

    def _assert_prints(self, regex, stream):

        """Test whether a message matching an expression is printed.

        :param regex: the regular expression to be matched

        :type regex: re.RegexObject

        :param stream: a name of the stream to be matched

        :type stream: str

        :returns: a context manager which represents the block in which

           the message should be printed

        :rtype: contextmanager

        :raises exceptions.AssertionError: if the test fails

        """

        with tests.mock.patch(stream, io.BytesIO()) as mock:

            yield

            self.assertRegexpMatches(mock.getvalue(), regex)

    def _assert_iter_equal(self, actual, expected):

        """Test whether two iterables are equal.

        :param actual: one of the iterables

        :type actual: collections.Iterable[object]

        :param expected: the other iterable

        :type expected: collections.Iterable[object]

        :raises exceptions.AssertionError: if the test fails

        """

        self.assertTrue(all(

            actual_ == expected_ for actual_, expected_ in

            itertools.izip_longest(actual, expected, fillvalue=object())))

    def test_detect_repository(self):

        """Test whether correct repository is detected.

        :raises exceptions.AssertionError: if the test fails

        """

        with self._patch_file():

            self.assertEqual(

                detect_repository().working_dir, self.repository.working_dir)

    def test_detect_version(self):

        """Test whether correct version is detected.

        :raises exceptions.AssertionError: if the test fails

        """

        self.assertEqual(detect_version(self.repository), self.VERSION)

    def test_find_tag_name(self):

        """Test whether correct tag is detected.

        :raises exceptions.AssertionError: if the test fails

        """

        self.assertEqual(find_tag(self.repository, '1.0.1'), 'dnf-1.0.1-1')

    def test_find_tag_none(self):

        """Test whether correct tag is detected.

        :raises exceptions.AssertionError: if the test fails

        """

        self.assertIsNone(find_tag(self.repository, '9999'))

    def test_iter_unreleased_commits(self):

        """Test whether correct commits are yielded.

        :raises exceptions.AssertionError: if the test fails

        """

        commits = iter_unreleased_commits(self.repository)

        self.assertItemsEqual(

            (commit.hexsha for commit in commits), [self.commit.hexsha])

    def test_parse_issues(self):

        """Test whether correct issues are yielded.

        :raises exceptions.AssertionError: if the test fails

        """

        self.assertItemsEqual(parse_issues([self.commit]), [self.ISSUE])

    def test_extend_releases_extend(self):

        """Test whether the release version is extended.

        :raises exceptions.AssertionError: if the test fails

        """

        releases = [

            (None, 'd1\n', [], ''),

            ('1.0.1', '\nd2\n', ['234567'], '\n'),

            ('999.9.9', '\nd3\n', ['345678'], '\n')]

        expected = [

            (None, 'd1\n', [], ''),

            ('1.0.1', '\nd2\n', ['456789', '234567'], '\n'),

            ('999.9.9', '\nd3\n', ['345678'], '\n')]

        self.assertItemsEqual(

            extend_releases(releases, '1.0.1', ['456789']), expected)

    def test_extend_releases_skip(self):

        """Test whether the already present issues are skipped.

        :raises exceptions.AssertionError: if the test fails

        """

        releases = [

            (None, 'd1\n', [], ''),

            ('1.0.1', '\nd2\n', ['234567'], '\n'),

            ('999.9.9', '\nd3\n', ['345678'], '\n')]

        expected = [

            (None, 'd1\n', [], ''),

            ('1.0.1', '\nd2\n', ['234567'], '\n'),

            ('999.9.9', '\nd3\n', ['345678'], '\n')]

        self.assertItemsEqual(

            extend_releases(releases, '1.0.1', ['234567']), expected)

    def test_extend_releases_append(self):

        """Test whether the rel. version is appended to the beginning.

        :raises exceptions.AssertionError: if the test fails

        """

        releases = [

            (None, 'd1\n', [], ''),

            ('1.0.1', '\nd2\n', ['234567'], '\n')]

        expected = [

            (None, 'd1\n', [], ''),

            ('999.9.9', '\n', ['345678'], '\n'),

            ('1.0.1', '\nd2\n', ['234567'], '\n')]

        self.assertItemsEqual(

            extend_releases(releases, '999.9.9', ['345678']), expected)

    def test_format_release_version(self):

        """Test whether correct string is returned.

        :raises exceptions.AssertionError: if the test fails

        """

        self.assertEqual(

            format_release('1.0.1', '\ndesc\n', ['123456', '234567'], '\ne\n'),

            '===================\n'

            '1.0.1 Release Notes\n'

            '===================\n'

            '\n'

            'desc\n'

            '* :rhbug:`123456`\n'

            '* :rhbug:`234567`\n'

            '\n'

            'e\n')

    def test_format_release_none(self):

        """Test whether no version is handled properly.

        :raises exceptions.AssertionError: if the test fails

        """

        self.assertEqual(format_release(None, 'l1\nl2\n', [], ''), 'l1\nl2\n')

    def test_update_notes_append(self):

        """Test whether the rel. version is appended to the beginning.

        :raises exceptions.AssertionError: if the test fails

        """

        regex = re.compile(

            '^Update finished. See the diff to the Git index:\n.+')

        notesfn = os.path.join(self.repository.working_dir, NOTES_FN)

        title = TITLE_PAT.format(version=self.VERSION)