hashgraph
Rethink the release notes section in docs
Problem
The release notes section in docs covers the release notes for mirror node services releases. The section contains the history of releases for the last few years. It is unlikely we want to keep the entire history of releases on docs as the release history is kept in the individual GitHub repos for each project.
Solution
Come up with a solution on how we should maintain the release notes section. For example, we keep the last 12 months of releases and discard the rest. Provide the link to the release notes for the project if devs need to go back further than the time we support on docs.
Alternatives
No response
### Tasks
- [ ] https://github.com/hashgraph/hedera-docs/issues/201
Below are a couple of different ways changelogs/release notes are presented:
Twilio Changelog What I think is neat about it:
- I like that they state the why in a short clear sentence.
- They link to docs to better support the change
- If there is a security change, it very briefly outlines the steps to be in compliance & links to docs
Slack Release Notes What I think is neat about it:
- Their release notes generalize the technical details into a brief bullet point that is easy to understand & explains the why.
- It outlines what was a bug fix vs. what was new, which can help a developer if they are experiencing a bug if something was added to fix it. When I often experience issues with a product, I always check their release notes to see if any identified bugs were fixed; sometimes, the issue I was experiencing was fixed in the next release.
Slack Changelog What I think is neat about it:
- It's located under Automation > Extras, which is right after the Getting Started Section.
- Each bullet point is not highly technical but gets the main idea across
- If more information is needed, it links to a documentation page.
Discord Changelog What I think is neat about it
- The changelog is the topic right after Getting Started, making it very visible for developers
- Updates are short and to the point, explaining the reason behind the change
- Key terms are linked to give an opportunity to learn more
- There seems to be a short summary paragraph of all the changes made for that release
- Video Changelog updates are above and beyond(since they take a lot of resources) but are a great way to highlight contributors and dive a little deeper into what these changes mean.
I propose that as an initial step we added a section to the release notes "Release Highlights" where we list the major updates, their functionality, and benefits.
For example:
Release Highlights
HIP 206 Functionality:
- Defines a new function to the Hedera Token Service system contract that allows for the atomic transfer of HBAR, fungible tokens and non-fungible tokens.
- Function cryptoTransfer(TransferList transferList,TokenTransferList[] tokenTransfer)
- Exposes an existing HAPI call via smart contracts.
- Transfer respects granted allowances
Benefits:
- Direct interaction with HBAR and HTS tokens
- Eliminates need for token wrapping
- Enhances efficiency and reduces complexity
- Cuts costs by removing intermediary steps i.e. wrapping assets to interact with them
- Enables native royalty support on the EVM since native HBAR can now be transferred using spending allowances
