cumulusci-plus 5.0.0__py3-none-any.whl

cumulusci/tasks/release_notes/README.md

@@ -0,0 +1,63 @@
+# GithubReleaseNotesGenerator
+
+This task generates release notes by finding all merged pull requests to the default branch between the date two tags were created.
+
+When you create Pull Requests against the default branch, the generator will parse the Pull Request's body for content that should be included in release notes.
+
+## Critical Changes
+
+The Critical Changes section is where you should list off any changes which might impact existing functionality.
+
+Start the section with `# Critical Changes` followed by your content
+
+For example:
+
+    This won't be included
+    
+    # Critical Changes
+    
+    This will be included in Critical Changes
+    
+## Changes
+
+The Changes section is where you should list off any changes worth highlight to users in the release notes.  This section should always include instructions for users for any post-upgrade tasks they need to perform to enable new functionality.  For example, users should be told to grant permissions and add new CustomFields to layouts.
+
+Start the section with `# Changes` followed by your content
+
+For example:
+
+    This won't be included
+    
+    # Changes
+    
+    This will be included in Changes
+    
+## Issues Closed
+
+The Issues Closed section is where you should link to any closed issues that should be listed in the release notes.
+
+Start the section with `# Changes` followed by your content
+
+For example:
+
+    This won't be included
+    
+    # Issues Closed
+    
+    Fixes #102
+    resolves #100
+    This release closes #101
+
+Would output:
+
+    # Issues Closed
+
+    #100: Title of Issue 100
+    #101: Title of Issue 101
+    #102: Title of Issue 102
+    
+A few notes about how issues are parsed:
+
+* The parser uses the same format as Github: https://help.github.com/articles/closing-issues-via-commit-messages/
+* The parser searches for all issue numbers and sorts them by their integer value, looks up their title, and outputs a formatted line with the issue number and title for each issue.
+* The parser ignores everything else in the line that is not an issue number.  Anything that is not an issue number will not appear in the rendered release notes

cumulusci/tasks/release_notes/exceptions.py

@@ -0,0 +1,5 @@
+from cumulusci.core.exceptions import CumulusCIException
+
+
+class LastReleaseTagNotFoundError(CumulusCIException):
+    pass

cumulusci/tasks/release_notes/generator.py

