Add changelog

Provide a fast and standard way for users to fin out about changes in
System Lambda.

Author: stefanbirkner

CHANGELOG.md

@@ -0,0 +1,84 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+## 1.2.1 – 2021-12-28
+
+Replace `assertThrownBy` with `assertThrows` in documentation.
+
+`assertThrows` is the correct method name of JUnit Jupiter's assertion for
+exceptions. All examples use JUnit Jupiter for assertions.
+
+
+## 1.2.0 – 2021-01-17
+
+Add methods for tapping `System.err` and `System.out` simultaneously.
+
+The output of command-line applications is usually the output to the standard
+output stream and the error output stream intermixed. The new methods allow
+capturing the intermixed output.
+
+    @Test
+    void application_writes_text_to_System_err_and_out(
+    ) throws Exception {
+      String text = tapSystemErrAndOut(() -> {
+        System.err.print("text from err");
+        System.out.print("text from out");
+      });
+      assertEquals("text from errtext from out", text);
+    }
+
+    @Test
+    void application_writes_mutliple_lines_to_System_err_and_out(
+    ) throws Exception {
+      String text = tapSystemErrAndOutNormalized(() -> {
+        System.err.println("text from err");
+        System.out.println("text from out");
+      });
+      assertEquals("text from err\ntext from out\n", text);
+    }
+
+
+## 1.1.1 – 2020-10-12
+
+Fix examples for tapping `System.err` and `System.out`.
+
+
+## 1.1.0 – 2020-08-17
+
+Support Callable for `withEnvironmentVariable`.
+
+This allows to write more precise and readable tests. The assertion can be
+outside the `withEnvironmentVariable` statement and `execute` can be called with
+a one-line Lambda expression. E.g.
+
+    @Test
+    void execute_code_with_environment_variables(
+    ) throws Exception {
+      String value = withEnvironmentVariable("key", "the value")
+        .execute(() -> System.getenv("key"));
+      assertEquals("the value", value);
+    }
+
+
+## 1.0.0 – 2020-05-17
+
+Initial release with the methods
+
+- assertNothingWrittenToSystemErr
+- assertNothingWrittenToSystemOut
+- catchSystemExit
+- muteSystemErr
+- muteSystemOut
+- restoreSystemProperties
+- tapSystemErr
+- tapSystemErrNormalized
+- tapSystemOut
+- tapSystemOutNormalized
+- withEnvironmentVariable
+- withSecurityManager
+- withTextFromSystemIn

README.md

@@ -25,7 +25,8 @@ System Lambda is available from
 ```
 
 Please don't forget to add the scope `test` if you're using System Lambda for
-tests only.
+tests only. The [changelog](CHANGELOG.md) lists all the changes of System
+Lambda.
 
 
 ## Usage
@@ -359,6 +360,11 @@ integration. Each pull request is automatically built by both CI servers.
 GitHub Actions tests with several Java versions (see Enhanced Testing) while
 AppVeyor tests with Java 8 only.
 
+### Project Decisions
+
+There are decision records for some decisions that had been made for System
+Lambda. They are stored in the folder
+[doc/Decision Records](doc/Decision%20Records)
 
 ### Build with Docker
 
@@ -386,8 +392,9 @@ The script uses Docker for running the tests.
 
 * Select a new version according to the
   [Semantic Versioning 2.0.0 Standard](http://semver.org/).
+* Update `Changelog.md`.
 * Set the new version in `pom.xml` and in the `Installation` section of
   this readme.
-* Commit the modified `pom.xml` and `README.md`.
+* Commit the modified `Changelog.md`, `pom.xml` and `README.md`.
 * Run `mvnw clean deploy` with JDK 8.
 * Add a tag for the release: `git tag system-lambda-X.X.X`

doc/Decision Records/1 Changelog.md

@@ -0,0 +1,41 @@
+# Changelog
+
+Status: Accepted
+
+
+## Context
+
+Sometimes I (Stefan) publish a new release of System Lambda.
+
+Users find out about new releases, e.g. because I tweet about it or their
+dependency management tool tells them about a new version. They want to know
+what changed in the new version (or maybe several versions). Some are curious
+about new features or bugfixes. Others need this information in order to decide
+whether they change their software to use a newer version of System Lambda or
+not.
+
+
+## Decision
+
+I provide a changelog that is stored in the file CHANGELOG.md.
+
+A curated list of the changes is the fastest way for users to find out about
+changes in System Lambda.
+
+CHANGELOG.md is a common filename for changelogs. Users who are used to this
+convention may look at this file without further guideline. For other users
+there is a link to the changelog in the readme file.
+
+The file is a text file that uses Markdown, because it provides lightweight text
+formatting that is nicely rendered by some viewers (e.g. GitHub which hosts
+this project) while it still can be viewed and edited by standard text editors.
+
+
+## Consequences
+
+Developers and project stakeholders can see the changes without viewing the git
+log.
+
+The changelog must be updated before a new release is published.
+
+Information may be duplicated between docs, changelog and git log.