docs: semi automatic changelog (#108)

CHANGELOG.md

@@ -5,22 +5,8 @@ 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).
 
-## [Unreleased]
+## [0.1.0](https://github.com/paradigmxyz/solar/releases/tag/v0.1.0)
 
-### Added
+Initial release.
 
-### Fixed
-
-### Changed
-
-### Removed
-
-## [0.1.0] - 2024-11-05
-
-### Added
-
-- Initial release.
-
-[Unreleased]: https://github.com/paradigmxyz/solar/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/paradigmxyz/solar/releases/tag/v0.1.0
-[#1]: https://github.com/paradigmxyz/solar/issues/1
+<!-- generated by git-cliff -->

README.md

@@ -16,6 +16,10 @@ Blazingly fast, modular and contributor friendly Solidity compiler, written in R
 
 ## Features and Goals
 
+> [!CAUTION]
+> Solar is under active development and is not yet feature complete.
+> Please do not use it in production environments.
+
 - ⚡ Instant compiles and low memory usage
 - 🔍 Expressive and useful diagnostics
 - 🧩 Modular, library-based architecture
@@ -37,8 +41,8 @@ solar = { version = "0.1.0", package = "solar-compiler" }
 
 Or through the CLI:
 
-```console
-$ cargo add solar-compiler --rename solar
+```bash
+cargo add solar-compiler --rename solar
 ```
 
 You can see examples of how to use Solar as a library in the [examples](/examples) directory.
@@ -47,49 +51,51 @@ You can see examples of how to use Solar as a library in the [examples](/example
 
 Pre-built binaries are available for macOS, Linux and Windows on the [releases page](https://github.com/paradigmxyz/solar/releases)
 and can be installed with the following commands:
-
-```console
-# On macOS and Linux.
-curl -LsSf https://paradigm.xyz/solar/install.sh | sh
-
-# On Windows.
-powershell -c "irm https://paradigm.xyz/solar/install.ps1 | iex"
-
-# For a specific version.
-curl -LsSf https://paradigm.xyz/solar/v0.1.0/install.sh | sh
-powershell -c "irm https://paradigm.xyz/solar/v0.1.0/install.ps1 | iex"
-```
+- On macOS and Linux:
+    ```bash
+    curl -LsSf https://paradigm.xyz/solar/install.sh | sh
+    ```
+- On Windows:
+    ```powershell
+    powershell -c "irm https://paradigm.xyz/solar/install.ps1 | iex"
+    ```
+- For a specific version:
+    ```bash
+    curl -LsSf https://paradigm.xyz/solar/v0.1.0/install.sh | sh
+    powershell -c "irm https://paradigm.xyz/solar/v0.1.0/install.ps1 | iex"
+    ```
 
 You can also build Solar from source:
-
-```console
-# From crates.io.
-$ cargo install solar-compiler --locked
-
-# From GitHub.
-$ cargo install --git https://github.com/paradigmxyz/solar --locked
-
-# From a Git checkout.
-$ git clone https://github.com/paradigmxyz/solar
-$ cd solar
-$ cargo install --locked --path crates/solar
-```
+- From crates.io:
+    ```bash
+    cargo install solar-compiler --locked
+    ```
+- From GitHub:
+    ```bash
+    cargo install --git https://github.com/paradigmxyz/solar --locked
+    ```
+- From a Git checkout:
+    ```bash
+    git clone https://github.com/paradigmxyz/solar
+    cd solar
+    cargo install --locked --path crates/solar
+    ```
 
 Once installed, check out the available options:
 
-```console
-$ solar -h
+```bash
+solar -h
 ```
 
 Here's a few examples:
 
-```console
+```bash
 # Compile a single file and emit ABI to stdout.
-$ solar Counter.sol --emit abi
+solar Counter.sol --emit abi
 
 # Compile a contract through standard input (`-` file).
-$ echo "contract C {}" | solar -
-$ solar - <<EOF
+echo "contract C {}" | solar -
+solar - <<EOF
 contract HelloWorld {
     function helloWorld() external pure returns (string memory) {
         return "Hello, World!";
@@ -98,7 +104,7 @@ contract HelloWorld {
 EOF
 
 # Compile a file with a Foundry project's remappings.
-$ solar $(forge re) src/Contract.sol
+solar $(forge re) src/Contract.sol
 ```
 
 ## Roadmap

RELEASE_CHECKLIST.md

@@ -14,8 +14,8 @@ changed or not.
 ## Steps
 
 - [ ] Create a new branch: `git checkout -b release-<version>`
-- [ ] Update CHANGELOG.md with the new version and the changes since the last release.
-- [ ] Run `cargo-release` to handle the version bump and commit: `cargo release --execute --no-publish --no-tag --allow-branch=<branch> <version>`
+- [ ] Run `cargo-release` to handle the version bump, changelog, and commit: `cargo release --execute --no-publish --no-tag --allow-branch=<branch> <version>`
+- [ ] Update changelog message if necessary.
 - [ ] Push, open and merge the PR. The name of the PR should be the same as the `cargo-release` commit message.
 - [ ] `git checkout main` and `git pull`.
 - [ ] Verify `dist plan` is correct.

cliff.toml

@@ -0,0 +1,63 @@
+# Configuration file for [`git-cliff`](https://github.com/orhun/git-cliff)
+# See https://git-cliff.org/docs/configuration
+
+[remote.github]
+owner = "paradigmxyz"
+repo = "solar"
+
+[changelog]
+header = """
+# 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).\n
+"""
+# https://keats.github.io/tera/docs/#introduction
+body = """\
+{% set gh_link = "https://github.com/" ~ remote.github.owner ~ "/" ~ remote.github.repo %}\
+{% if version %}\
+    ## [{{ version | trim_start_matches(pat="v") }}]({{ gh_link }}/releases/tag/v{{ version | trim_start_matches(pat="v") }})
+{% elif previous %}\
+    ## [Unreleased]({{ gh_link }}/compare/{{ previous.version }}...HEAD)
+{% else %}\
+    ## Unreleased
+{% endif %}\
+{% for group, commits in commits | group_by(attribute="group") %}
+    ### {{ group | title }}
+    {% for commit in commits %}
+        - {% if commit.scope %}[{{ commit.scope }}] {% endif %}{{ commit.message | upper_first | split(pat="\\n") | first }}\
+    {% endfor %}
+{% endfor %}\n
+"""
+trim = true
+footer = """
+<!-- generated by git-cliff -->
+"""
+
+[git]
+conventional_commits = true
+filter_unconventional = false
+commit_preprocessors = [
+    { pattern = '#(\d+)', replace = "[#$1](https://github.com/paradigmxyz/solar/issues/$1)" },
+]
+commit_parsers = [
+    { message = "^[Ff]eat", group = "Features" },
+    { message = "^[Ff]ix", group = "Bug Fixes" },
+    { message = "^[Dd]oc", group = "Documentation" },
+    { message = ".*\\b([Dd]eps|[Dd]ependencies|[Bb]ump)\\b", group = "Dependencies" },
+    { message = "^[Pp]erf", group = "Performance" },
+    { message = "^[Rr]efactor", group = "Refactor" },
+    { message = ".*\\b([Ss]tyle|[Ff]mt|[Ff]ormat)\\b", group = "Styling" },
+    { message = "^[Tt]est", group = "Testing" },
+    { message = "^[Cc]hore", group = "Miscellaneous Tasks" },
+
+    { message = ".*", group = "Other" },
+]
+protect_breaking_commits = false
+filter_commits = false
+tag_pattern = "v[0-9]*"
+skip_tags = "v?0\\.1\\.0"
+ignore_tags = "rc"
+sort_commits = "newest"

crates/ast/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 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).
+
+## [0.1.0](https://github.com/paradigmxyz/solar/releases/tag/v0.1.0)
+
+Initial release.
+
+<!-- generated by git-cliff -->

crates/cli/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 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).
+
+## [0.1.0](https://github.com/paradigmxyz/solar/releases/tag/v0.1.0)
+
+Initial release.
+
+<!-- generated by git-cliff -->

crates/config/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 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).
+
+## [0.1.0](https://github.com/paradigmxyz/solar/releases/tag/v0.1.0)
+
+Initial release.
+
+<!-- generated by git-cliff -->

crates/data-structures/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 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).
+
+## [0.1.0](https://github.com/paradigmxyz/solar/releases/tag/v0.1.0)
+
+Initial release.
+
+<!-- generated by git-cliff -->

crates/interface/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 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).
+
+## [0.1.0](https://github.com/paradigmxyz/solar/releases/tag/v0.1.0)
+
+Initial release.
+
+<!-- generated by git-cliff -->

crates/macros/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 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).
+
+## [0.1.0](https://github.com/paradigmxyz/solar/releases/tag/v0.1.0)
+
+Initial release.
+
+<!-- generated by git-cliff -->

crates/parse/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 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).
+
+## [0.1.0](https://github.com/paradigmxyz/solar/releases/tag/v0.1.0)
+
+Initial release.
+
+<!-- generated by git-cliff -->

crates/sema/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 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).
+
+## [0.1.0](https://github.com/paradigmxyz/solar/releases/tag/v0.1.0)
+
+Initial release.
+
+<!-- generated by git-cliff -->

crates/solar/CHANGELOG.md

@@ -0,0 +1,12 @@
+# 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).
+
+## [0.1.0](https://github.com/paradigmxyz/solar/releases/tag/v0.1.0)
+
+Initial release.
+
+<!-- generated by git-cliff -->

crates/solar/src/lib.rs

@@ -6,6 +6,7 @@
 #![cfg_attr(feature = "nightly", feature(rustc_attrs), allow(internal_features))]
 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
 #![allow(unused_crate_dependencies)]
+#![allow(rustdoc::broken_intra_doc_links)] // Ignore GitHub Alerts in included README.md.
 
 #[doc(inline)]
 pub use solar_ast as ast;

release.toml

@@ -7,3 +7,8 @@ sign-tag = true
 shared-version = true
 pre-release-commit-message = "chore: release {{version}}"
 tag-prefix = "" # tag only once instead of per every crate
+pre-release-hook = [
+    "bash",
+    "-c",
+    "$WORKSPACE_ROOT/scripts/changelog.sh --tag {{version}}",
+]

scripts/changelog.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -eo pipefail
+
+run_unless_dry_run() {
+    if [ "$DRY_RUN" = "true" ]; then
+        echo "skipping due to dry run: $*" >&2
+    else
+        "$@"
+    fi
+}
+
+root=$WORKSPACE_ROOT
+crate=$CRATE_ROOT
+crate_glob="${crate#"$root/"}/**"
+
+if [[ "$CRATE_ROOT" != *crates/* ]]; then
+    exit 0
+fi
+
+command=(git cliff --workdir "$root" --config "$root/cliff.toml" --latest "${@}")
+run_unless_dry_run "${command[@]}" --prepend "$root/CHANGELOG.md"
+if [ -n "$crate" ] && [ "$root" != "$crate" ]; then
+    run_unless_dry_run "${command[@]}" --include-path "$crate_glob" --prepend "$crate/CHANGELOG.md"
+fi