@@ -0,0 +1,137 @@
+from typing import List
+
+from cumulusci.tasks.release_notes.parser import ChangeNotesLinesParser, IssuesParser
+from cumulusci.tasks.release_notes.provider import (
+    DirectoryChangeNotesProvider,
+    StaticChangeNotesProvider,
+)
+
+
+class BaseReleaseNotesGenerator(object):
+    def __init__(self):
+        self.change_notes: List[BaseReleaseNotesGenerator] = []
+        self.empty_change_notes: List[BaseReleaseNotesGenerator] = []
+        self.init_parsers()
+        self.init_change_notes()
+        self.version_id = None
+        self.trial_info = False
+        self.sandbox_date = None
+        self.production_date = None
+
+    def __call__(self):
+        self._parse_change_notes()
+        return self.render()
+
+    def init_change_notes(self):
+        self.change_notes = self._init_change_notes()
+
+    def _init_change_notes(self):
+        """Subclasses should override this method to return an initialized
+        subclass of BaseChangeNotesProvider"""
+        return []
+
+    def init_parsers(self):
+        """Initializes the parser instances as the list self.parsers"""
+        self.parsers = []
+        self._init_parsers()
+
+    def _init_parsers(self):
+        """Subclasses should override this method to initialize their
+        parsers"""
+        pass
+
+    def _parse_change_notes(self):
+        """Parses all change_notes in self.change_notes() through all parsers
+        in self.parsers"""
+        for change_note in self.change_notes():
+            self._parse_change_note(change_note)
+
+    def _parse_change_note(self, change_note):
+        """Parses an individual change note through all parsers in
+        self.parsers. If no lines were added then appends the change
+        note to the list of empty PRs"""
+        line_added_by_parsers = False
+        for parser in self.parsers:
+            line_added = parser.parse(change_note)
+            if not line_added_by_parsers:
+                line_added_by_parsers = line_added
+
+        if not line_added_by_parsers:
+            self.empty_change_notes.append(change_note)
+
+    def render(self):
+        """Returns the rendered release notes from all parsers as a string"""
+        release_notes = []
+        for parser in self.parsers:
+            parser_content = parser.render()
+            if parser_content:
+                release_notes.append(parser_content)
+        return "\r\n\r\n".join(release_notes)
+
+
+class StaticReleaseNotesGenerator(BaseReleaseNotesGenerator):
+    def __init__(self, change_notes):
+        self._change_notes = change_notes
+        super(StaticReleaseNotesGenerator, self).__init__()
+
+    def _init_parsers(self):
+        self.parsers.append(ChangeNotesLinesParser(self, "Critical Changes"))
+        self.parsers.append(ChangeNotesLinesParser(self, "Changes"))
+        self.parsers.append(IssuesParser(self, "Issues Closed"))
+
+    def _init_change_notes(self):
+        return StaticChangeNotesProvider(self, self._change_notes)
+
+
+class DirectoryReleaseNotesGenerator(BaseReleaseNotesGenerator):
+    def __init__(self, directory):
+        self.directory = directory
+        super(DirectoryReleaseNotesGenerator, self).__init__()
+
+    def _init_parsers(self):
+        self.parsers.append(ChangeNotesLinesParser(self, "Critical Changes"))
+        self.parsers.append(ChangeNotesLinesParser(self, "Changes"))
+        self.parsers.append(IssuesParser(self, "Issues Closed"))
+
+    def _init_change_notes(self):
+        return DirectoryChangeNotesProvider(self, self.directory)
+
+
+def render_empty_pr_section(empty_change_notes):
+    section_lines = []
+    if empty_change_notes:
+        section_lines.append("\n# Pull requests with no release notes")
+        for change_note in empty_change_notes:
+            section_lines.append("\n* {}".format(markdown_link_to_pr(change_note)))
+    return section_lines
+
+
+def markdown_link_to_pr(change_note):
+    return f"{change_note.title} [[PR{change_note.number}]({change_note.html_url})]"
+
+
+# For backwards-compatibility
+import cumulusci.vcs.github.release_notes.generator as githubGenerator
+from cumulusci.utils.deprecation import warn_moved
+
+
+class GithubReleaseNotesGenerator(githubGenerator.GithubReleaseNotesGenerator):
+    """Deprecated: use cumulusci.vcs.github.release_notes.generator.GithubReleaseNotesGenerator instead"""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        warn_moved(
+            "cumulusci.vcs.github.release_notes.generator.GithubReleaseNotesGenerator",
+            __name__,
+        )
+
+
+class ParentPullRequestNotesGenerator(githubGenerator.ParentPullRequestNotesGenerator):
+    """Deprecated: use cumulusci.vcs.github.release_notes.generator.ParentPullRequestNotesGenerator instead"""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        warn_moved(
+            "cumulusci.vcs.github.release_notes.generator.ParentPullRequestNotesGenerator",
+            __name__,
+        )

cumulusci/tasks/release_notes/parser.py

