Semantic Release Notes v 0.3

NOTE: SRN is currently a proposal & requires feedback. To make it better please join in the conversation at our GitHub repository.

Semantic Release Notes (SRN) is a text-to-object-to-html conversion tool for application authors. SRN specifically aims to produce semantic release notes from a Markdown document. This allows authors to write using an easy-to-read, easy-to-write plain text document, convert it to a structured data format (typically JSON or XML) and from this format, convert it into any styled representation (typically html) or to consume the information programatically within 3rd party applications.

Thus, SRN is two things:

  1. a plain text DSL (domain specific language)/syntax for writting release notes; and
  2. a software tool that converts said syntax into JSON/XML and subsequently HTML.
For details pertaining to SRN formatting, see the Syntax section or try it out, right now, using the Live Editor or by extending the provided Examples.

Goals

The overriding design goals for SRN's syntax is:

  • to make it as readable as possible,
  • to support various formats in which release notes are published (Example: NuSpec XML),
  • to make this document parsable by a standard Markdown parser, and
  • to extract semantic release information from the document for further processing.
The idea is that a SRN document should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions. This works well in a Release Notes scenario where plain text documents usually accompany the build. Additional, with the assumptions around the formatting of the release document, SRN can extract semantic meaning from the plain text provided (i.e. the bugs fixed, features, included, release summaries, etc).

Once we have the type representations, we can then look at producing the following:

  • if a user updates through multiple versions of your product, be able to easily generate a consolidated release note which highlights the most important changes,
  • the above would also be true if the user wanted to view the changes that occurred between take 2 different releases - in effect producing a "diff" at the release notes level
  • be able to change the rendered display of the release notes, without changing the format of the original source

Sample

Source:
Incremental release designed to provide an update to some of the core plugins.

# System
 - *Release Checker*: Now gives you a breakdown of exactly what you are missing. +New
 - *Structured Layout*: An alternative layout engine that allows developers to control layout. +New
 
# Plugin
 - *Timeline*: Comes with an additional grid view to show the same data. +Changed
 - *Ajax*: Fix that crashed poll in Chrome and IE due to log/trace statement. +Fix
Object:

                        Result:
                        

Why

With the way that we currently approach producing release notes, we lose any ability to "process" the data. If we change this and produce something that can be, a variety of different possibilities can be realized.

Currently, most projects use either the following approaches:

  1. a single document which lists every release, with the details of each release, or
  2. a document which only shows the details or the latest release, or
  3. a generated document which only shows the details of every release between what they had installed an how have.
These are mostly problematic as they aren't able to isolate which details the user should know about and in most cases, drowns the user in more information than they can/want to take in.

What we should be aiming for, is to help the users find what is the most important information they should know about. If we do this, users are more likely to find the information we as developers want them to know about and be educated as to what items in the release they may care about

Influences

The establishment of the overall syntax and simplicity of the SRN syntax is based on Markdown. As stated, a document based on SRN's syntax should be able to be parsed by a standard Markdown parser. This means that besides making the document human readable, it means that systems that aren't SRN aware but are Markdown aware, can still parse the documents.

The idea of being able to extract semantic meaning from the release notes, isn't established here, rather influences where drawn from the semantic syntax of Todo.txt files. Documents that follow the conventions of the Todo.txt "standard" are able to extract typed information within the TODO domain from the document. The origins on the standard are similar to those of Markdown (a need for human readability), but also a need to be able to define tasks, which are complete, what priority a given task has, etc.

Acknowledgements

John Gruber deserves a tremendous amount of credit for this original work on Markdown, as does Gina Trapani and her work on Todo.txt.

Syntax

The axes of Semantic Release Notes

Using the SRN syntax, you can create a list that can be broken along various key axes.

  • Summary: At its most basic level, SRN should be able to take a paragraph and interpret that as the summary of a given release.
  • Item: A release note should be able to show which "items" are included in a given release. Items typically include features, bug fixes, or improvements. This is indicated via a standard Markdown ordered or unorderded list.
  • Section: Lets the author group items which represent logical sections within the application. These can be arbitrary in nature and specific to the release notes which application is for. This is indicated via a standard Markdown header.
  • Priority: The release note should be able to let you define the importance feature or item that has been defined. This is indicated via a standard Markdown ordered list.
  • Category: Additionally the release note should be able to indicate what category an item is. For instance, "+New", "+Change", "+Bug-Fix", +Developer". This is indicated via a single word, or - (dash) delimited phrase, that has a "+" prefix.
  • Release: As SRN allows for many releases to be defined within the one block of text, the system needs to provide a means by which an individual release can be identified. This is indicated via a standard Markdown header.

Summaries

It is useful to be able to provide summaries various parts of the release. Sections and Releases allow for multi-line multi-paragraph summaries, whilst the summary for an Item is more restrictive, only allowing a single paragraph descriptions.

In each content block, a subset of Markdown is supported - _italic_, **bold**, `code` and [link](uri).

Examples:
This is a _project_ summary with two paragraphs. 
Lorem ipsum dolor sit amet consectetuer **adipiscing** elit. 
Aliquam hendreritmi posuere lectus.

Vestibulum `enim wisi` viverra nec fringilla in laoreet
vitae risus. Donec sit amet nisl. Aliquam [semper](?) ipsum
sit amet velit.

                    

Items

