Editing Release notes

{{Short description|Document listing software changes}}
{{External links|date=March 2022}}
'''Release notes''' are documents that are distributed with [[software product]]s or hardware products, sometimes when the product is still in the development or test state (e.g., a [[Development stage#Beta|beta]] release).<ref>{{Cite web|title=Change Log Concepts (GNU Coding Standards)|url=https://www.gnu.org/prep/standards/html_node/Change-Log-Concepts.html#Change-Log-Concepts|access-date=2021-04-05|website=www.gnu.org}}</ref><ref>{{Cite web|last=Scott|first=James|date=2020-04-24|title=The art of writing great release notes|url=https://uxdesign.cc/the-art-of-writing-great-release-notes-6607e22efae1|access-date=2021-04-05|website=Medium|language=en}}</ref> For products that have already been in use by clients, the release note is delivered to the customer when an update is released. Another abbreviation for Release notes is ''[[Changelog]]'' or ''Release logs'' or ''Software changes'' or ''Revision history'' ''Updates or README file''.<ref>{{Cite web|title=Releases (GNU Coding Standards)|url=https://www.gnu.org/prep/standards/html_node/Releases.html#index-README-file|access-date=2021-04-05|website=www.gnu.org}}</ref> However, in some cases, the release notes <u>and</u> changelog are published separately. This split is for clarity and differentiation of feature-highlights from bugs, change requests ([[Change request|CRs]]) or improvements on the other side.<ref>{{Cite web|title=Version History - English - Knowledge Base|url=https://kb.i-doit.com/display/en/Version+History|access-date=2021-10-10|website=kb.i-doit.com}}</ref><ref>{{Cite web|title=56508 - Zynq-7000 SoC, 14.6 FSBL - Is there a changelog?|url=https://support.xilinx.com/s/article/56508?language=en_US|website=[[Xilinx]] Support Keyword Search}}</ref>

==Purpose==
Release Notes are documents that are shared with end users, customers and clients of an organization. The definition of the terms 'End Users', 'Clients' and 'Customers' are very relative in nature and might have various interpretations based on the specific context. For instance, the Quality Assurance group within a software development organization can be interpreted as an internal customer.<ref>{{Cite journal|last1=Hobbs|first1=Brian|last2=Besner|first2=Claude|date=2016-05-01|title=Projects with internal vs. external customers: An empirical investigation of variation in practice|journal=International Journal of Project Management|language=en|volume=34|issue=4|pages=675–687|doi=10.1016/j.ijproman.2016.02.010|issn=0263-7863|doi-access=free}}</ref>

== Content ==
Release notes detail the corrections, changes or enhancements ([[Functional requirement|functional]] or [[Non-functional requirement|non-functional]]) made to the service or product the company provides.<ref>{{Cite web|title=Change Logs (GNU Coding Standards)|url=https://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs|access-date=2021-04-05|website=www.gnu.org}}</ref><ref>{{Cite book|last1=Wang|first1=C.|last2=Li|first2=J.|last3=Liang|first3=P.|last4=Daneva|first4=M.|last5=Sinderen|first5=M.|title=2019 IEEE 27th International Requirements Engineering Conference Workshops (REW) |chapter=Developers' Eyes on the Changes of Apps: An Exploratory Study on App Changelogs |date=September 2019|chapter-url=https://ieeexplore.ieee.org/document/8933541|pages=207–212|doi=10.1109/REW.2019.00042|isbn=978-1-7281-5165-6|s2cid=209460408|url=https://research.utwente.nl/en/publications/b34c4559-4a9d-4fbf-8567-3e001f84d8f8 }}</ref><ref>{{Citation|last=Bourne|first=Kelly C.|title=Chapter 10 - Updates and Patches|date=2014-01-01|url=https://www.sciencedirect.com/science/article/pii/B9780123985453000108|work=Application Administrators Handbook|pages=150–165|editor-last=Bourne|editor-first=Kelly C.|place=Boston|publisher=Morgan Kaufmann|language=en|doi=10.1016/b978-0-12-398545-3.00010-8|isbn=978-0-12-398545-3|access-date=2021-03-25|url-access=subscription}}</ref>

They might also be provided as an artifact accompanying the deliverables for [[System testing|System Testing]] and [[System integration testing|System Integration Testing]] and other managed environments especially with reference to an [[information technology]] organization.

Release notes can also contain test results and information about the [[Software testing|test procedure]]. This kind of information gives readers of the release note more confidence in the fix/change done; this information also enables implementer of the change to conduct rudimentary [[Acceptance testing|acceptance tests]].

They differ from [[End-user license agreement]], since they do not (should not) contain any legal terms of the software product or service. The focus should be on the software release itself, not for example legal conditions.<ref>{{Citation|title=release-notes/release-notes-spec|date=2021-03-25|url=https://github.com/release-notes/release-notes-spec|publisher=Release Notes|access-date=2021-03-25}}</ref>

Release notes can also be interpreted as describing how to install or build the software, instead of highlighting new features or resolved bugs.<ref>{{Cite web|title=Linux kernel release 5.x — The Linux Kernel documentation|url=https://www.kernel.org/doc/html/latest/admin-guide/README.html|access-date=2021-03-25|website=www.kernel.org}}</ref> Another term often used in this context is ''System Requirements'', meaning the required hardware and software for installing or building the software.

==Format style==
There is no standard format for release notes that is followed throughout different organizations. Organizations normally adopt their own formatting styles based on the requirement and type of the information to be circulated. The content of release notes also vary according to the release type. For products that are at testing stage and that are newly released, the content is usually more descriptive compared to release notes for bug fixes and feature enhancements, which are usually brief.

Release notes may include the following sections:
* '''Header''' – Document name (i.e. release notes), product name, release number, release date, note date, note version, etc.
* '''Overview''' - A brief overview of the product and changes, in the absence of other formal documentation.
* '''Purpose''' - A brief overview of the purpose of the release note with a listing of what is new in this release, including [[bug fix]]es and new features.
** '''Issue summary''' - A short description of the bug or the enhancement in the release.
** '''[[Steps to reproduce]]''' - The steps that were followed when the bug was encountered.
** '''Resolution''' - A short description of the modification/enhancement that was made to fix the bug.
* '''End-user impact''' - What different actions are needed by the end-users of the application.  This should include whether other functionality is impacted by these changes.
* '''Support impacts''' - Changes required in the daily process of administering the software.
* '''Notes''' - Notes about software or hardware [[Installation (computer programs)|installation]], upgrades and product documentation (including documentation updates)
* '''Disclaimers''' - Company and standard product related messages. e.g.; [[freeware]], [[Copy protection#Anti-piracy|anti-piracy]], duplication etc.. See also [[disclaimer]].
* '''Contact''' - Support contact information.

A release note is usually a terse summary of recent changes, enhancements and bug fixes in a particular software release. It is not a substitute for [[user guide]]s. Release notes are frequently written in the present tense and provide information that is clear, correct, and complete.

A proposal for an open-specification exists and is called Release Notes Schema Specification.<ref>{{Citation|title=release-notes/release-notes-spec|date=2021-03-25|url=https://github.com/release-notes/release-notes-spec|publisher=Release Notes|access-date=2021-03-25}}</ref>

==See also==
{{cmn|colwidth=30em|
* [[Changelog]]
* [[Configuration management]]
* [[End-user license agreement]]
* [[README]]
* [[Release management]]
* [[Release candidate]]
* [[Software release life cycle]]
* [[Software Engineering Body of Knowledge|SWEBOK]]
* [[Terms of service]]
}}

== Further reading ==

* Laura Moreno et al. ''ARENA: An Approach for the Automated Generation of Release Notes'', IEEE Transactions on Software Engineering (Volume: 43, Issue: 2, Feb. 1 2017)<ref>{{Cite journal|last1=Moreno|first1=L.|last2=Bavota|first2=G.|last3=Penta|first3=M. D.|last4=Oliveto|first4=R.|last5=Marcus|first5=A.|last6=Canfora|first6=G.|date=February 2017|title=ARENA: An Approach for the Automated Generation of Release Notes|journal=IEEE Transactions on Software Engineering|volume=43|issue=2|pages=106–127|doi=10.1109/TSE.2016.2591536|issn=1939-3520|doi-access=free}}</ref>
* {{Cite news |last=Newton |first=Casey |author-link=Casey Newton |date=February 10, 2016 |title=I drank beer and wrote release notes with the Medium release notes team |url=https://www.theverge.com/2016/2/10/10938420/medium-release-notes-drinking |access-date=April 5, 2021 |work=[[The Verge]] |publisher=[[Vox Media]]}}
*[[GNU coding standards]] - [https://www.gnu.org/prep/standards/html_node/Change-Logs.html#Change-Logs 6.8 Change Logs]

== References ==
<references />

== External links ==
* [http://blog.davingranroth.com/2010/03/how-to-write-release-notes/ How to write release notes]
* [https://stackoverflow.com/questions/638423/how-should-release-notes-be-written How should release notes be written?] (Stackoverflow)
* [https://spectrum.ieee.org/the-art-of-writing-app-release-notes The Strange Art of Writing App Release Notes]
*[https://github.com/release-notes Release Notes Hub] (also https://www.release-notes.com) ''open-source'' on GitHub
* [https://github.com/release-notes/release-notes-spec Release Notes Schema Specification]

[[Category:Technical communication]]
[[Category:Software release]]
[[Category:Configuration management]]
[[Category:Change management]]