v0.2.2 (#59)

CHANGELOG.md

@@ -4,6 +4,11 @@ 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.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.2] - 2023-06-11
+### Added
+- The `--only-body` option for the `describe` command.
+- Support for the changelog section preamble, a free text right after the header.
+
 ## [0.2.1] - 2023-06-11
 ### Fixed
 - "Error: No value found at /cider" when run with no configuration in pubspec.yaml
@@ -95,6 +100,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 - Initial version
 
+[0.2.2]: https://github.com/f3ath/cider/compare/0.2.1...0.2.2
 [0.2.1]: https://github.com/f3ath/cider/compare/0.2.0...0.2.1
 [0.2.0]: https://github.com/f3ath/cider/compare/0.1.6...0.2.0
 [0.1.6]: https://github.com/f3ath/cider/compare/0.1.5...0.1.6

README.md

@@ -87,12 +87,16 @@ Cider will automatically generate the diff links in the changelog if the diff li
 Prints the corresponding section from `CHANGELOG.md` in markdown format. This command is read-only.
 
 ```
-cider describe [<version>]
+cider describe [<version>] [options]
 ```
 
 - **version** is an existing version from the changelog. If not specified, the `Unreleased` section will
   be used.
 
+Options:
+
+- `--only-body` will skip the header and the link part of the changelog section.
+
 ### Listing all versions in the changelog
 
 Prints all versions from the changelog, highest to lowest.

lib/src/cli/cider_cli.dart

@@ -5,6 +5,7 @@ import 'package:cider/src/cli/command/bump_command.dart';
 import 'package:cider/src/cli/command/describe_command.dart';
 import 'package:cider/src/cli/command/list_command.dart';
 import 'package:cider/src/cli/command/log_command.dart';
+import 'package:cider/src/cli/command/preamble_command.dart';
 import 'package:cider/src/cli/command/release_command.dart';
 import 'package:cider/src/cli/command/unyank_command.dart';
 import 'package:cider/src/cli/command/version_command.dart';
