Add CHANGELOG.md (#1010)

* add CHANGELOG.md
* update release instructions
** Add step to consider updating CHANGELOG.md
** Revise ticket auditing to remove suggestion that ticket titles are used in release notes.
* add test of `make_release.py`.

Author: kevinAlbs

CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 3.9.0 [Unreleased]
+
+### Added 
+
+- Add CMake option `USE_DEFAULT_INSTALL_PATH`.
+- Add API to manage Atlas Search Indexes.
+- Automatically download C driver dependency if not provided.
+
+### Changed
+- Do not build tests as part of `all` target. Configure with `BUILD_TESTING=ON` to build tests.

etc/make_release.py

@@ -20,6 +20,7 @@
 Make a release of the C++ Driver, including steps associated with the CXX
 project in Jira, and with the mongodb/mongo-cxx-driver GitHub repository.
 See releasing.md for complete release instructions.
+When editing this file, consider running `test_make_release.py` to validate changes.
 """
 
 # CXX Project ID - 11980
@@ -36,6 +37,7 @@
 # | Task        | 3      |
 # ------------------------
 
+import textwrap
 import re
 from distutils.version import LooseVersion
 import os
@@ -204,7 +206,9 @@ def release(jira_creds_file,
         # all_issues_closed() has already produced an error message
         sys.exit(1)
 
-    release_notes_text = generate_release_notes(issues, release_version)
+    with open ("CHANGELOG.md", "r") as changelog:
+        changelog_contents = changelog.read()
+    release_notes_text = generate_release_notes(release_version, changelog_contents)
 
     gh_repo = auth_gh.get_repo('mongodb/mongo-cxx-driver')
     gh_release_dict = get_github_releases(gh_repo)
@@ -565,28 +569,63 @@ def all_issues_closed(issues):
 
     return True
 
-def generate_release_notes(issues, release_version):
-    """
-    Produce HTML release notes which can be used as part of the project release
-    announcement.
-    """
-
-    release_notes = '<h1>Release Notes - C++ Driver - Version {}</h1>\n'.format(release_version)
-    release_notes += '<h2>Bug</h2>\n'
-    release_notes += '<ul>\n'
-    bug_filter = lambda i: i.fields.issuetype.id == ISSUE_TYPE_ID['Bug']
-    release_notes += print_issues(list(filter(bug_filter, issues)))
-    release_notes += '</ul>\n'
-    release_notes += '<h2>New Feature</h2>\n'
-    release_notes += '<ul>\n'
-    new_feature_filter = lambda i: i.fields.issuetype.id == ISSUE_TYPE_ID['New Feature']
-    release_notes += print_issues(list(filter(new_feature_filter, issues)))
-    release_notes += '</ul>\n'
-    release_notes += '<h2>Improvement</h2>\n'
-    release_notes += '<ul>\n'
-    improvement_filter = lambda i: i.fields.issuetype.id == ISSUE_TYPE_ID['Improvement']
-    release_notes += print_issues(list(filter(improvement_filter, issues)))
-    release_notes += '</ul>\n'
+def generate_release_notes(release_version: str, changelog_contents: str) -> str:
+    lines = []
+    adding_to_lines = False
+    for line in changelog_contents.splitlines(keepends=True):
+        # Check for a version title. Example: `## 3.9.0`.
+        match = re.match(r"^## (.*?)\s(.*)$".format(release_version), line)
+        if match:
+            matched_version = match.group(1)
+            if matched_version == release_version:
+                # Found matching version.
+                extra = match.group(2)
+                if extra != "":
+                    raise click.ClickException(
+                        "Unexpected extra characters in CHANGELOG: {}. Is the CHANGELOG updated?".format(extra))
+                if adding_to_lines:
+                    raise click.ClickException(
+                        "Unexpected second changelog entry matching version: {}: {}".format(release_version), line)
+                # Begin adding lines to `lines` list.
+                adding_to_lines = True
+                continue
+            # End adding lines when another title is seen.
+            else:
+                adding_to_lines = False
+                break
+
+        if adding_to_lines:
+            # Reduce title by one.
+            if line.startswith("#"):
+                lines.append(line[1:])
+            else:
+                lines.append(line)
+
+    # Removing beginning empty lines.
+    while len(lines) > 0 and lines[0] == "\n":
+        lines = lines[1:]
+
+    # Remove trailing empty lines.
+    while len(lines) > 0 and lines[-1] == "\n":
+        lines = lines[0:-1]
+
+    if lines == []:
+        raise click.ClickException(
+            "Failed to find changelog contents for {}".format(release_version))
+
+    footer = textwrap.dedent("""
+    ## Feedback
+    To report a bug or request a feature, please open a ticket in the MongoDB issue management tool Jira:
+
+    - [Create an account](https://jira.mongodb.org) and login.
+    - Navigate to the [CXX project](https://jira.mongodb.org/browse/CXX)
+    - Click `Create`.
+    """).lstrip()
+
+    release_notes = "".join(lines) + "\n"
+    release_notes += "See the [full list of changes in Jira](https://jira.mongodb.org/issues/?jql=project%20%3D%20CXX%20AND%20fixVersion%20%3D%20{}).\n\n".format(
+        release_version)
+    release_notes += footer
 
     return release_notes
 

etc/releasing.md

@@ -44,13 +44,16 @@ changes cherry-picked onto the release branch. This is indicated by a comment on
 the ticket. Here is an
 [example comment](https://jira.mongodb.com/browse/CXX-2650?focusedCommentId=5271981&page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel#comment-5271981).
 
-## Audit Jira ticket titles and types for use in release notes
+## Audit Jira ticket titles and types
 
-From the releases page click the "Release Notes" link to see a summary of
-tickets to be included in release notes. Update the ticket type and title as
-appropriate. User-facing issues should generally be either "Bug" or
-"New Feature". Non-user facing issues should generally be "Task" tickets (and
-will be omitted later, so you can ignore them here).
+Update Jira ticket types and titles as appropriate.
+User-facing issues should generally be either "Bug" or "New Feature".
+Non-user facing issues should generally be "Task" tickets.
+
+## Update CHANGELOG.md
+
+Check Jira for tickets closed in this fix version. Consider updating CHANGELOG.md
+with notable changes not already mentioned.
 
 ## Clone and set up environment
 

etc/test_make_release.py

@@ -0,0 +1,65 @@
+import make_release
+import unittest
+import textwrap
+import click
+
+
+class TestMakeRelease(unittest.TestCase):
+    def test_generate_release_notes(self):
+        # Test can generate.
+        changelog = textwrap.dedent("""
+        # Changelog
+
+        All notable changes to this project will be documented in this file.
+
+        The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+        and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+        ## 3.9.0
+
+        ### Added
+
+        - Add CMake option `USE_DEFAULT_INSTALL_PATH`.
+        - Add API to manage Atlas Search Indexes.
+                                    
+        ## 3.8.0
+
+        ### Fixed
+
+        - Fix foo.
+        """).lstrip()
+        expected_release_notes = textwrap.dedent("""
+        ## Added
+
+        - Add CMake option `USE_DEFAULT_INSTALL_PATH`.
+        - Add API to manage Atlas Search Indexes.
+
+        See the [full list of changes in Jira](https://jira.mongodb.org/issues/?jql=project%20%3D%20CXX%20AND%20fixVersion%20%3D%203.9.0).
+
+        ## Feedback
+        To report a bug or request a feature, please open a ticket in the MongoDB issue management tool Jira:
+
+        - [Create an account](https://jira.mongodb.org) and login.
+        - Navigate to the [CXX project](https://jira.mongodb.org/browse/CXX)
+        - Click `Create`.
+        """).lstrip()
+
+        got = make_release.generate_release_notes("3.9.0", changelog)
+        self.assertEqual(got, expected_release_notes)
+
+        # Test exception occurs if CHANGELOG includes extra characters in title.
+        with self.assertRaises(click.ClickException) as ctx:
+            make_release.generate_release_notes(
+                "3.9.0", "## 3.9.0 [Unreleased]")
+        self.assertIn("Unexpected extra characters",
+                      str(ctx.exception.message))
+
+        # Test exception occurs if CHANGELOG does not include matching entry.
+        with self.assertRaises(click.ClickException) as ctx:
+            make_release.generate_release_notes(
+                "3.9.0", "## 3.8.0")
+        self.assertIn("Failed to find", str(ctx.exception.message))
+
+
+if __name__ == "__main__":
+    unittest.main()