Skip to content

Commit 71ee063

Browse files
bowenli86bowenli86
authored
docs: add templates for changelog and release notes (#1381)
**Motivation:** improve our release management and legibility **Modifications:** - add CHANGLOG structure and template - add prefilled CHANGELOG for upcoming 3 releases
1 parent 75b56e3 commit 71ee063

File tree

5 files changed

+164
-51
lines changed

5 files changed

+164
-51
lines changed

‎CHANGELOG/CHANGELOG-1.5.0.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# v1.5.0 Redistribution
2+
3+
**Use this template to draft changelog and submit PR to review by the team**
4+
5+
6+
## Highlights
7+
8+
🚀 New Features – Highlight major new functionality.
9+
- ...
10+
- ...
11+
12+
⛔ Breaking Changes – Call out backward-incompatible changes.
13+
- ...
14+
- ...
15+
16+
📌 Deprecations – Mention features that are being phased out.
17+
- ...
18+
- ...
19+
20+
🛠️ Security Fixes – Specify patched vulnerabilities.
21+
- ...
22+
- ...
23+
24+
🔧 Improvements – Enhancements to existing features.
25+
- ...
26+
- ...
27+
28+
🐛 Bug Fixes – List resolved issues.
29+
- ...
30+
- ...
31+
32+
33+
## Changelog
34+
35+
Copy the one that's auto generated from github by default to here, and submit PR for review
36+
37+
38+
- merged PRs in diff from last release
39+
- contributors
40+
- etc

‎CHANGELOG/CHANGELOG-1.6.0.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# v1.6.0 Moocow and ELIP5
2+
3+
**Use this template to draft changelog and submit PR to review by the team**
4+
5+
6+
## Highlights
7+
8+
🚀 New Features – Highlight major new functionality.
9+
- ...
10+
- ...
11+
12+
⛔ Breaking Changes – Call out backward-incompatible changes.
13+
- ...
14+
- ...
15+
16+
📌 Deprecations – Mention features that are being phased out.
17+
- ...
18+
- ...
19+
20+
🛠️ Security Fixes – Specify patched vulnerabilities.
21+
- ...
22+
- ...
23+
24+
🔧 Improvements – Enhancements to existing features.
25+
- ...
26+
- ...
27+
28+
🐛 Bug Fixes – List resolved issues.
29+
- ...
30+
- ...
31+
32+
33+
## Changelog
34+
35+
Copy the one that's auto generated from github by default to here, and submit PR for review
36+
37+
38+
- merged PRs in diff from last release
39+
- contributors
40+
- etc

‎CHANGELOG/CHANGELOG-1.7.0.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# v1.7.0 Multi Chain
2+
3+
**Use this template to draft changelog and submit PR to review by the team**
4+
5+
6+
## Highlights
7+
8+
🚀 New Features – Highlight major new functionality.
9+
- ...
10+
- ...
11+
12+
⛔ Breaking Changes – Call out backward-incompatible changes.
13+
- ...
14+
- ...
15+
16+
📌 Deprecations – Mention features that are being phased out.
17+
- ...
18+
- ...
19+
20+
🛠️ Security Fixes – Specify patched vulnerabilities.
21+
- ...
22+
- ...
23+
24+
🔧 Improvements – Enhancements to existing features.
25+
- ...
26+
- ...
27+
28+
🐛 Bug Fixes – List resolved issues.
29+
- ...
30+
- ...
31+
32+
33+
## Changelog
34+
35+
Copy the one that's auto generated from github by default to here, and submit PR for review
36+
37+
38+
- merged PRs in diff from last release
39+
- contributors
40+
- etc

‎CHANGELOG/CHANGELOG-template.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# <release-version>
2+
3+
**Use this template to draft changelog and submit PR to review by the team**
4+
5+
6+
## Highlights
7+
8+
🚀 New Features – Highlight major new functionality.
9+
- ...
10+
- ...
11+
12+
⛔ Breaking Changes – Call out backward-incompatible changes.
13+
- ...
14+
- ...
15+
16+
📌 Deprecations – Mention features that are being phased out.
17+
- ...
18+
- ...
19+
20+
🛠️ Security Fixes – Specify patched vulnerabilities.
21+
- ...
22+
- ...
23+
24+
🔧 Improvements – Enhancements to existing features.
25+
- ...
26+
- ...
27+
28+
🐛 Bug Fixes – List resolved issues.
29+
- ...
30+
- ...
31+
32+
33+
## Changelog
34+
35+
Copy the one that's auto generated from github by default to here, and submit PR for review
36+
37+
38+
- merged PRs in diff from last release
39+
- contributors
40+
- etc

‎MAINTENANCE.md

Lines changed: 4 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -173,66 +173,19 @@ So our release branch and model must be flexible enough to solve it via cherry p
173173

174174
### Changelog, Release Note, Release Announcement Blog
175175

176-
Each release in testnet and mainnet must have corresponding release note, changelog, and announcement blog
176+
Each release in testnet and mainnet must have corresponding changelog, release note, and announcement blog
177177

178-
- Changelog
178+
- Changelog and release notes
179179
- lives in the repo `/CHANGELOG` dir
180-
- exact commit history diff from last release
180+
- release note: high level summary of key changes users need to be aware of
181+
- changelog: exact commit history diff from last release
181182
- See examples in Kubernetes https://github.com/kubernetes/kubernetes/tree/master/CHANGELOG
182-
- Release note:
183-
- lives in the repo as part of release description under “[Releases](https://github.com/Layr-Labs/eigenlayer-contracts/releases)”
184-
- high level summary of key changes users need to be aware of
185-
- See template below
186-
- Owner: release manager and PM
187183
- Release announcement blog
188184
- published to [blog.eigenlayer.xyz](http://blog.eigenlayer.xyz)
189185
- an announcement with polished language to introduce the release to users. It will include content in both release notes and changelog
190186
- See examples in Golang https://tip.golang.org/doc/go1.24
191187
- Owner: release manager and PM
192188

193-
Release Note must follow template:
194-
195-
```jsx
196-
<release-version>
197-
198-
🚀 New Features – Highlight major new functionality.
199-
- ...
200-
- ...
201-
202-
⛔ Breaking Changes – Call out backward-incompatible changes.
203-
- ...
204-
- ...
205-
206-
📌 Deprecations – Mention features that are being phased out.
207-
- ...
208-
- ...
209-
210-
🛠️ Security Fixes – Specify patched vulnerabilities.
211-
- ...
212-
- ...
213-
214-
🔧 Improvements – Enhancements to existing features.
215-
- ...
216-
- ...
217-
218-
🐛 Bug Fixes – List resolved issues.
219-
- ...
220-
- ...
221-
```
222-
223-
When writing **release notes** and **changelog entries**, follow these best practices to ensure clarity, usefulness, and professionalism.
224-
225-
**Required Best Practices**
226-
227-
1. **Be Clear and Concise** – Use simple, direct language. Avoid jargon unless necessary.
228-
2. **Categorize Changes** – Use standard sectioned template above.
229-
3. **Provide Context** – Briefly explain why the change was made, not just what changed.
230-
4. **Use a Consistent Format** – Follow a structured template for every release.
231-
5. **Include Relevant Links** – Link to issue trackers, PRs, or documentation for more details.
232-
6. **Highlight User Impact** – Mention how the update affects users and any required actions.
233-
7. **Keep It Versioned** – Use semantic versioning (e.g., `v2.3.1`) and list versions in descending order.
234-
8. **Avoid Internal-Only Details** – Don't include internal project discussions that aren’t relevant to users.
235-
9. **Maintain a Single Source of Truth** – Store changelogs in a `CHANGELOG.md` file or an equivalent documentation system.
236189

237190

238191
## Release Manager Responsibilities

0 commit comments

Comments
 (0)