Google Git
Sign in
eclipse / gerrit / www.eclipse.org / n4js / 6a7ee297bcf9c98d211c00ddb3fd8c04692d2498 / . / releases / reporting-bugs.html
blob: d90f671ce33439ebe6b08f53f6e7095e4b8f3734 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<!--[if IE]><meta http-equiv="X-UA-Compatible" content="IE=edge"><![endif]-->
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="generator" content="Asciidoctor 1.5.7.1">
<title>Reporting Bugs</title>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
<!-- ************* Meta ************* -->
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1" />
<!-- ************* OpenGraph ************-->
<meta name="description" content="The Eclipse N4JS language and its IDE enable high-quality JavaScript development for large Node.js projects.">
<meta property="og:site_name" content="Eclipse N4JS"/>
<meta property="og:title" content="Eclipse N4JS Language and IDE"/>
<meta property="og:url" content="https://numberfour.github.io/n4js"/>
<meta property="og:description" content="The Eclipse N4JS language and its IDE enable high-quality JavaScript development for large Node.js projects."/>
<meta property="og:image" content="../images/n4js.png">
<!-- ************* Favicon ************-->
<link rel="icon" href="../images/favicon.ico" />
<link rel="icon" type="image/png" href="../images/favicon-32x32.png" sizes="32x32" />
<link rel="icon" type="image/png" href="../images/favicon-16x16.png" sizes="16x16" />
<!-- ************* Back-to-top JQuery ************* -->
<script src="https://code.jquery.com/jquery-1.12.4.js"></script>
<script src="https://code.jquery.com/ui/1.12.0/jquery-ui.js"></script>
<!-- ************* Prism.js Syntax Highlighter ******-->
<link href="../styles/prism.min.css" rel="stylesheet"/>
<script src="../scripts/prism.js"></script>
<!-- ************* Styles ************* -->
<link rel="stylesheet" type="text/css" href="../styles/n4js-adoc.css">
<!-- ****************** NavBar ****************** -->
<div id="menubar">
<div class="banner">
<a href="../index.html"><img id="logo" src="../images/n4js-logo.png" alt="N4JS Language and IDE"></a>
</div>
<ul>
<li><a href="../downloads.html"></i>Download</a></li>
<li><a href="../community.html"></i>Community</a></li>
<li><a href="../userguides/index.html">Documentation</a></li>
</ul>
</div>
<button id="tocbutton">TOC</button>
</head>
<body class="book">
<div id="header">
</div>
<div id="content">
<h1 id="_reporting_bugs" class="sect0"><a class="link" href="#_reporting_bugs">Reporting Bugs</a></h1>
<div class="openblock partintro">
<div class="content">
<div class="paragraph">
<div class="title">Reporting Bugs</div>
<p><strong>We embrace bug reports and feature requests!</strong></p>
</div>
<div class="paragraph">
<p>For the moment, we use <a href="https://github.com/eclipse/n4js/issues">GitHub issues</a> to manage
issues found by users. We will soon migrate our current, internal list of bugs there. We greatly appreciate
all bug reports, thank you so much for your time!</p>
</div>
<div class="paragraph">
<p>If you like, you can try out a novel test technology called <a href="http://www.xpect-tests.org/">Xpect</a>
that was designed for writing tests for domain-specific languages and that we have integrated into the N4JS
IDE. It is described in detail in the coming section.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_write_bug_reports_with_xpect"><a class="link" href="#_write_bug_reports_with_xpect">Write Bug Reports with Xpect</a></h2>
<div class="sectionbody">
<div class="paragraph">
<p>With Xpect you can write concise bug reports and feature requests using N4JS and comments. What is a bug? A
bug usually is a programming error that leads to unexpected behavior. What is a feature? A feature is a
functionality provided by a system with a well-defined, i.e. expected, behavior. In other words: Bug
reports and feature requests both have to describe the <strong>expected</strong> behavior. Instead of long explanations
separated from the code, it is often easier to just add this <strong>expectations</strong> to the code.</p>
</div>
<div class="paragraph">
<p>The following screenshot shows a typical feature request (on the left hand side), written with Xpect:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/xpect_feature_request.png" alt="xpect feature request">
</div>
</div>
<div class="paragraph">
<p>The great thing about Xpect is that it actually defines a test. That is the feature request (or bug report)
can be executed. This is even possible within the N4JS IDE, and the result is shown on the right hand side
of the screenshot above. In order to do that, all you have to do is</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Create a new file with extension <code>n4js.xt</code> (".xt" will activate Xpect)</p>
</li>
<li>
<p>Write the bug report or feature request, using comments and the keyword <code>XPECT</code> together with a known
xpectation type (see below)</p>
</li>
<li>
<p>Run the Xpect test from the context menu <strong><span class="menuseq"><b class="menu">Run As</b>&#160;<i class="fa fa-angle-right caret"></i> <b class="menuitem">Xpect run</b></span></strong>.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p><strong>Instead of writing long explanations, just file the <code>n4js.xt</code> file as bug report (and a short explanation)!</strong></p>
</div>
<div class="paragraph">
<p>Note that in the screenshot the file does not contain any error markers - your expectation is already taken
into account during validations, improving the readability of the bug report. As shown in the screenshot above,
the Xpect test failed! In order to make things easier for the developer fixing the bug, you can add an additional
keyword <code>FIXME</code> to expectations you have but which are not fulfilled. In particular in longer reports with several
expectations, it is very helpful to easily identify what is expected and what is correct behavior. When running the
test again with the <code>FIXME</code> annotation, it will succeed as shown in the following screenshot:</p>
</div>
<div class="imageblock">
<div class="content">
<img src="images/xpect_fixme.png" alt="xpect fixme">
</div>
</div>
<div class="paragraph">
<p><strong>Bug reporting will be improved in future releases!</strong></p>
</div>
<div class="paragraph">
<p>In future releases, we will improve the Xpect support and simplify writing bug reports. In particular, we will
provide content assist or wizards for adding certain types of expectations.</p>
</div>
<div class="paragraph">
<p>In general, expectations are written inside comments preceding the line in the code which demonstrates the
un-)expected behavior, according to the following pattern:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>«expectation» at «location»</code></pre>
</div>
</div>
<div class="ulist">
<ul>
<li>
<p><strong>remark</strong>: optional and can be omitted.</p>
</li>
<li>
<p><strong>type:</strong> The type of the expectation is one of the types described in the table below.</p>
</li>
<li>
<p><strong>keyword</strong> "FIXME": is optional and is used to indicate currently missing or unexpected behavior</p>
</li>
<li>
<p><strong>expectation</strong>: optional, usually used for the expected issue message, or value; concrete semantic depends
on the expectation type.</p>
</li>
<li>
<p><strong>location</strong>: used to further indicate the location of the problem, usually just the next line is assumed. The location has to be prefixed with <code>at</code> in most cases</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>If a single code line contains
several issues, multi-line comments are to be used:</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-n4js" data-lang="n4js">/* «remark» XPECT «type» ---
"expectation1" at "location1"
"expectation2" at "location2"
...
--- */</code></pre>
</div>
</div>
<div class="paragraph">
<p>Depending on the type of the expectation, the syntax may be a little bit different. The following table summarizes
the known types along with an example snippet to illustrate the syntax.</p>
</div>
<div class="sect2">
<h3 id="_errors"><a class="link" href="#_errors">errors</a></h3>
<div class="paragraph">
<p>Probably the most often used expectation type, indicates a validation error to be issued.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>var i: int = 5.5;</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_warnings"><a class="link" href="#_warnings">warnings</a></h3>
<div class="literalblock">
<div class="content">
<pre>Similar to "errors", indicates a validation warning to be issued.</pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>var i: int = 5.5;</code></pre>
</div>
</div>
</div>
<div class="sect2">
<h3 id="_noerrors"><a class="link" href="#_noerrors">noerrors</a></h3>
<div class="paragraph">
<p>See example above, used if no error is expected.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code>var a: A;
if (o instanceof A) {
// I want type guards XPECT noerrors FIXME --&gt;
a = o;
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>More expectation types will become available in future versions.</p>
</div>
</div>
</div>
</div>
</div>
<div id="footer">
<div id="footer-text">
</div>
</div>
<div class="Grid social" style="color:#d5dfea">
<div class="Cell Cell--2-12 m-Cell--withMargin">
<h2>Quick Links</h2>
<ul>
<li><a href="../downloads.html">Download</a></li>
<li><a href="../userguides/index.html">Documentation</a></li>
<li><a href="https://github.com/eclipse/n4js/">Source</a></li>
<li><a href="https://github.com/eclipse/n4js/issues">Issues</a></li>
</ul>
</div>
<div class="Cell Cell--2-12 m-Cell--withMargin">
<br/><br/>
<ul>
<li><a href="https://www.eclipse.org/forums/index.php/f/365/">Forum</a></li>
<li><a href="http://n4js.blogspot.de/">Blog</a></li>
<li><a href="https://dev.eclipse.org/mailman/listinfo/n4js-dev">Mailing List</a></li>
<li><a href="https://projects.eclipse.org/projects/technology.n4js">Eclipse Project Page</a></li>
<li><a href="https://twitter.com/n4jsdev">Tweets by n4jsdev</a></li>
</ul>
</div>
<div class="Cell Cell--2-12 m-Cell--withMargin">
<br/><br/>
<ul>
<li><a href="http://www.eclipse.org/">Eclipse Home</a></li>
<li><a href="http://www.eclipse.org/legal/privacy.php">Privacy Policy</a></li>
<li><a href="http://www.eclipse.org/legal/termsofuse.php">Terms of Use</a></li>
<li><a href="http://www.eclipse.org/legal/copyright.php">Copyright Agent</a></li>
<li><a href="http://www.eclipse.org/legal/">Legal</a></li>
</ul>
</div>
<div style="clear: both; height: 0; overflow: hidden;"></div>
</div>
<script>
// Toggle the table of contents
$( "button#tocbutton" ).click(function() {
if ($("#tocbutton").css('right') == '25px') {
$( "#tocbutton" ).animate({right: '215px'},"slow");
$( "#toc.toc2" ).animate({right: '0'},"slow");
}
else {
$( "#tocbutton" ).animate({right: '25px'},"slow");
$( "#toc.toc2" ).animate({right: '-13rem'},"slow");
}
});
</script>
<script type="text/javascript">
// Create a back to top button
$('body').prepend('<a href="#" class="back-to-top">Back to Top</a>');
var amountScrolled = 300;
$(window).scroll(function() {
if ( $(window).scrollTop() > amountScrolled ) {
$('a.back-to-top').fadeIn('slow');
} else {
$('a.back-to-top').fadeOut('slow');
}
});
$('a.back-to-top, a.simple-back-to-top').click(function() {
$('html, body').animate({
scrollTop: 0
}, 700);
return false;
});
</script>
</body>
</html>