Keep freetext in the beginning of a release. (#16)

Section preamble

Co-authored-by: Malte Vesper <[email protected]>

Author: f3ath

.github/workflows/publish.yml

@@ -0,0 +1,12 @@
+# .github/workflows/publish.yml
+name: Publish to pub.dev
+
+on:
+  push:
+    tags:
+      - '[0-9]+.[0-9]+.[0-9]+*'
+
+# Publish using the reusable workflow from dart-lang.
+jobs:
+  publish:
+    uses: dart-lang/setup-dart/.github/workflows/publish.yml@v1

CHANGELOG.md

@@ -1,6 +1,14 @@
 # Changelog
 This project follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2023-06-11
+### Added
+- keep freetext directly under release headings
+- Support for section preamble
+
+### Changed
+- Min SDK version is 3.0.0
+
 ## [0.6.0] - 2023-02-14
 ### Added
 - You may pass an instance of markdown `Document` to the `parseChangelog()` to have fine-grained control over parsing, e.g. whether to encode HTML entities
@@ -111,6 +119,7 @@ This project follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.
 - Parsing from markdown
 - Writing to markdown
 
+[0.7.0]: https://github.com/f3ath/change/compare/0.6.0...0.7.0
 [0.6.0]: https://github.com/f3ath/change/compare/0.5.0...0.6.0
 [0.5.0]: https://github.com/f3ath/change/compare/0.4.0...0.5.0
 [0.4.0]: https://github.com/f3ath/change/compare/0.3.1...0.4.0
@@ -130,4 +139,4 @@ This project follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.
 [0.0.5]: https://github.com/f3ath/change/compare/0.0.4...0.0.5
 [0.0.4]: https://github.com/f3ath/change/compare/0.0.3...0.0.4
 [0.0.3]: https://github.com/f3ath/change/compare/0.0.2...0.0.3
-[0.0.2]: https://github.com/f3ath/change/compare/0.0.1...0.0.2
+[0.0.2]: https://github.com/f3ath/change/compare/0.0.1...0.0.2

analysis_options.yaml

@@ -1,8 +1,4 @@
 include: package:lints/recommended.yaml
-analyzer:
-  strong-mode:
-    implicit-casts: false
-    implicit-dynamic: false
 linter:
   rules:
     - sort_constructors_first

lib/src/changelog.dart

@@ -7,8 +7,8 @@ class Changelog {
   /// Releases mapped by version
   final _releases = <String, Release>{};
 
-  /// Changelog header which comes on top of the file before the Unreleased
-  /// and version sections.
+  /// Free text which comes on top of the file before the Unreleased section
+  /// and the releases.
   final header = <Node>[];
 
   /// The unreleased changes.

lib/src/parser.dart

@@ -3,6 +3,7 @@ import 'dart:convert';
 import 'package:change/src/change.dart';
 import 'package:change/src/changelog.dart';
 import 'package:change/src/release.dart';
+import 'package:change/src/section.dart';
 import 'package:markdown/markdown.dart';
 import 'package:pub_semver/pub_semver.dart';
 
@@ -24,7 +25,7 @@ Changelog parseChangelog(String markdown, {Document? document}) {
   }
   for (final nodes in sections) {
     if (_isUnreleased(nodes.first)) {
-      _changes(nodes.skip(1)).forEach(log.unreleased.add);
+      _parseInto(log.unreleased, nodes.skip(1));
       log.unreleased.link = doc.linkReferences['unreleased']?.destination ?? '';
     } else {
       final release = _release(nodes);
@@ -64,22 +65,24 @@ Release _release(Iterable<Node> nodes) {
     DateTime.parse(date),
     isYanked: isYanked,
   );
-  _changes(nodes.skip(1)).forEach(release.add);
+  _parseInto(release, nodes.skip(1));
   return release;
 }
 
-List<Change> _changes(Iterable<Node> nodes) {
-  final changes = <Change>[];
+void _parseInto(Section section, Iterable<Node> nodes) {
   var type = 'Changed';
+  var headerFinished = false;
   for (final node in nodes.whereType<Element>()) {
     if (node.tag == 'h3') {
+      headerFinished = true;
       type = node.textContent.trim();
+    } else if (!headerFinished) {
+      section.preamble.add(node);
     } else if (node.tag == 'ul') {
       node.children!
           .whereType<Element>()
           .map((node) => Change(type, node.children!))
-          .forEach(changes.add);
+          .forEach(section.add);
     }
   }
-  return changes;
 }

lib/src/printer.dart

@@ -46,6 +46,7 @@ Iterable<Element> _unreleased(Section section) sync* {
     header.add(_link(sectionLink, [text]));
   }
   yield Element('h2', header);
+  yield* section.preamble;
   yield* _changes(section);
 }
 
@@ -63,6 +64,7 @@ Iterable<Element> _release(Release release) sync* {
     header.add(Text(' [YANKED]'));
   }
   yield Element('h2', header);
+  yield* release.preamble;
   yield* _changes(release);
 }
 

lib/src/section.dart

@@ -1,9 +1,15 @@
 import 'package:change/src/change.dart';
+import 'package:markdown/markdown.dart';
 
 /// A release or the unreleased section
 class Section {
   final _changes = <Change>[];
 
+  /// Free text which precedes the actual list of changes.
+  /// The Keepachangelog standard does not specify this part but we support
+  /// it since there's a demand for it.
+  final preamble = <Element>[];
+
   /// Section link. Usually, the diff
   String link = '';
 
@@ -33,5 +39,6 @@ class Section {
   void clear() {
     _changes.clear();
     link = '';
+    preamble.clear();
   }
 }

pubspec.yaml

@@ -1,15 +1,10 @@
 name: change
-version: 0.6.0
+version: 0.7.0
 description: A Changelog manipulation library. Read/modify/write your CHANGELOG.md. Inspired by keepachangelog.com.
 homepage: "https://github.com/f3ath/change"
 
-cider:
-  link_template:
-    tag: 'https://github.com/f3ath/change/releases/tag/%tag%' # initial release link template
-    diff: 'https://github.com/f3ath/change/compare/%from%...%to%' # subsequent releases link template
-
 environment:
-  sdk: ">=2.19.0 <4.0.0"
+  sdk: '>=3.0.0 <4.0.0'
 
 dependencies:
   markdown: ^7.0.0
@@ -23,3 +18,7 @@ dev_dependencies:
   coverage: ^1.2.0
   check_coverage: ^0.0.4
 
+cider:
+  link_template:
+    tag: 'https://github.com/f3ath/change/releases/tag/%tag%' # initial release link template
+    diff: 'https://github.com/f3ath/change/compare/%from%...%to%' # subsequent releases link template

test/browser_test.dart

@@ -0,0 +1,23 @@
+import 'package:change/change.dart';
+import 'package:markdown/markdown.dart';
+import 'package:pub_semver/pub_semver.dart';
+import 'package:test/test.dart';
+
+void main() {
+  test('Browser compatibility smoke test', () {
+    final c = Changelog();
+    final release =
+        Release(Version.parse('1.0.0'), DateTime.parse('2022-02-22'))
+          ..add(Change('Added', [Text('Some change')]))
+          ..link = 'https://example.com';
+    c.add(release);
+
+    final expected = '## [1.0.0] - 2022-02-22\n'
+        '### Added\n'
+        '- Some change\n'
+        '\n'
+        '[1.0.0]: https://example.com';
+
+    expect(printChangelog(c), equals(expected));
+  }, testOn: 'browser');
+}

test/changelog_test.dart

@@ -67,19 +67,6 @@ void main() {
             throwsFormatException);
       });
     });
