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:
The overriding design goals for SRN's syntax is:
Once we have the type representations, we can then look at producing the following:
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. +FixObject: Result:
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:
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
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.
John Gruber deserves a tremendous amount of credit for this original work on Markdown, as does Gina Trapani and her work on Todo.txt.
Using the SRN syntax, you can create a list that can be broken along various key axes.
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).
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.
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.
- This is the _first_ *list* item. - This is the **second** __list__ item. - This is the `third` list item. - This is the [forth](?) list item.
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".
# 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.
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.
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.
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".
- 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.
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).
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. +FixResult: 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. +FixResult: 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: