-
Notifications
You must be signed in to change notification settings - Fork 4
/
index.html
541 lines (502 loc) · 30.5 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
<!doctype html>
<!--[if lt IE 7]> <html class="no-js lt-ie9 lt-ie8 lt-ie7" lang="en"> <![endif]-->
<!--[if IE 7]> <html class="no-js lt-ie9 lt-ie8" lang="en"> <![endif]-->
<!--[if IE 8]> <html class="no-js lt-ie9" lang="en"> <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en"> <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>Semantic Release Notes</title>
<meta name="description" content="">
<meta name="viewport" content="width=device-width">
<link rel="stylesheet" href="css/style.css">
</head>
<body>
<!--[if lt IE 7]><p class=chromeframe>Your browser is <em>ancient!</em> <a href="http://browsehappy.com/">Upgrade to a different browser</a> or <a href="http://www.google.com/chromeframe/?redirect=true">install Google Chrome Frame</a> to experience this site.</p><![endif]-->
<div class="wrapper">
<section class="box box-top">
<h1>Semantic Release Notes <span class="light">v 0.4-beta</span></h1>
</section>
<header>
<div class="header-inner">
<div class="author">
By <strong><a href="https://twitter.com/anthony_vdh">Anthony van der Hoorn</a></strong><br /> & <strong><a href="https://twitter.com/nikmd23">Nik Molnar</a></strong>
</div>
<ul>
<li><a href="#Main">Main</a></li>
<li><a href="#Syntax">Syntax</a></li>
<li><a href="#Examples">Examples</a></li>
<li><a href="#Editor">Live Editor</a></li>
<li><a href="#MicroFormat">Micro Format</a></li>
<li><a href="#Tools">Tools</a></li>
</ul>
</div>
</header>
<section class="box box-main">
<div style="width:95%; margin: auto; background-color: lightyellow; border: 1px solid goldenrod; color: goldenrod; margin: -5px auto 15px; padding: 10px; text-align: center;">
<strong>NOTE:</strong> SRN is currently a proposal & requires feedback. To make it better please join in the conversation at our <a href="https://github.com/Glimpse/Semantic-Release-Notes/issues">GitHub repository</a>.
</div>
<div>
<input name="menu-root-radio" class="menu-root-radio" id="Main" type="radio" checked="checked" />
<a id="Main"></a>
<div class="section-main">
<p>
Semantic Release Notes (SRN) is a text-to-object-to-html conversion tool for application authors. SRN
specifically aims to produce <em>semantic</em> <strong>release notes</strong> 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.
</p>
<p>
Thus, SRN is two things:
<ol>
<li>a plain text DSL (domain specific language)/syntax for writting release notes; and</li>
<li>a software tool that converts said syntax into JSON/XML and subsequently HTML.</li>
</ol>
For details pertaining to SRN formatting, see the <a href="#Syntax">Syntax</a> section or
try it out, right now, using the <a href="#Editor">Live Editor</a> or by extending the provided <a href="#Examples">
Examples</a>.
</p>
<h3>Goals</h3>
<p>
The overriding design goals for SRN's syntax is:
<ul>
<li>to make it as <strong>readable as possible</strong>,</li>
<li>to <strong>support various formats</strong> in which release notes are published (Example: <a href="http://docs.nuget.org/docs/reference/nuspec-reference">NuSpec XML</a>),</li>
<li>to make this document <strong>parsable by a standard Markdown parser</strong>, and</li>
<li>to <strong>extract semantic release information</strong> from the document for further processing.</li>
</ul>
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 <strong>extract semantic meaning</strong>
from the plain text provided (i.e. the bugs fixed, features, included, release summaries, etc).
</p>
<p>
Once we have the type representations, we can then look at producing the following:
<ul>
<li>
if a user <strong>updates through multiple versions</strong> of your product, be able to easily <strong>generate
a consolidated release note</strong> which highlights the most important changes,
</li>
<li>
the above would also be true if the <i>user</i> wanted to view the <strong>changes that occurred
between take 2 different releases</strong> - in effect producing a "diff" at the release notes level
</li>
<li>
be able to <strong>change the rendered display of the release notes</strong>, without changing the format of the
original source
</li>
</ul>
</p>
<h3>Sample</h3>
<div class="container">
<strong>Source:</strong>
<pre class="code">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</pre>
<strong>Object:</strong>
<pre class="object"></pre>
<strong>Result:</strong>
<div class="result"></div>
</div>
<h3>Why</h3>
<p>
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.
</p>
<p>
Currently, most projects use either the following approaches:
<ol>
<li>a single document which lists every release, with the details of each release, or</li>
<li>a document which only shows the details or the latest release, or</li>
<li>a generated document which only shows the details of every release between what they had installed an how have.</li>
</ol>
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.
</p>
<p>
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
</p>
<h3>Influences</h3>
<p>
The establishment of the overall syntax and simplicity of the SRN syntax is based on <strong>Markdown</strong>.
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.
</p>
<p>
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 <strong>Todo.txt</strong> 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.
</p>
<h3>Acknowledgements</h3>
<p>
<a href="http://daringfireball.net">John Gruber</a> deserves a tremendous amount of credit
for this original work on <a href="http://daringfireball.net/projects/markdown/">Markdown</a>, as does
<a href="http://ginatrapani.org/">Gina Trapani</a> and her work on <a href="http://todotxt.com/">Todo.txt</a>.
</p>
</div>
</div>
<div>
<input name="menu-root-radio" class="menu-root-radio" id="Syntax" type="radio" />
<div class="section-basics">
<a id="Syntax"></a>
<h2>Syntax</h2>
<h3>The axes of Semantic Release Notes </h3>
<p>
Using the SRN syntax, you can create a list that can be broken along various key axes.
<ul>
<li>
<strong>Summary</strong>:
At its most basic level, SRN should be able to take a paragraph and interpret that as the summary
of a given release.
</li>
<li>
<strong>Item</strong>:
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 <em>ordered</em> or <em>unorderded</em> list.
</li>
<li>
<strong>Section</strong>:
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 <em>header</em>.
</li>
<li>
<strong>Priority</strong>:
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 <em>ordered list</em>.
</li>
<li>
<strong>Category</strong>:
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.
</li>
<li>
<strong>Release</strong>:
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 <em>header</em>.
</li>
</ul>
</p>
<h3>Summaries</h3>
<p>
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.
</p>
<p>
In each content block, a subset of Markdown is supported - _italic_, **bold**, `code` and [link](uri).
</p>
<div class="container">
<strong>Examples:</strong>
<pre class="code">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.</pre>
<div class="result"></div>
<pre class="object"></pre>
</div>
<h3>Items</h3>
<p>
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.
</p>
<p>
Since the syntax is a subset of Markdown the same list types are supported.
</p>
<div class="container">
<strong>Examples:</strong>
<pre class="code"> - This is the _first_ *list* item.
- This is the **second** __list__ item.
- This is the `third` list item.
- This is the [forth](?) list item.</pre>
<div class="result"></div>
<pre class="object"></pre>
</div>
<h3>Sections</h3>
<p>
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.
</p>
<p>
Sections are expressed through the use of headings. Also sections can have their own "Summaries" and "Items".
</p>
<div class="container">
<strong>Examples:</strong>
<pre class="code"># 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.
</pre>
<div class="result"></div>
<pre class="object"></pre>
</div>
<h3>Priority</h3>
<p>
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.
</p>
<p>
Since the syntax is a subset of Markdown the same ordered list types is supported. Note, the
index order isn't important.
</p>
<div class="container">
<strong>Example:</strong>
<pre class="code"> 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.
</pre>
<div class="result"></div>
<pre class="object"></pre>
</div>
<h3>Category</h3>
<p>
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).
</p>
<p>
Markdown doesn't have an exact way of expressing this requirement, hence we use the following notation: "+New" or "+Bug-Fix".
</p>
<div class="container">
<strong>Examples:</strong>
<pre class="code"> - 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.
- This is my last +DEVELOPER list item. +New
</pre>
<div class="result"></div>
<pre class="object"></pre>
</div>
<h3>Release (Not Working)</h3>
<p>
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.
</p>
<p>
For the purposes of interpretation of the version number, it is assumed that you are using
Semantic Visioning - <a href="http://semver.org/">http://semver.org/</a>. 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).
</p>
<div class="container">
<strong>Examples:</strong>
Not yet specified.
<!--
<pre class="code"># 1.1
This is the release summary for 1.1
# 1.2
This is the release summary for 1.2
# 2.0
This is the release summary for 2.0
</pre>
<div class="result"></div>
<pre class="object"></pre>
-->
</div><!--
<div class="container">
<strong>Examples:</strong>
Not yet specified.
<pre class="code"># 1.1
This is the release summary for 1.1
## Section
This is the summary for Section for 1.1.
## Other Section
This is the summary for Other Section for 1.1.
# 1.2
This is the release summary for 1.2
## Section
This is the summary for Section for 1.2.
# 2.0
This is the release summary for 2.0
## Section
This is the summary for Section for 2.0.
## Other Section
This is the summary for Other Section for 2.0.
</pre>
<div class="result"></div>
<pre class="object"></pre>
</div>-->
</div>
</div>
<div>
<input name="menu-root-radio" class="menu-root-radio" id="Examples" type="radio" />
<div class="section-syntax">
<a id="Exmaples"></a>
<h2>Examples</h2>
<div class="section-editor">
<ul class="tabs">
<li><a class="active" data-tab="1">Example A</a></li>
<li><a data-tab="2">Example B</a></li>
<li><a data-tab="3">Example C</a></li>
<li><a data-tab="4">Example D</a></li>
</ul>
<ul class="tabs-content example">
<li class="active container" data-tab="1">
<p>Simple example of how a summary can be used in conjunction with release items.</p>
<strong>Source:</strong>
<pre class="code">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</pre>
<strong>Result:</strong>
<div class="result"></div>
<strong>Object:</strong>
<pre class="object"></pre>
</li>
<li class="container" data-tab="2">
<p>This introduces the concept of sections, along with the items that can be linked with a section.</p>
<strong>Source:</strong>
<pre class="code">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</pre>
<strong>Result:</strong>
<div class="result"></div>
<strong>Object:</strong>
<pre class="object"></pre>
</li>
<li class="container" data-tab="3">
<p>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.</p>
<strong>Source:</strong>
<pre class="code">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]]</pre>
<strong>Result:</strong>
<div class="result"></div>
<strong>Object:</strong>
<pre class="object"></pre>
</li>
<li class="container" data-tab="4">
<p>Same as the previous sample, with the addition of priories and icons that can
be associated with sections.</p>
<strong>Source:</strong>
<pre class="code">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]]</pre>
<strong>Result:</strong>
<div class="result"></div>
<strong>Object:</strong>
<pre class="object"></pre>
</li>
</ul>
</div>
</div>
</div>
<div>
<input name="menu-root-radio" class="menu-root-radio" id="Editor" type="radio" />
<div class="section-editor">
<a id="Editor"></a>
<h2>Live Editor</h2>
<div class="section-editor">
<p>Feel free to play around with some samples and see how things are put together.</p>
<textarea class="editor" style="height:180px;">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</textarea>
<div class="center">
<button class="execute">Parse!</button>
</div>
<div class="result-container">
<strong>Result:</strong>
<div class="result"></div>
<strong>Object:</strong>
<pre class="object"></pre>
</div>
</div>
</div>
</div>
<div>
<input name="menu-root-radio" class="menu-root-radio" id="MicroFormat" type="radio" />
<div class="section-micro-format">
<a id="MicroFormat"></a>
<h2>Micro Format</h2>
Yet to come.
</div>
</div>
<div>
<input name="menu-root-radio" class="menu-root-radio" id="Tools" type="radio" />
<div class="section-tools">
<a id="Tools"></a>
<h2>Tools</h2>
Here are a list of tools based on Semantic Release Notes:
<ul>
<li><a href="https://github.com/jakeginnivan/gitreleasenotes">Git Release Notes</a> by Jake Ginnivan<br/>
Utility which makes it really easy to generate semantic release notes for your Git project. Works with GitHub, Jira and YouTrack.</li>
<li><a href="https://github.com/laedit/SemanticReleaseNotesParser">Semantic Release Notes Parser</a> by Jérémie Bertrand<br/>
C# parser / formatter of Semantic Release Notes, can be used to parse a semantic release notes and to format it to a markdown or html file or environment variable, for use on build sever.</li>
</ul>
</div>
</div>
</section>
<footer>
<div class="footer-inner">
Copyright © 2013<br /> Anthony van der Hoorn & Nik Molnar
</div>
</footer>
</div>
<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"></script>
<script>window.jQuery || document.write('<script src="js/libs/jquery-1.7.1.min.js"><\/script>')</script>
<script src="js/script.js"></script>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-26457179-3']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</body>
</html>