-
-    group('Non-standard', () {
-      final file = File('test/md/non_standard.md');
-
-      test('Can be read', () {
-        final log = parseChangelog(file.readAsStringSync());
-        expect(log.unreleased, isNotEmpty);
-        expect(log.history().single.link, isEmpty);
-        expect(log.history().single.version.toString(), '0.0.1-beta+42');
-        expect(log.history().single.changes().single.type, 'Invented');
-        expect(log.unreleased.changes().single.type, 'Added');
-      });
-    });
   });
 
   group('Printing', () {
@@ -92,13 +79,6 @@ void main() {
       });
     });
 
-    test('Non-standard', () {
-      final original = File('test/md/non_standard.md');
-      final saved = File('test/md/non_standard_saved.md');
-      expect(printChangelog(parseChangelog(original.readAsStringSync())),
-          saved.readAsStringSync());
-    });
-
     final step1 = File('test/md/step1.md');
     final step2 = File('test/md/step2.md');
     final step3 = File('test/md/step3.md');
@@ -175,4 +155,23 @@ void main() {
           ].join('\n'));
     });
   });
+
+  group('Non-standard', () {
+    final file = File('test/md/non_standard.md');
+
+    test('Reading', () {
+      final log = parseChangelog(file.readAsStringSync());
+      expect(log.unreleased, isNotEmpty);
+      expect(log.history().single.link, isEmpty);
+      expect(log.history().single.version.toString(), '0.0.1-beta+42');
+      expect(log.history().single.changes().single.type, 'Invented');
+      expect(log.unreleased.changes().single.type, 'Added');
+    });
+
+    test('Writing', () {
+      final saved = File('test/md/non_standard_saved.md');
+      expect(printChangelog(parseChangelog(file.readAsStringSync())),
+          saved.readAsStringSync());
+    });
+  });
 }