@@ -0,0 +1,232 @@
+import re
+import urllib.parse
+
+from cumulusci.oauth.salesforce import PROD_LOGIN_URL, SANDBOX_LOGIN_URL
+
+
+class BaseChangeNotesParser(object):
+    def __init__(self, title):
+        self.title = title
+        self.content = []
+
+    def parse(self):
+        raise NotImplementedError()
+
+    def render(self, existing_content=""):
+        return "# {}\r\n\r\n{}".format(self.title, self._render())
+
+    def _render(self):
+        raise NotImplementedError()
+
+
+class ChangeNotesLinesParser(BaseChangeNotesParser):
+    def __init__(self, release_notes_generator, title):
+        super(ChangeNotesLinesParser, self).__init__(title)
+        self.release_notes_generator = release_notes_generator
+        self.title = title
+        self._in_section = False
+        self.h2 = {}  # dict of h2 sections - key=header, value is list of lines
+        self.h2_title = None  # has value when in h2 section
+
+    def parse(self, change_note):
+        """Returns True if a line was added to self._add_line was called, False otherwise"""
+        if not self.title:
+            self._in_section = True
+
+        line_added = False
+        change_note = self._process_change_note(change_note)
+
+        if not change_note:
+            return False
+
+        for line in change_note.splitlines():
+            line = self._process_line(line)
+
+            # Look for the starting line of the section
+            if self._is_start_line(line):
+                self._in_section = True
+                self.h2_title = None
+                continue
+
+            # Look for h2
+            if line.startswith("## "):
+                self.h2_title = re.sub(r"\s+#+$", "", line[3:]).lstrip()
+                continue
+
+            # Add all content once in the section
+            if self._in_section:
+
+                # End when the end of section is found
+                if self._is_end_line(line):
+                    self._in_section = False
+                    self.h2_title = None
+                    continue
+
+                # Skip excluded lines
+                if self._is_excluded_line(line):
+                    continue
+
+                self._add_line(line)
+                if self.title:
+                    line_added = True
+
+        self._in_section = False
+        return line_added
+
+    def _process_change_note(self, change_note):
+        # subclasses override this if some manipulation is needed
+        return change_note
+
+    def _process_line(self, line):
+        try:
+            line = str(line, "utf-8")
+        except TypeError:
+            pass
+        return line.rstrip()
+
+    def _is_excluded_line(self, line):
+        if not line:
+            return True
+
+    def _is_start_line(self, line):
+        if self.title:
+            return line.upper() == "# {}".format(self.title.upper())
+
+    def _is_end_line(self, line):
+        # Also treat any new top level heading as end of section
+        if line.startswith("# "):
+            return True
+
+    def _add_line(self, line):
+        line = self._add_link(line)
+        if self.h2_title:
+            if self.h2_title not in self.h2:
+                self.h2[self.h2_title] = []
+            self.h2[self.h2_title].append(line)
+            return
+        self.content.append(line)
+
+    def _add_link(self, line):
+        return line
+
+    def render(self, existing_content=""):
+        if not self.content and not self.h2:
+            return ""
+        content = []
+        content.append(self._render_header())
+        if self.content:
+            content.append(self._render_content())
+        if self.h2:
+            content.append(self._render_h2())
+        return "\r\n".join(content)
+
+    def _render_header(self):
+        return "# {}\r\n".format(self.title)
+
+    def _render_content(self):
+        return "\r\n".join(self.content)
+
+    def _render_h2(self):
+        content = []
+        for h2_title in self.h2.keys():
+            content.append("\r\n## {}\r\n".format(h2_title))
+            content.append("\r\n".join(self.h2[h2_title]))
+        return "\r\n".join(content)
+
+
+class IssuesParser(ChangeNotesLinesParser):
+    def __init__(self, release_notes_generator, title, issue_regex=None):
+        super(IssuesParser, self).__init__(release_notes_generator, title)
+        self.issue_regex = issue_regex or self._get_default_regex()
+
+    def _add_line(self, line):
+        # find issue numbers per line
+        issue_numbers = re.findall(self.issue_regex, line, flags=re.IGNORECASE)
+        for issue_number in issue_numbers:
+            self.content.append(int(issue_number))
+
+    def _get_default_regex(self):
+        return r"#(\d+)"
+
+    def _render_content(self):
+        issues = []
+        for issue in sorted(self.content):
+            issues.append("#{}".format(issue))
+        return "\r\n".join(issues)
+
+
+class InstallLinkParser(ChangeNotesLinesParser):
+    def parse(self, change_note):
+        # There's no need to parse lines, this parser gets its values from task options
+        return False
+
+    def render(self, existing_content=""):
+        version_id = self.release_notes_generator.version_id
+        trial_info = self.release_notes_generator.trial_info
+
+        if (
+            not version_id
+            and not self.release_notes_generator.sandbox_date
+            and not self.release_notes_generator.production_date
+            and not trial_info
+        ):
+            return existing_content
+        result = [self._render_header()]
+        if (
+            self.release_notes_generator.sandbox_date
+            or self.release_notes_generator.production_date
+        ):
+            result.append("## Push Schedule")
+            if self.release_notes_generator.sandbox_date:
+                result.append(
+                    f"Sandbox orgs: {self.release_notes_generator.sandbox_date}"
+                )
+            if self.release_notes_generator.production_date:
+                result.append(
+                    f"Production orgs: {self.release_notes_generator.production_date}",
+                )
+        if version_id:
+            version_id = urllib.parse.quote_plus(version_id)
+            if (
+                self.release_notes_generator.sandbox_date
+                or self.release_notes_generator.production_date
+            ):
+                result.append("")
+            result += [
+                "Sandbox & Scratch Orgs:",
+                f"{SANDBOX_LOGIN_URL}/packaging/installPackage.apexp?p0={version_id}",
+                "",
+                "Production & Developer Edition Orgs:",
+                f"{PROD_LOGIN_URL}/packaging/installPackage.apexp?p0={version_id}",
+            ]
+
+        if trial_info:
+            if (
+                version_id
+                or self.release_notes_generator.sandbox_date
+                or self.release_notes_generator.production_date
+            ):
+                result.append("")
+            result += ["## Trialforce Template ID", f"{trial_info}"]
+        return "\r\n".join(result)
+
+
+# For backwards-compatibility
+import cumulusci.vcs.github.release_notes.parser as githubParser
+from cumulusci.utils.deprecation import warn_moved
+
+
+class GithubLinesParser(githubParser.GithubLinesParser):
+    """Deprecated: use cumulusci.vcs.github.release_notes.parser.GithubLinesParser instead"""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        warn_moved("cumulusci.vcs.github.release_notes.parser", __name__)
+
+
+class GithubIssuesParser(githubParser.GithubIssuesParser):
+    """Deprecated: use cumulusci.vcs.github.release_notes.parser.GithubIssuesParser instead"""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        warn_moved("cumulusci.vcs.github.release_notes.parser", __name__)

cumulusci/tasks/release_notes/provider.py

@@ -0,0 +1,44 @@
+import os
+
+
+class BaseChangeNotesProvider(object):
+    def __init__(self, release_notes_generator):
+        self.release_notes_generator = release_notes_generator
+
+    def __call__(self):
+        """Subclasses should provide an implementation that returns an
+        iterable of each change note"""
+        raise NotImplementedError()
+
+
+class StaticChangeNotesProvider(BaseChangeNotesProvider):
+    def __init__(self, release_notes_generator, change_notes):
+        super(StaticChangeNotesProvider, self).__init__(release_notes_generator)
+        self.change_notes = change_notes
+
+    def __call__(self):
+        for change_note in self.change_notes:
+            yield change_note
+
+
+class DirectoryChangeNotesProvider(BaseChangeNotesProvider):
+    def __init__(self, release_notes_generator, directory):
+        super(DirectoryChangeNotesProvider, self).__init__(release_notes_generator)
+        self.directory = directory
+
+    def __call__(self):
+        for item in sorted(os.listdir(self.directory)):
+            yield open("{}/{}".format(self.directory, item)).read()
+
+
+# For backwards-compatibility
+import cumulusci.vcs.github.release_notes.provider as githubProvider
+from cumulusci.utils.deprecation import warn_moved
+
+
+class GithubChangeNotesProvider(githubProvider.GithubChangeNotesProvider):
+    """Deprecated: use cumulusci.vcs.github.release_notes.provider.GithubChangeNotesProvider instead"""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        warn_moved("cumulusci.vcs.github.release_notes.provider", __name__)