New changelog page. (#3327)

* New changelog page.

* Catching only FormatException

* h2 in documentation

* Return Version instead of String in _extractVersion

Author: isoos

app/lib/frontend/templates/_utils.dart

@@ -12,12 +12,17 @@ import '../../shared/markdown.dart';
 const HtmlEscape htmlAttrEscape = HtmlEscape(HtmlEscapeMode.attribute);
 
 /// Renders a file content (e.g. markdown, dart source file) into HTML.
-String renderFile(FileObject file, String baseUrl) {
+String renderFile(
+  FileObject file,
+  String baseUrl, {
+  bool isChangelog = false,
+}) {
   final filename = file.filename;
   final content = file.text;
   if (content != null) {
     if (_isMarkdownFile(filename)) {
-      return markdownToHtml(content, baseUrl, baseDir: p.dirname(filename));
+      return markdownToHtml(content, baseUrl,
+          baseDir: p.dirname(filename), isChangelog: isChangelog);
     } else if (_isDartFile(filename)) {
       return _renderDartCode(content);
     } else {

app/lib/frontend/templates/package.dart

@@ -16,6 +16,7 @@ import '../../shared/email.dart' show EmailAddress;
 import '../../shared/tags.dart';
 import '../../shared/urls.dart' as urls;
 
+import '../request_context.dart';
 import '../static_files.dart';
 
 import '_cache.dart';
@@ -310,7 +311,8 @@ List<Tab> _pkgTabs(
 
   String renderedChangelog;
   if (selectedVersion.changelog != null) {
-    renderedChangelog = renderFile(selectedVersion.changelog, baseUrl);
+    renderedChangelog = renderFile(selectedVersion.changelog, baseUrl,
+        isChangelog: requestContext.isExperimental);
   }
 
   String renderedExample;

app/lib/shared/markdown.dart

@@ -6,16 +6,26 @@ import 'package:logging/logging.dart';
 import 'package:markdown/markdown.dart' as m;
 import 'package:pana/pana.dart' show getRepositoryUrl;
 import 'package:path/path.dart' as p;
+import 'package:pub_semver/pub_semver.dart';
 import 'package:sanitize_html/sanitize_html.dart';
 
 final Logger _logger = Logger('pub.markdown');
 
 const _whitelistedClassNames = <String>[
+  'changelog-entry',
+  'changelog-version',
+  'changelog-content',
   'hash-header',
   'hash-link',
 ];
 
-String markdownToHtml(String text, String baseUrl, {String baseDir}) {
+/// Renders markdown [text] to HTML.
+String markdownToHtml(
+  String text,
+  String baseUrl, {
+  String baseDir,
+  bool isChangelog = false,
+}) {
   if (text == null) return null;
   final sanitizedBaseUrl = _pruneBaseUrl(baseUrl);
 
@@ -24,7 +34,11 @@ String markdownToHtml(String text, String baseUrl, {String baseDir}) {
       blockSyntaxes: m.ExtensionSet.gitHubWeb.blockSyntaxes);
 
   final lines = text.replaceAll('\r\n', '\n').split('\n');
-  final nodes = document.parseLines(lines);
+  var nodes = document.parseLines(lines);
+
+  if (isChangelog) {
+    nodes = _groupChangelogNodes(nodes).toList();
+  }
 
   final urlRewriter = _RelativeUrlRewriter(sanitizedBaseUrl, baseDir);
   final hashLink = _HashLink();
@@ -63,17 +77,22 @@ class _HashLink implements m.NodeVisitor {
         element.children.length == 1;
 
     if (isHeaderWithHash) {
-      element.attributes['class'] = 'hash-header';
-      element.children.addAll([
-        m.Text(' '),
-        m.Element('a', [m.Text('#')])
-          ..attributes['href'] = '#${element.generatedId}'
-          ..attributes['class'] = 'hash-link',
-      ]);
+      _addHashLink(element, element.generatedId);
     }
   }
 }
 
+void _addHashLink(m.Element element, String id) {
+  final currentClasses = element.attributes['class'] ?? '';
+  element.attributes['class'] = '$currentClasses hash-header'.trim();
+  element.children.addAll([
+    m.Text(' '),
+    m.Element('a', [m.Text('#')])
+      ..attributes['href'] = '#$id'
+      ..attributes['class'] = 'hash-link',
+  ]);
+}
+
 /// Filters unsafe URLs from the generated HTML.
 class _UnsafeUrlFilter implements m.NodeVisitor {
   static const _trustedSchemes = <String>['http', 'https', 'mailto'];
@@ -212,3 +231,67 @@ String _pruneBaseUrl(String url) {
   }
   return null;
 }
+
+/// Group corresponding changelog nodes together, if it matches the following
+/// pattern:
+/// - version identifiers are the only content in a single line
+/// - heading level or other style doesn't matter
+/// - optional `v` prefix is accepted
+/// - message logs between identifiers are copied to the version entry before the line
+///
+/// The output is in the following structure:
+/// <div class="changelog-entry">
+///   <h2 class="changelog-version">{{version - stripped from styles}}</h2>
+///   <div class="changelog-content">
+///     {{log entries in their original HTML format}}
+///   </div>
+/// </div>
+Iterable<m.Node> _groupChangelogNodes(List<m.Node> nodes) sync* {
+  m.Element lastContentDiv;
+  for (final node in nodes) {
+    final version = (node is m.Element &&
+            node.children.isNotEmpty &&
+            node.children.first is m.Text)
+        ? _extractVersion(node.children.first.textContent)
+        : null;
+    if (version != null) {
+      final titleElem = m.Element('h2', [m.Text(version.toString())])
+        ..attributes['class'] = 'changelog-version';
+      final generatedId = (node as m.Element).generatedId;
+      if (generatedId != null) {
+        titleElem.attributes['id'] = generatedId;
+        _addHashLink(titleElem, generatedId);
+      }
+
+      lastContentDiv = m.Element('div', [])
+        ..attributes['class'] = 'changelog-content';
+
+      yield m.Element('div', [
+        titleElem,
+        lastContentDiv,
+      ])
+        ..attributes['class'] = 'changelog-entry';
+    } else if (lastContentDiv != null) {
+      lastContentDiv.children.add(node);
+    } else {
+      yield node;
+    }
+  }
+}
+
+/// Returns the extracted version (if it is a specific version, not `any` or empty).
+Version _extractVersion(String text) {
+  if (text == null || text.isEmpty) return null;
+  text = text.trim();
+  if (text.startsWith('v')) {
+    text = text.substring(1).trim();
+  }
+  if (text.isEmpty) return null;
+  try {
+    final v = Version.parse(text);
+    if (v.isEmpty || v.isAny) return null;
+    return v;
+  } on FormatException catch (_) {
+    return null;
+  }
+}

app/test/shared/markdown_test.dart

@@ -201,4 +201,65 @@ void main() {
           '<p><img src="https://github.com/rcpassos/progress_hud/raw/master/progress_hud.gif" alt="text" /></p>\n');
     });
   });
+
+  group('changelog', () {
+    test('no structure', () {
+      expect(
+          markdownToHtml(
+              'a\n\n'
+              'b\n\n'
+              'c',
+              null,
+              isChangelog: true),
+          '<p>a</p>\n'
+          '<p>b</p>\n'
+          '<p>c</p>\n');
+    });
+
+    test('single entry', () {
+      expect(
+          markdownToHtml(
+              '# Changelog\n\n'
+              '## 1.0.0\n'
+              '\n'
+              '- change1',
+              null,
+              isChangelog: true),
+          '<h1 class="hash-header" id="changelog">Changelog <a href="#changelog" class="hash-link">#</a></h1>'
+          '<div class="changelog-entry">\n'
+          '<h2 class="changelog-version hash-header" id="100">1.0.0 <a href="#100" class="hash-link">#</a></h2>'
+          '<div class="changelog-content">\n'
+          '<ul>\n'
+          '<li>change1</li>\n'
+          '</ul>'
+          '</div>'
+          '</div>\n');
+    });
+
+    test('multiple entries', () {
+      expect(
+          markdownToHtml(
+              '# Changelog\n\n'
+              '## 1.0.0\n\n- change1\n\n- change2\n\n'
+              '## 0.9.0\n\nMostly refatoring',
+              null,
+              isChangelog: true),
+          '<h1 class="hash-header" id="changelog">Changelog <a href="#changelog" class="hash-link">#</a></h1>'
+          '<div class="changelog-entry">\n'
+          '<h2 class="changelog-version hash-header" id="100">1.0.0 <a href="#100" class="hash-link">#</a></h2>'
+          '<div class="changelog-content">\n'
+          '<ul>\n'
+          '<li>\n<p>change1</p>\n</li>\n'
+          '<li>\n<p>change2</p>\n</li>\n'
+          '</ul>'
+          '</div>'
+          '</div>'
+          '<div class="changelog-entry">\n'
+          '<h2 class="changelog-version hash-header" id="090">0.9.0 <a href="#090" class="hash-link">#</a></h2>'
+          '<div class="changelog-content">\n'
+          '<p>Mostly refatoring</p>'
+          '</div>'
+          '</div>\n');
+    });
+  });
 }

pkg/web_css/lib/src/_pkg_experimental.scss

@@ -67,5 +67,24 @@ body.experimental {
   }
 }
 
+.changelog-entry {
+  display: flex;
+  padding: 12px 0;
+  border-bottom: 1px solid #c8c8ca;
+
+  .changelog-version {
+    border-bottom: none;
+    margin: 0;
+    width: 120px;
+  }
+
+  .changelog-content {
+    flex-grow: 1;
+    font-size: 14px;
+    margin: 4px 0 4px 16px;
+    width: 100%;
+  }
+}
+
 /* non-indented rule to restrict the content of the file to the experimental pages */
 }