Switch to herald for releasing

Author: carbolymer

.cardano-dev.yaml

@@ -0,0 +1,6 @@
+project: cardano-api
+pr: 1164
+kind:
+  - maintenance
+description: |
+  Switch releasing process to herald

.changes/20260409_cardano_api_herald_template_update.yml

@@ -0,0 +1,6 @@
+project: cardano-rpc
+pr: 1149
+kind:
+  - compatible
+description: |
+  Add lower bound to proto-lens >= 0.7.1.6

.changes/20260409_cardano_rpc_proto_lens_lower_bound.yml

@@ -0,0 +1,6 @@
+project: cardano-rpc
+pr: 1134
+kind:
+  - bugfix
+description: |
+  gRPC: add tip timestamp to ChainPoint response

.changes/20260409_cardano_rpc_tip_timestamp.yml

@@ -0,0 +1,6 @@
+project: cardano-wasm
+pr: 1008
+kind:
+  - feature
+description: |
+  Add implementation for stake certificate creation in `cardano-wasm`

.changes/20260409_cardano_wasm_stake_certificate.yml

@@ -0,0 +1,8 @@
+project: cardano-api
+pr: 1182
+kind:
+  - feature
+  - breaking
+description: |
+  Bump ouroboros-consensus to ^>=3.0 and plutus to ^>=1.61.
+  The golden file changes come from upstream plutus changes to the TokenName Show instance.

.changes/20260413_cardano_api_bump_consensus_plutus.yml

@@ -0,0 +1,9 @@
+project: cardano-api
+pr: 1181
+kind:
+  - breaking
+  - bugfix
+description: |
+  makeUnsignedTx now returns Either MakeUnsignedTxError and errors when
+  Plutus scripts are present but protocol parameters are missing, instead
+  of silently omitting the script integrity hash (script_data_hash).

.changes/20260413_cardano_api_make_unsigned_tx_error.yml

@@ -0,0 +1,31 @@
+# Changelog fragment template - copy this file and fill in the fields.
+# Or use 'herald new' for interactive creation.
+#
+# Files starting with _ are ignored by herald.
+#
+# Available projects and kinds are defined in .herald.yml
+
+# Which project this change belongs to (see 'projects' in .herald.yml)
+# Uncomment exactly one:
+# project: cardano-api
+# project: cardano-api-gen
+# project: cardano-rpc
+# project: cardano-wasm
+
+# Pull request number associated with this change
+pr: 0
+
+# One or more change kinds (see 'kinds' in .herald.yml)
+kind:
+#   - breaking       # the API has changed in a breaking way
+#   - feature        # introduces a new feature
+#   - compatible     # the API has changed but is non-breaking
+#   - bugfix         # fixes a defect
+#   - optimisation   # measurable performance improvements
+#   - documentation  # change in code docs, haddocks
+#   - refactoring    # code quality improvements
+#   - test           # fixes or modifies tests
+#   - maintenance    # not directly related to the code
+#   - release        # related to a new release preparation
+description: |
+  Describe your change here.

.changes/_TEMPLATE.yml

@@ -1,27 +1,16 @@
-# Changelog
-
-```yaml
-- description: |
-    <insert-changelog-description-here>
-# uncomment types applicable to the change:
-  type:
-  # - feature        # introduces a new feature
-  # - breaking       # the API has changed in a breaking way
-  # - compatible     # the API has changed but is non-breaking
-  # - optimisation   # measurable performance improvements
-  # - refactoring    # QoL changes
-  # - bugfix         # fixes a defect
-  # - test           # fixes/modifies tests
-  # - maintenance    # not directly related to the code
-  # - release        # related to a new release preparation
-  # - documentation  # change in code docs, haddocks...
-# uncomment at least one main project this PR is associated with
-  projects:
-  # - cardano-api
-  # - cardano-api-gen
-  # - cardano-rpc
-  # - cardano-wasm
-```
+<!--
+Every PR needs a changelog fragment in `.changes/`.
+Create one from the template at .changes/_TEMPLATE.yml, or use `herald` for interactive creation.
+Run herald with nix: nix run github:input-output-hk/cardano-dev#herald
+
+Interactive:
+  herald new
+
+Non-interactive:
+  herald new -p cardano-api -k bugfix -d "Fix something" --pr 1234
+
+See .herald.yml for full configuration.
+-->
 
 # Context
 
@@ -36,6 +25,7 @@ Highlight important bits of the PR that will make the review faster. If there ar
 - [ ] Commit sequence broadly makes sense and commits have useful messages
 - [ ] New tests are added if needed and existing tests are updated. See [Running tests](https://github.com/input-output-hk/cardano-node-wiki/wiki/Running-tests) for more details
 - [ ] Self-reviewed the diff
+- [ ] Changelog fragment added in `.changes/`
 
 <!--
 ### Note on CI ###

.github/PULL_REQUEST_TEMPLATE.md

@@ -30,3 +30,81 @@ source-repository-package
 ```
 
 These lines are **comments** (ignored by cabal) but are consumed by Nix tooling to fetch the package source. The hash is computed using a different fetch method than the `sha256` in `flake.nix` (which uses `fetchgit`), so the two values will **intentionally differ**. Do **not** flag a mismatch between a `--sha256:` comment in `cabal.project` and the corresponding `sha256` in `flake.nix` as an error.
+
+## Breaking Change Detection (CRITICAL)
+
+When reviewing PRs, you MUST rigorously check for breaking changes and verify they are correctly classified in the changelog fragment (`.changes/*.yml`). This is the single most important aspect of PR review for this project. cardano-api is a foundational library -- downstream consumers (cardano-cli, cardano-node, dApps, tooling) break silently when we get this wrong.
+
+### What constitutes a breaking change
+
+Any of the following in an **exposed module** is a breaking change. Exposed modules are those listed under `exposed-modules:` in the `library` stanza of a `.cabal` file. Changes to `other-modules:` (internal modules) are NOT breaking unless they affect the behaviour of exposed API.
+
+#### Type-level breaks
+- Removing or renaming an exported type, data constructor, type class, or type family
+- Adding a field to a record that uses non-record syntax (positional constructors)
+- Adding a required field to a record constructor (even with named fields)
+- Removing a field from any data constructor
+- Changing the type of an existing field or function argument
+- Changing a type synonym or type family equation
+- Narrowing a type signature (making it less polymorphic) on an exported function
+- Adding a new constraint to an exported function's type signature
+- Changing the kind of a type variable
+- Removing a type class instance that was previously exported
+
+#### Value-level breaks
+- Removing or renaming an exported function or value
+- Changing the number or order of arguments to an exported function
+- Changing default values or smart constructor behaviour in ways that alter semantics
+- Changing the semantics of an exported function (different return value for same input) -- this is a **behavioural** break even if the type signature is unchanged
+
+#### Module-level breaks
+- Removing an exposed module entirely
+- Removing re-exports from an exposed module (e.g. a module that re-exported `Foo(..)` no longer does)
+- Moving a definition from an exposed module to an internal module without re-exporting it
+
+#### Dependency-level breaks
+- Bumping a major version of a dependency that is transitively exposed in the public API (e.g. types from `cardano-ledger-api` appear in cardano-api's signatures)
+- Removing a dependency whose types appear in the public API
+
+#### Things that are NOT breaking
+- Adding new exported functions, types, or modules (this is `feature` or `compatible`)
+- Adding new type class instances (unless orphans that could cause overlap)
+- Adding optional fields with defaults to records using `HasField` / lenses
+- Changes to internal modules (`Cardano.Api.Internal.*`, `other-modules:`) that do not change exposed behaviour
+- Documentation, test, or refactoring changes with no API surface impact
+- Performance improvements with identical semantics
+
+### Verifying the changelog fragment
+
+Every PR must include a `.changes/*.yml` file. When reviewing:
+
+1. **Check the `kind:` field** -- if the PR contains ANY breaking change from the list above, the kind MUST include `breaking`. A PR marked as `feature`, `compatible`, `bugfix`, or anything else that introduces a breaking change is **incorrectly classified** and must be flagged.
+
+2. **Check the `project:` field** -- the project must match whichever package's exposed API changed. The projects are: `cardano-api`, `cardano-api-gen`, `cardano-rpc`, `cardano-wasm`.
+
+3. **Check the `description:`** -- for breaking changes, the description MUST clearly state what broke and what downstream consumers need to do to adapt. Vague descriptions like "update API" are not acceptable for breaking changes.
+
+4. **If no changelog fragment exists**, flag the PR as incomplete. Every PR requires one.
+
+5. **If multiple packages are affected**, there should be separate changelog fragments for each, or a single fragment listing multiple projects.
+
+### How to review for breaking changes
+
+When reviewing a diff:
+
+1. First, identify which files are in exposed modules by cross-referencing with the `exposed-modules:` list in the relevant `.cabal` file.
+2. For each changed exposed module, check every removed or modified line against the breaking change categories above.
+3. Pay special attention to:
+   - Removed exports in module headers (`module Foo (thing1, thing2, ...)`)
+   - Changed type signatures
+   - Modified data type definitions
+   - Removed or renamed pattern synonyms
+   - Changes to re-export modules like `Cardano.Api` (the main entry point re-exports heavily)
+4. If a change touches `Cardano.Api` or `Cardano.Api.Experimental` (the main re-export modules), scrutinize especially carefully -- these are the most widely imported modules.
+
+### Err on the side of caution
+
+When uncertain whether something is breaking:
+- **Flag it as potentially breaking** and ask the author to confirm
+- It is far worse to miss a breaking change than to over-flag one
+- A false positive costs a conversation; a false negative costs every downstream consumer