From b5192581ccd35b67fe5a1f795ead9cbcd25956d6 Mon Sep 17 00:00:00 2001 From: Daniel Wong <97631336+daniel-wong-dfinity-org@users.noreply.github.com> Date: Fri, 10 Jan 2025 17:26:42 +0100 Subject: [PATCH] docs(governance): Create changelog files for all of our canisters. (#3388) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Also, moves the description of the process from governance/unreleased_changelog.md to nervous_system/changelog_process.md. Other files point to changelog_process.md. # Future Work In the next PRs in this vein, add support for SNS our tools. In particular, proposal generation, and moving content from unreleased_changelog.md to CHANGELOG.md. # References [👈 Previous PR][prev] [prev]: https://github.com/dfinity/ic/pull/3332 --- rs/nervous_system/changelog_process.md | 59 +++++++++++++++++++ rs/nns/cmc/CHANGELOG.md | 14 +++++ rs/nns/cmc/unreleased_changelog.md | 20 +++++++ rs/nns/governance/CHANGELOG.md | 6 +- rs/nns/governance/unreleased_changelog.md | 32 +--------- rs/nns/gtc/CHANGELOG.md | 14 +++++ rs/nns/gtc/unreleased_changelog.md | 20 +++++++ rs/nns/handlers/lifeline/CHANGELOG.md | 14 +++++ .../handlers/lifeline/unreleased_changelog.md | 20 +++++++ rs/nns/handlers/root/CHANGELOG.md | 14 +++++ rs/nns/handlers/root/unreleased_changelog.md | 20 +++++++ rs/nns/sns-wasm/CHANGELOG.md | 14 +++++ rs/nns/sns-wasm/unreleased_changelog.md | 20 +++++++ rs/registry/CHANGELOG.md | 14 +++++ rs/registry/unreleased_changelog.md | 20 +++++++ rs/sns/governance/CHANGELOG.md | 14 +++++ rs/sns/governance/unreleased_changelog.md | 20 +++++++ rs/sns/root/CHANGELOG.md | 14 +++++ rs/sns/root/unreleased_changelog.md | 20 +++++++ rs/sns/swap/CHANGELOG.md | 14 +++++ rs/sns/swap/unreleased_changelog.md | 20 +++++++ 21 files changed, 371 insertions(+), 32 deletions(-) create mode 100644 rs/nervous_system/changelog_process.md create mode 100644 rs/nns/cmc/CHANGELOG.md create mode 100644 rs/nns/cmc/unreleased_changelog.md create mode 100644 rs/nns/gtc/CHANGELOG.md create mode 100644 rs/nns/gtc/unreleased_changelog.md create mode 100644 rs/nns/handlers/lifeline/CHANGELOG.md create mode 100644 rs/nns/handlers/lifeline/unreleased_changelog.md create mode 100644 rs/nns/handlers/root/CHANGELOG.md create mode 100644 rs/nns/handlers/root/unreleased_changelog.md create mode 100644 rs/nns/sns-wasm/CHANGELOG.md create mode 100644 rs/nns/sns-wasm/unreleased_changelog.md create mode 100644 rs/registry/CHANGELOG.md create mode 100644 rs/registry/unreleased_changelog.md create mode 100644 rs/sns/governance/CHANGELOG.md create mode 100644 rs/sns/governance/unreleased_changelog.md create mode 100644 rs/sns/root/CHANGELOG.md create mode 100644 rs/sns/root/unreleased_changelog.md create mode 100644 rs/sns/swap/CHANGELOG.md create mode 100644 rs/sns/swap/unreleased_changelog.md diff --git a/rs/nervous_system/changelog_process.md b/rs/nervous_system/changelog_process.md new file mode 100644 index 00000000000..e6197217f36 --- /dev/null +++ b/rs/nervous_system/changelog_process.md @@ -0,0 +1,59 @@ +Each canister has a "primary" code directory (e.g. NNS governance's primary code +directory is `rs/nns/governance`). Within that directory, there lives two files: + +1. `unreleased_changelog.md` +2. `CHANGELOG.md` + +The next section describes how these files are maintained. + +# Standard Operating Procedure + +1. When a PR introduces user-visible behavior change in release builds (e.g. the + PR simply consists of `IS_MY_FEATURE_ENABLED = true`), add an entry to the + corresponding `unreleased_changelog.md` file (under the "Next Upgrade + Proposal" heading). This new entry should be added in the **same** PR. There + is a bot that reminds you to do this. + +2. When making an NNS proposal to upgrade this canister (or in the case of SNS, + publish a new WASM), copy entries from `unreleased_changelog.md` to the + proposal's "Features & Fixes" section. This is handled automatically by our + proposal generator scripts. + +3. After the proposal is executed, move the entries from + `unreleased_changelog.md` to its sibling `CHANGELOG.md` file. This can be + done by running + + ```bash + PROPOSAL_ID=??? + + ./testnet/tools/nns-tools/add-release-to-changelog.sh $PROPOSAL_ID + ``` + +If your new code is not active in release builds (because it is behind a feature +flag, or it is simply not called yet), then, do NOT add an entry to +`unreleased_changelog.md`. Instead, wait until your code is actually active in +release builds (e.g. the feature flag is flipped to "enable") before adding an +entry to `unreleased_changelog.md`. + + +# How to Write a Good Entry + +The intended audience of your new entry is people who vote on NNS proposals. In +particular, these people are not necessarily engineers who develop this +canister. In fact, it is best to assume that the reader does not know how to +program at all. (In fact, very many very intelligent people do not know how to +write code!) + +Look at [this example]. Notice how the only Rust code changes in that PR just +sets some `IS_MY_FEATURE_ENABLED` "feature flags" to true. The entry being added +to the `unreleased_changelog.md` file in that same PR describes what the code +behind the flag does, because suddenly, that code is now active in release +builds. + +[this example]: https://github.com/dfinity/ic/pull/3371/files#diff-a0dc71a90ca0ffb3298781894bae5c9dce11c53078ad815c5df1bec4cf0bf625 + + +# The Origin of This Process + +This process is modeled after the process used by nns-dapp. nns-dapp in turn +links to keepachangelog.com as its source of inspiration. diff --git a/rs/nns/cmc/CHANGELOG.md b/rs/nns/cmc/CHANGELOG.md new file mode 100644 index 00000000000..a4306ca17a5 --- /dev/null +++ b/rs/nns/cmc/CHANGELOG.md @@ -0,0 +1,14 @@ +# Changelog + +Proposals before 2025 are NOT listed in here, because this process was +introduced later. (We could back fill those later though.) + +The process that populates this file is described in +`rs/nervous_system/changelog_process.md`. In general though, the entries you see +here were moved from the adjacent `unreleased_changelog.md` file. + + +INSERT NEW RELEASES HERE + + +END diff --git a/rs/nns/cmc/unreleased_changelog.md b/rs/nns/cmc/unreleased_changelog.md new file mode 100644 index 00000000000..94126a0ff42 --- /dev/null +++ b/rs/nns/cmc/unreleased_changelog.md @@ -0,0 +1,20 @@ +# How This File Is Used + +In general, upcoming/unreleased behavior changes are described here. For details +on the process that this file is part of, see +`rs/nervous_system/changelog_process.md`. + + +# Next Upgrade Proposal + +## Added + +## Changed + +## Deprecated + +## Removed + +## Fixed + +## Security diff --git a/rs/nns/governance/CHANGELOG.md b/rs/nns/governance/CHANGELOG.md index 026ed3c923c..a4306ca17a5 100644 --- a/rs/nns/governance/CHANGELOG.md +++ b/rs/nns/governance/CHANGELOG.md @@ -3,9 +3,9 @@ Proposals before 2025 are NOT listed in here, because this process was introduced later. (We could back fill those later though.) -The process that populates this file is described in the adjacent -unreleased_changelog.md file. In general though, the entries you see here were -moved from there. +The process that populates this file is described in +`rs/nervous_system/changelog_process.md`. In general though, the entries you see +here were moved from the adjacent `unreleased_changelog.md` file. INSERT NEW RELEASES HERE diff --git a/rs/nns/governance/unreleased_changelog.md b/rs/nns/governance/unreleased_changelog.md index 90de181cefb..aacc80ecf2c 100644 --- a/rs/nns/governance/unreleased_changelog.md +++ b/rs/nns/governance/unreleased_changelog.md @@ -1,34 +1,8 @@ # How This File Is Used -1. When there is a user-visible behavior change to this canister, add an entry - to this file (in the "Next Upgrade Proposal" section) in the same PR. - -2. When making an NNS proposal to upgrade this canister, copy entries to the - proposal's summary. - -3. After the proposal is executed, move the entries from this file to a new - section in the adjacent CHANGELOG.md file. - -If your new code is not active in release builds (because it is behind a feature -flag, or it is simply not called yet), then do NOT add an entry to this file, -because this new function has no user-visible behavior change yet. Wait until it -is active (e.g. the feature flag is flipped to "enable") before adding an entry -to this file. - - -# How to Write a Good Entry - -The intended audience here is people who vote (with their neurons) in NNS, not -necessarily engineers who develop this canister. - -If there is a motion proposal and/or forum thread where a feature (or bug fix) -was proposed, link to it. - - -# The Origin of This Process - -This process is modeled after the process used by nns-dapp. nns-dapp in turn -links to keepachangelog.com as its source of inspiration. +In general, upcoming/unreleased behavior changes are described here. For details +on the process that this file is part of, see +`rs/nervous_system/changelog_process.md`. # Next Upgrade Proposal diff --git a/rs/nns/gtc/CHANGELOG.md b/rs/nns/gtc/CHANGELOG.md new file mode 100644 index 00000000000..a4306ca17a5 --- /dev/null +++ b/rs/nns/gtc/CHANGELOG.md @@ -0,0 +1,14 @@ +# Changelog + +Proposals before 2025 are NOT listed in here, because this process was +introduced later. (We could back fill those later though.) + +The process that populates this file is described in +`rs/nervous_system/changelog_process.md`. In general though, the entries you see +here were moved from the adjacent `unreleased_changelog.md` file. + + +INSERT NEW RELEASES HERE + + +END diff --git a/rs/nns/gtc/unreleased_changelog.md b/rs/nns/gtc/unreleased_changelog.md new file mode 100644 index 00000000000..94126a0ff42 --- /dev/null +++ b/rs/nns/gtc/unreleased_changelog.md @@ -0,0 +1,20 @@ +# How This File Is Used + +In general, upcoming/unreleased behavior changes are described here. For details +on the process that this file is part of, see +`rs/nervous_system/changelog_process.md`. + + +# Next Upgrade Proposal + +## Added + +## Changed + +## Deprecated + +## Removed + +## Fixed + +## Security diff --git a/rs/nns/handlers/lifeline/CHANGELOG.md b/rs/nns/handlers/lifeline/CHANGELOG.md new file mode 100644 index 00000000000..a4306ca17a5 --- /dev/null +++ b/rs/nns/handlers/lifeline/CHANGELOG.md @@ -0,0 +1,14 @@ +# Changelog + +Proposals before 2025 are NOT listed in here, because this process was +introduced later. (We could back fill those later though.) + +The process that populates this file is described in +`rs/nervous_system/changelog_process.md`. In general though, the entries you see +here were moved from the adjacent `unreleased_changelog.md` file. + + +INSERT NEW RELEASES HERE + + +END diff --git a/rs/nns/handlers/lifeline/unreleased_changelog.md b/rs/nns/handlers/lifeline/unreleased_changelog.md new file mode 100644 index 00000000000..94126a0ff42 --- /dev/null +++ b/rs/nns/handlers/lifeline/unreleased_changelog.md @@ -0,0 +1,20 @@ +# How This File Is Used + +In general, upcoming/unreleased behavior changes are described here. For details +on the process that this file is part of, see +`rs/nervous_system/changelog_process.md`. + + +# Next Upgrade Proposal + +## Added + +## Changed + +## Deprecated + +## Removed + +## Fixed + +## Security diff --git a/rs/nns/handlers/root/CHANGELOG.md b/rs/nns/handlers/root/CHANGELOG.md new file mode 100644 index 00000000000..a4306ca17a5 --- /dev/null +++ b/rs/nns/handlers/root/CHANGELOG.md @@ -0,0 +1,14 @@ +# Changelog + +Proposals before 2025 are NOT listed in here, because this process was +introduced later. (We could back fill those later though.) + +The process that populates this file is described in +`rs/nervous_system/changelog_process.md`. In general though, the entries you see +here were moved from the adjacent `unreleased_changelog.md` file. + + +INSERT NEW RELEASES HERE + + +END diff --git a/rs/nns/handlers/root/unreleased_changelog.md b/rs/nns/handlers/root/unreleased_changelog.md new file mode 100644 index 00000000000..94126a0ff42 --- /dev/null +++ b/rs/nns/handlers/root/unreleased_changelog.md @@ -0,0 +1,20 @@ +# How This File Is Used + +In general, upcoming/unreleased behavior changes are described here. For details +on the process that this file is part of, see +`rs/nervous_system/changelog_process.md`. + + +# Next Upgrade Proposal + +## Added + +## Changed + +## Deprecated + +## Removed + +## Fixed + +## Security diff --git a/rs/nns/sns-wasm/CHANGELOG.md b/rs/nns/sns-wasm/CHANGELOG.md new file mode 100644 index 00000000000..a4306ca17a5 --- /dev/null +++ b/rs/nns/sns-wasm/CHANGELOG.md @@ -0,0 +1,14 @@ +# Changelog + +Proposals before 2025 are NOT listed in here, because this process was +introduced later. (We could back fill those later though.) + +The process that populates this file is described in +`rs/nervous_system/changelog_process.md`. In general though, the entries you see +here were moved from the adjacent `unreleased_changelog.md` file. + + +INSERT NEW RELEASES HERE + + +END diff --git a/rs/nns/sns-wasm/unreleased_changelog.md b/rs/nns/sns-wasm/unreleased_changelog.md new file mode 100644 index 00000000000..94126a0ff42 --- /dev/null +++ b/rs/nns/sns-wasm/unreleased_changelog.md @@ -0,0 +1,20 @@ +# How This File Is Used + +In general, upcoming/unreleased behavior changes are described here. For details +on the process that this file is part of, see +`rs/nervous_system/changelog_process.md`. + + +# Next Upgrade Proposal + +## Added + +## Changed + +## Deprecated + +## Removed + +## Fixed + +## Security diff --git a/rs/registry/CHANGELOG.md b/rs/registry/CHANGELOG.md new file mode 100644 index 00000000000..a4306ca17a5 --- /dev/null +++ b/rs/registry/CHANGELOG.md @@ -0,0 +1,14 @@ +# Changelog + +Proposals before 2025 are NOT listed in here, because this process was +introduced later. (We could back fill those later though.) + +The process that populates this file is described in +`rs/nervous_system/changelog_process.md`. In general though, the entries you see +here were moved from the adjacent `unreleased_changelog.md` file. + + +INSERT NEW RELEASES HERE + + +END diff --git a/rs/registry/unreleased_changelog.md b/rs/registry/unreleased_changelog.md new file mode 100644 index 00000000000..94126a0ff42 --- /dev/null +++ b/rs/registry/unreleased_changelog.md @@ -0,0 +1,20 @@ +# How This File Is Used + +In general, upcoming/unreleased behavior changes are described here. For details +on the process that this file is part of, see +`rs/nervous_system/changelog_process.md`. + + +# Next Upgrade Proposal + +## Added + +## Changed + +## Deprecated + +## Removed + +## Fixed + +## Security diff --git a/rs/sns/governance/CHANGELOG.md b/rs/sns/governance/CHANGELOG.md new file mode 100644 index 00000000000..a4306ca17a5 --- /dev/null +++ b/rs/sns/governance/CHANGELOG.md @@ -0,0 +1,14 @@ +# Changelog + +Proposals before 2025 are NOT listed in here, because this process was +introduced later. (We could back fill those later though.) + +The process that populates this file is described in +`rs/nervous_system/changelog_process.md`. In general though, the entries you see +here were moved from the adjacent `unreleased_changelog.md` file. + + +INSERT NEW RELEASES HERE + + +END diff --git a/rs/sns/governance/unreleased_changelog.md b/rs/sns/governance/unreleased_changelog.md new file mode 100644 index 00000000000..94126a0ff42 --- /dev/null +++ b/rs/sns/governance/unreleased_changelog.md @@ -0,0 +1,20 @@ +# How This File Is Used + +In general, upcoming/unreleased behavior changes are described here. For details +on the process that this file is part of, see +`rs/nervous_system/changelog_process.md`. + + +# Next Upgrade Proposal + +## Added + +## Changed + +## Deprecated + +## Removed + +## Fixed + +## Security diff --git a/rs/sns/root/CHANGELOG.md b/rs/sns/root/CHANGELOG.md new file mode 100644 index 00000000000..a4306ca17a5 --- /dev/null +++ b/rs/sns/root/CHANGELOG.md @@ -0,0 +1,14 @@ +# Changelog + +Proposals before 2025 are NOT listed in here, because this process was +introduced later. (We could back fill those later though.) + +The process that populates this file is described in +`rs/nervous_system/changelog_process.md`. In general though, the entries you see +here were moved from the adjacent `unreleased_changelog.md` file. + + +INSERT NEW RELEASES HERE + + +END diff --git a/rs/sns/root/unreleased_changelog.md b/rs/sns/root/unreleased_changelog.md new file mode 100644 index 00000000000..94126a0ff42 --- /dev/null +++ b/rs/sns/root/unreleased_changelog.md @@ -0,0 +1,20 @@ +# How This File Is Used + +In general, upcoming/unreleased behavior changes are described here. For details +on the process that this file is part of, see +`rs/nervous_system/changelog_process.md`. + + +# Next Upgrade Proposal + +## Added + +## Changed + +## Deprecated + +## Removed + +## Fixed + +## Security diff --git a/rs/sns/swap/CHANGELOG.md b/rs/sns/swap/CHANGELOG.md new file mode 100644 index 00000000000..a4306ca17a5 --- /dev/null +++ b/rs/sns/swap/CHANGELOG.md @@ -0,0 +1,14 @@ +# Changelog + +Proposals before 2025 are NOT listed in here, because this process was +introduced later. (We could back fill those later though.) + +The process that populates this file is described in +`rs/nervous_system/changelog_process.md`. In general though, the entries you see +here were moved from the adjacent `unreleased_changelog.md` file. + + +INSERT NEW RELEASES HERE + + +END diff --git a/rs/sns/swap/unreleased_changelog.md b/rs/sns/swap/unreleased_changelog.md new file mode 100644 index 00000000000..94126a0ff42 --- /dev/null +++ b/rs/sns/swap/unreleased_changelog.md @@ -0,0 +1,20 @@ +# How This File Is Used + +In general, upcoming/unreleased behavior changes are described here. For details +on the process that this file is part of, see +`rs/nervous_system/changelog_process.md`. + + +# Next Upgrade Proposal + +## Added + +## Changed + +## Deprecated + +## Removed + +## Fixed + +## Security