When trying to extract individual items that make up a release, standard lists (ordered or unordered) are used. These lists indicate the items what are a part of the Section or Release they are a part of.

Since the syntax is a subset of Markdown the same list types are supported.

Examples:
 - This is the _first_ *list* item.
 - This is the **second** __list__ item.
 - This is the `third` list item.
 - This is the [forth](?) list item.

                    

Sections

When trying to extract individual items that make up a release, standard lists (ordered or unordered) are used. These lists indicate the items what are a part of the Section or Release they are a part of. These are usually used in larger applications when it's important to isolate out different sections of the application.

Sections are expressed through the use of headings. Also sections can have their own "Summaries" and "Items".

Examples:
# Section
This is the summary for Section.
 - This is a Section scoped first list item.
 - This is a Section scoped second list item.

# Other Section
This is the summary for Other Section.
 - This is a Other Section scoped first list item.
 - This is a Other Section scoped second list item.
                        

                    

Priority

When defining items, the priority of the fix can be expressed via a standard ordered list. Normally we expect ordered lists index to increment sequentially upwards. For our purposes, since the index represents the the priority the values are always going to be 1, 2 or 3 - High, Normal and Minor. This means that when using priorities an index value is likely to be replicated.

Since the syntax is a subset of Markdown the same ordered list types is supported. Note, the index order isn't important.

Example:
 1. This is a High priority list item.
 1. This is a High priority list item. 
 2. This is a Normal priority list item. 
 1. This is a High priority list item. 
 2. This is a Normal priority list item.
 3. This is a Minor priority list item.
 3. This is a Minor priority list item. 
                        

                    

Category

When creating creating items it's useful to be able to assign a Category to an item. Conventional Categories may be established are with special meaning. Examples may include: New, Fix, Changed and Developer (where Developer describes a change that developers would be interested over users).

Markdown doesn't have an exact way of expressing this requirement, hence we use the following notation: "+New" or "+Bug-Fix".

Examples:
 - This is a +New list item.
 - This is a +Fix list item.
 - This is a +Change list item.
 - +New features are everyone's favorites.
 - This is a list item for a +Developer.
 - This is a +Super-Special custom list item.
                        

                    

Release (Not Working)

In some cases we want to have the one document that describes many releases. In this case, the syntax simply allows you to define a heading which is the Version Number. If you use this feature in conjunction with sections, Section headers are also altered.

For the purposes of interpretation of the version number, it is assumed that you are using Semantic Visioning - http://semver.org/. Normal Markdown headers are used to describe the version number for each release and the scope of reach release (which item, etc makes up the release).

Examples: Not yet specified.

Examples

  • Simple example of how a summary can be used in conjunction with release items.

    Source:
    Incremental release designed to provide an update to some of the core plugins.
    
     - Release Checker: Now gives you a breakdown of exactly what you are missing. +New
     - Structured Layout: An alternative layout engine that allows developers to control layout. +New
     - Timeline: Comes with an additional grid view to show the same data. +Changed
     - Ajax: Fix that crashed poll in Chrome and IE due to log/trace statement. +Fix
    Result:
    Object:
    
                                
  • This introduces the concept of sections, along with the items that can be linked with a section.

    Source:
    Incremental release designed to provide an update to some of the core plugins.
    
    # System
     - *Release Checker*: Now gives you a breakdown of exactly what you are missing. +New
     - *Structured Layout*: An alternative layout engine that allows developers to control layout. +New
     
    # Plugin
     - *Timeline*: Comes with an additional grid view to show the same data. +Changed
     - *Ajax*: Fix that crashed poll in Chrome and IE due to log/trace statement. +Fix
    Result:
    Object:
    
                                
  • More complex example that shows how general a general summary and items can be linked to a release, along with a summary and items that can be linked to sections. Also shows how categories can be used.

    Source:
    Incremental release designed to provide an update to some of the core plugins.
     - *Example*: You can have global issues that aren't grouped to a section
    
    # System
    This description is specific to system section.
     - *Release Checker*: Now gives you a +new breakdown of exactly what you are missing.
     - *Structured Layout*: A +new alternative layout engine that allows developers to control layout.
    
    # Plugin
    This description is specific to plugin section.
     - *Timeline*: Comes with an additional grid view to show the same data. +Changed
     - *Ajax*: +Fix that crashed poll in Chrome and IE due to log/trace statement. [[i1234][http://getglimpse.com]]
    Result:
    Object:
    
                                
  • Same as the previous sample, with the addition of priories and icons that can be associated with sections.

    Source:
    Incremental release designed to provide an update to some of the core plugins.
     1. *Example*: You can have global issues that aren't grouped to a section
    
    # System [[icon][http://getglimpse.com/release/icon/core.png]]
    This description is specific to system section.
     3. *Release Checker*: Now gives you a breakdown of exactly what you are missing. +New
     2. *Structured Layout*: An alternative layout engine that allows developers to control layout. +New
    
    # Plugin [[icon][http://getglimpse.com/release/icon/mvc.png]]
    This description is specific to plugin section.
     1. *Timeline*: Comes with an additional grid view to show the same data. +Changed
     1. *Ajax*: Fix that crashed poll in Chrome and IE due to log/trace statement. +Fix [[i1234][http://getglimpse.com]]
    Result:
    Object:
    
                                

Live Editor

Feel free to play around with some samples and see how things are put together.

Result:
Object:

                        

Micro Format

Yet to come.