Skip to content

Commit

Permalink
docs(governance): Create changelog files for all of our canisters. (#…
Browse files Browse the repository at this point in the history
…3388)

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]: #3332
  • Loading branch information
daniel-wong-dfinity-org authored Jan 10, 2025
1 parent 69981dc commit b519258
Show file tree
Hide file tree
Showing 21 changed files with 371 additions and 32 deletions.
59 changes: 59 additions & 0 deletions rs/nervous_system/changelog_process.md
Original file line number Diff line number Diff line change
@@ -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.
14 changes: 14 additions & 0 deletions rs/nns/cmc/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
20 changes: 20 additions & 0 deletions rs/nns/cmc/unreleased_changelog.md
Original file line number Diff line number Diff line change
@@ -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
6 changes: 3 additions & 3 deletions rs/nns/governance/CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
32 changes: 3 additions & 29 deletions rs/nns/governance/unreleased_changelog.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
14 changes: 14 additions & 0 deletions rs/nns/gtc/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
20 changes: 20 additions & 0 deletions rs/nns/gtc/unreleased_changelog.md
Original file line number Diff line number Diff line change
@@ -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
14 changes: 14 additions & 0 deletions rs/nns/handlers/lifeline/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
20 changes: 20 additions & 0 deletions rs/nns/handlers/lifeline/unreleased_changelog.md
Original file line number Diff line number Diff line change
@@ -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
14 changes: 14 additions & 0 deletions rs/nns/handlers/root/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
20 changes: 20 additions & 0 deletions rs/nns/handlers/root/unreleased_changelog.md
Original file line number Diff line number Diff line change
@@ -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
14 changes: 14 additions & 0 deletions rs/nns/sns-wasm/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
20 changes: 20 additions & 0 deletions rs/nns/sns-wasm/unreleased_changelog.md
Original file line number Diff line number Diff line change
@@ -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
14 changes: 14 additions & 0 deletions rs/registry/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
20 changes: 20 additions & 0 deletions rs/registry/unreleased_changelog.md
Original file line number Diff line number Diff line change
@@ -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
14 changes: 14 additions & 0 deletions rs/sns/governance/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
20 changes: 20 additions & 0 deletions rs/sns/governance/unreleased_changelog.md
Original file line number Diff line number Diff line change
@@ -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
14 changes: 14 additions & 0 deletions rs/sns/root/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
20 changes: 20 additions & 0 deletions rs/sns/root/unreleased_changelog.md
Original file line number Diff line number Diff line change
@@ -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
Loading

0 comments on commit b519258

Please sign in to comment.