@@ -20,6 +21,7 @@ class CiderCli extends CommandRunner<int> {
     addCommand(DescribeCommand(console));
     addCommand(ListCommand(console));
     addCommand(LogCommand(console));
+    addCommand(PreambleCommand(console));
     addCommand(ReleaseCommand(console));
     addCommand(UnyankCommand(console));
     addCommand(VersionCommand(console));

lib/src/cli/command/describe_command.dart

@@ -5,10 +5,8 @@ class DescribeCommand extends CiderCommand {
   DescribeCommand(super.printer) {
     argParser.addFlag(onlyBody,
         abbr: 'b',
-        help: 'Print only the section body (no header)',
+        help: 'Print only the section body (no header, no link).',
         defaultsTo: false,
-        hide: true,
-        // TODO: remove when implemented
         negatable: false);
   }
 

lib/src/cli/command/preamble_command.dart

@@ -0,0 +1,18 @@
+import 'package:cider/src/cli/command/cider_command.dart';
+import 'package:cider/src/project.dart';
+
+class PreambleCommand extends CiderCommand {
+  PreambleCommand(super.printer);
+
+  @override
+  final name = 'preamble';
+  @override
+  final description =
+      'Add a new paragraph to the preamble of the "Unreleased" section of the changelog';
+
+  @override
+  Future<int> exec(Project project) async {
+    await project.addPreamble(argResults!.rest.join(' '));
+    return 0;
+  }
+}

lib/src/project.dart

@@ -59,64 +59,80 @@ class Project {
     return next;
   }
 
+  /// Adds a new paragraph to the preamble (the free text right after the header)
+  /// of the `Unreleased` section.
+  Future<void> addPreamble(String text) => _updateChangelog((it) {
+        it.unreleased.preamble
+            .add(Element('p', Document().parseInline(text.trim())));
+      });
+
   /// Adds a new entry to the `Unreleased` section.
   /// Type is one of `a`, `c`, `d`, `f`, `r`, `s`.
-  Future<void> addUnreleased(String type, String description) async {
-    const map = <String, String>{
-      'a': 'Added',
-      'c': 'Changed',
-      'd': 'Deprecated',
-      'f': 'Fixed',
-      'r': 'Removed',
-      's': 'Security',
-    };
-    final typeFull = map[type.substring(0, 1)]!;
-    final log = await _readChangelog();
-    final change = Change(typeFull, Document().parseInline(description));
-    log.unreleased.add(change);
-    if (_config.diffTemplate.isNotEmpty) {
-      final releases = log.history().toList();
-      if (releases.isNotEmpty) {
-        log.unreleased.link =
-            _config.diffTemplate.render(releases.last.version, 'HEAD');
-      }
-    }
-    await _writeChangelog(log);
-  }
+  Future<void> addUnreleased(String type, String description) =>
+      _updateChangelog((log) {
+        const map = <String, String>{
+          'a': 'Added',
+          'c': 'Changed',
+          'd': 'Deprecated',
+          'f': 'Fixed',
+          'r': 'Removed',
+          's': 'Security',
+        };
+        final typeFull = map[type.substring(0, 1)]!;
+        final change = Change(typeFull, Document().parseInline(description));
+        log.unreleased.add(change);
+        if (_config.diffTemplate.isNotEmpty) {
+          final releases = log.history().toList();
+          if (releases.isNotEmpty) {
+            log.unreleased.link =
+                _config.diffTemplate.render(releases.last.version, 'HEAD');
+          }
+        }
+      });
 
   /// Returns a markdown description of the given [version] or the `Unreleased`
   /// section.
   Future<String> describe(String? version, {bool onlyBody = false}) async {
     final log = await _readChangelog();
-    if (version == null) return printUnreleased(log.unreleased);
-    return printRelease(log.get(version));
+    if (version == null) {
+      final section = log.unreleased;
+      if (onlyBody) {
+        return printChanges(section);
+      }
+      return printUnreleased(section);
+    }
+    final section = log.get(version);
+    if (onlyBody) {
+      return printChanges(section);
+    }
+    return printRelease(section);
   }
 
   /// Releases the `Unreleased` section.
   /// Returns the description of the created release.
   Future<String> release(DateTime date, {Version? version}) async {
     version ??= await getVersion();
-    final log = await _readChangelog();
-    final release = Release(version, date);
-    release.addAll(log.unreleased.changes());
-    final parent = log.preceding(release.version);
-    if (parent != null && _config.diffTemplate.isNotEmpty) {
-      release.link = _config.diffTemplate.render(parent.version, version);
-    } else if (_config.tagTemplate.isNotEmpty) {
-      release.link = _config.tagTemplate.render(version);
-    }
-    log.add(release);
-    log.unreleased.clear();
-    await _writeChangelog(log);
-    return describe(release.version.toString());
+    await _updateChangelog((log) {
+      final release = Release(version!, date);
+      release.preamble.addAll(log.unreleased.preamble);
+      release.addAll(log.unreleased.changes());
+      final parent = log.preceding(release.version);
+      if (parent != null && _config.diffTemplate.isNotEmpty) {
+        release.link = _config.diffTemplate.render(parent.version, version);
+      } else if (_config.tagTemplate.isNotEmpty) {
+        release.link = _config.tagTemplate.render(version);
+      }
+      log.add(release);
+      log.unreleased.clear();
+    });
+    return describe(version.toString());
   }
 
   Future<String> setYanked(String version, bool yanked) async {
-    final log = await _readChangelog();
-    final release = log.get(version);
-    release.isYanked = yanked;
-    await _writeChangelog(log);
-    return printRelease(release);
+    await _updateChangelog((log) {
+      log.get(version).isYanked = yanked;
+    });
+    return describe(version);
   }
 
   /// Lists all versions in the changelog.
@@ -128,7 +144,7 @@ class Project {
     final changelog = await _readChangelog();
     final versions = changelog
         .history()
-        .where((r) => !r.isYanked || includeYanked)
+        .where((release) => !release.isYanked || includeYanked)
         .map((release) => release.version.toString())
         .toList()
         .reversed
@@ -144,6 +160,13 @@ class Project {
   Future<void> _writePubspecString(String contents) =>
       _pubspec.writeAsString(contents, flush: true);
 
+  Future<Changelog> _updateChangelog(Function(Changelog changelog) f) async {
+    final changelog = await _readChangelog();
+    f(changelog);
+    await _writeChangelog(changelog);
+    return changelog;
+  }
+
   /// Reads the project changelog
   Future<Changelog> _readChangelog() async {
     if (await _changelog.exists()) {

pubspec.yaml

@@ -1,5 +1,5 @@
 name: cider
-version: 0.2.1
+version: 0.2.2
 description: Tools for Dart package maintainers. Automates changelog and pubspec updates.
 homepage: https://github.com/f3ath/cider
 repository: https://github.com/f3ath/cider
@@ -8,7 +8,7 @@ environment:
   sdk: ">=3.0.0 <4.0.0"
 dependencies:
   args: ^2.0.0
-  change: ^0.6.0
+  change: ^0.7.1
   markdown: ^7.0.0
   path: ^1.6.0
   pub_semver: ^2.0.0

test/functional_test.dart

@@ -88,7 +88,10 @@ void main() {
     expect(out.buffer.toString(), step2);
     await run(['log', 'change', 'New turbo V6 engine installed']);
     await run(['log', 'fix', 'Wheels falling off sporadically']);
+    await run(['preamble', 'I love my dog.']);
     final step3Body = '''
+I love my dog.
+
 ### Changed
 - New turbo V6 engine installed
 
@@ -104,10 +107,9 @@ $step3Body
     await run(['describe']);
     expect(out.buffer.toString(), step3);
 
-    // TODO: implement in 0.2.1
-    // out.buffer.clear();
-    // await run(['describe', '-b']);
-    // expect(out.buffer.toString(), step3Body);
+    out.buffer.clear();
+    await run(['describe', '-b']);
+    expect(out.buffer.toString(), step3Body);
 
     await run(['bump', 'minor']);
 
@@ -119,6 +121,8 @@ $step3Body
     await run(['release', '--date=2021-02-03']);
     final step4 = '''
 ## [1.1.0] - 2021-02-03
+I love my dog.
+
 ### Changed
 - New turbo V6 engine installed
 
@@ -132,6 +136,8 @@ $step3Body
     await run(['yank', '1.1.0']);
     final step5 = '''
 ## [1.1.0] - 2021-02-03 \\[YANKED\\]
+I love my dog.
+
 ### Changed
 - New turbo V6 engine installed