contributing.html

<!DOCTYPE html>
<html>
	<head>
		<title>Q ⟩ Contributing</title>
		<meta charset="utf-8">
		<meta name="viewport"             content="width=device-width,initial-scale=1.0">
		<meta name="description"          content="Quantum computing in your browser.">
		<meta name="copyright"            content="Stewart Smith 2019–2020">
		<meta name="keywords"             content="
			Q, Q.js, Q-js, Qjs, quantum JavaScript,
			quantum, quantum physics, quantum mechanics, superposition,
			quantum computer, quantum computer programming, quantum computing, QC, 
			quantum simulator, quantum computer simulator, 
			qubit, qbit, gate, Hadamard, Bloch, Bloch Sphere,
			Web, Web site, website, Web browser, browser, HTML, HTML5, JavaScript, ES6, CSS,
			Chrome, Firefox, Safari, Opera, Brave, Edge, WebKit, Blink, Gecko, Mozilla,
			Stewart Smith, Stewart, Stew, Stuart, Steven, Steve, Stewdio, stewartsmith, stew_rtsmith, @stew_rtsmith,
			Moar, Moar Technologies Corp, MTC,
			Google, IBM, Microsoft, Amazon, NASA, DWave, D-Wave,
			Quil, OpenQASM,
				ProjectQ, Qiskit, 
				Quantum Development Kit, Cirq, Strawberry Fields, t|ket>,
				QCL, Quantum pseudocode, Q#, Q|SI>, Q language, qGCL, QFC, QML, LIQUi|>, Quipper,
			Stanford CS 269 Q: Quantum Computer Programming">
		
		<meta name="twitter:card"         content="summary_large_image">
		<meta name="twitter:site"         content="@stew_rtsmith">
		<meta name="twitter:creator"      content="@stew_rtsmith">
		<meta name="twitter:title"        content="Q ⟩ Contributing">
		<meta name="twitter:description"  content="Quantum computing in your browser.">
		<meta name="twitter:image"        content="https://quantumjavascript.app/assets/Q-website-preview.jpg">
		
		<meta property="og:type"          content="website">
		<meta property="og:title"         content="Q ⟩ Contributing">
		<meta property="og:description"   content="Quantum computing in your browser.">
		<meta property="og:image"         content="https://quantumjavascript.app/assets/Q-website-preview.jpg">
		<meta property="og:url"           content="https://quantumjavascript.app/contributing.html">
		
		<link rel="canonical" href="https://quantumjavascript.app/contributing.html">
		<link href="assets/Q-favicon-064.png" rel="icon" type="image/png">
		<link href="assets/Q-favicon-144.png" rel="apple-touch-icon">
		
		<link rel="stylesheet" href="Q/Q.css">
		<link rel="stylesheet" href="Q/Q-Circuit-Editor.css">
		<link rel="stylesheet" href="assets/documentation.css">

		<script src="https://www.googletagmanager.com/gtag/js" async></script>
		<script src="assets/ga.js"></script>
		<script src="Q/Q.js"></script>
		<script src="Q/Q-ComplexNumber.js"></script>
		<script src="Q/Q-Matrix.js"></script>
		<script src="Q/Q-Qubit.js"></script>
		<script src="Q/Q-Gate.js"></script>
		<script src="Q/Q-History.js"></script>
		<script src="Q/Q-Circuit.js"></script>
		<script src="Q/Q-Circuit-Editor.js"></script>
		<script src="assets/navigation.js"></script>
	
	</head>
	<body>
		<main>			
			<h3>Q needs you</h3>
			<p>
				It’s time for Q to grow.
				But it’s also 2020—we’re right in the middle of the
				<a href="https://en.wikipedia.org/wiki/Coronavirus_disease_2019" target="_blank">COVID-19</a> global pandemic.
				Are you in need of a project to take your mind off current events?
				Do you love JavaScript, CSS, and the free Web?
				How about breaking down complex subjects into simple bite-sized chunks of 
				<a href="https://en.wikipedia.org/wiki/Copywriting" target="_blank">copywriting</a> and minimalist diagrams?
				Are you a graphic designer or copywriter?
				Are you excited about quantum computing?
				<a href="https://github.com/stewdio/q.js" target="_blank">Join our Q.js project on GitHub</a>,
				<a href="https://github.com/stewdio/q.js/issues" target="_blank">create or resolve some issues</a>,
				and help us make quantum accessible!
			</p>
			<p>
				Read the following sections to familiarize yourself
				with Q’s objectives, inspirations, and plans for the future.
			</p>
			<h4>Roadmap</h4>
			<p>
				Thursday, 30 April 2020, is our one-year anniversary.
				From conception 12 months ago to now
				we’ve built a functioning code API 
				and a drag-and-drop circuit editor.
				While there are still many exciting features to add,
				and a list of 
				<a href="https://github.com/stewdio/q.js/issues" target="_blank">issues to resolve</a>,
				this anniversary is a milestone worth celebrating.
				As initial work on the circuit editor interface winds down
				our focus will shift back to optimization of the simulator itself. 
				During Summer 2020 our primary focus will be wrangling
				<a href="https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers" target="_blank">multiple execution threads</a> and hardware acceleration via
				<a href="https://en.wikipedia.org/wiki/WebGPU" target="_blank">WebGPU</a>.
				On the back burner 
				we’ll be adding new import and export utilities
				to make hopping between Q and other quantum suites a breeze.
			</p>
			<h4>Documentation style</h4>
			<h5>Concepts included</h5>
			<p>
				For most people anything “quantum” is brand new.
				Even the simpler mathematics 
				are things that most folks probably
				haven’t seen since high school. 
				(When’s the last time the average person actually 
				had to think about 
				<a href="Q-ComplexNumber.html">complex numbers</a>?)
				If we’re going to make quantum accessible
				we need to include simple / legible / digestible 
				concept primers for these topics
				right in the documentation, 
				and also provide links to learning resources. 
			</p>
			<p>
				To this end documentation for Q classes—such as 
				<a href="Q-Matrix.html">Q.Matrix</a>, 
				<a href="Q-Qubit.html">Q.Qubit</a>, 
				and so on—include brief explanations of the mathematics
				that the class represents
				before diving into the code and usage specifics.
				We also provide a separate
				<a href="resources.html">Resources page</a>
				with links to learn more about quantum computing in general.
			</p>
			<h5>Interface</h5>
			<p>
				This collection of <code>HTML</code> files serve as Q’s interactive
				documentation. 
				Its design objectives are tidiness, shareability, and consistency. 
				When possible the general UI features,
				such as the main navigation 
				or body modules,
				are visually flat.
				Buttons intended to be “pushed” 
				or circuit operations intended to be “dragged and dropped”
				may be represented as dimensional.
			</p>
			<h4>JavaScript style</h4>
			<blockquote cite="https://mitpress.mit.edu/sites/default/files/sicp/full-text/book/book-Z-H-7.html#%_chap_Temp_4">Programs must be written for people to read, and only incidentally for machines to execute.</blockquote>
			<cite>
				<p>
					<a href="https://mitpress.mit.edu/sites/default/files/sicp/full-text/book/book-Z-H-7.html#%_chap_Temp_4" target="_blank">Structure and Interpretation of Computer Programs,<br>
					Preface to the first edition</a>
				</p>
			</cite>
			<p>
				Q’s source code is verbose, heavily commented, and there’s great empathy for fellow learners.
				<a href="https://en.wikipedia.org/wiki/Visual_hierarchy" target="_blank">Visual hierarchy</a> is key when facing a brick of monospace code gibberish. 
				<a href="https://en.wikipedia.org/wiki/White_space_(visual_arts)" target="_blank">White space</a> helps; white space around variables, between conceptually different blocks of code.
				(You’ve got to let code breathe.)
				Semicolons as line-enders are avoided unless absolutely necessary. 
				(They’re just visual clutter otherwise; <a href="https://en.wikipedia.org/wiki/Typography" target="_blank">typographic</a> noise in the signal.)
				Q is meant to be flexible and expressive to adapt to your style.
				<a href="https://en.wikipedia.org/wiki/Fluent_interface" target="_blank">“Fluent interface” method chaining</a> is prized, but Q often uses static class methods as a foundation for instance methods, so you’re free to use either approach.
			</p>
			<h5>Low barrier to entry</h5>
			<p>
				Not everyone’s a grizzled software engineer—nor should they be.
				If you’re reading this on any desktop or laptop,
				you already have all the tools you need to start playing with Q.
				And “getting started” shouldn’t require installing new applications,
				signing up for new accounts,
				or spinning up a server thread from the command line
				just to load a website and play.
				(That’s one reason Q does
				<strong>not use <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules" target="_blank">JavaScript modules</a></strong>.)
				Just drag and drop any HTML file 
				from Q’s code repository onto your browser window
				and you’re up and running.
				This is the beauty of <a href="https://en.wikipedia.org/wiki/History_of_the_World_Wide_Web" target="_blank">Sir Tim’s World Wide Web</a>
				and every single person who has ever contributed to the art of the browser.
				In general you can always add more layers to 
				something—install what you will, tweak how you like.
				But removing layers is damn near impossible.
				Q aims to ship with few layers.
			</p>
			<h5>Hackable by design</h5>
			<p>
				Q places heavy emphasis on the ability to 
				inspect anything right from your own browser console
				in realtime.
				This is one of the reasons Q shuns 
				<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules" target="_blank">JavaScript modules</a>,
				is sensitive to the use of
				<a href="https://en.wikipedia.org/wiki/Closure_(computer_programming)#State_representation" target="_blank">closures</a>,
				and hangs all of its functionality off of the 
				<a href="Q.html" target="_blank">Q object</a>
				which sits in the global scope
				For us “hackability” is important—particularly for teaching and learning.
				By “hackable” we mean heavily inspectable and customizable
				by the curious—novice and expert alike.
				We do not not mean “hackable” as in “containing security flaws.”
			</p>
			<h5>Less Java, more JavaScript</h5>
			<p>
				Some ES6 syntax is preferred, but the bits that disfigure JavaScript to look more like Java, C++, C#, etc. are weeded out, bagged, and tossed in the river.
				There is nothing wrong with 
				<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Inheritance_and_the_prototype_chain" target="_blank">prototypal inheritance</a>
				and it’s in fact 
				<a href="https://www.crockford.com/javascript/inheritance.html" target="_blank">more powerful than classical inheritance</a>.
				JavaScript is uniquely beautiful in its flexibility
				and to paper over that with 
				“<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes" target="_blank"><code>class</code></a>”,
				or ignore the power of 
				<a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Closures" target="_blank">closures</a>,
				or pretend private variables weren’t possible prior to 2015
				is like confusing an aptitude for Rock Band
				with actual musicianship.
			</p>
			<p>
				While Q’s internal code uses <code>let</code> and <code>const</code> when declaring variables,
				the examples here use <code>var</code> instead;
				redeclare and overwrite example variables to your heart’s content.
			</p>
			<h5>Destructive vs non-destructive methods</h5>
			<p>
				Q pays particular attention to <em>destructive</em> versus <em>non-destructive</em> instance methods. 
				For example, the archetypal <em>non-destructive</em> method is <code>.<strong>clone</strong>()</code>
				which returns a new sibling instance of the object it was called from 
				and by its nature makes no alterations to that original object.
				In contrast, <code>.<strong>copy</strong>$(&nbsp;sibling&nbsp;)</code> is the archetypal <em>destructive</em> method
				which causes an instance to alter itself by overwriting its own properties’ values with values from a sibling instance, then returns itself.
				The dollar sign suffix is similar to 
				<a href="https://en.wikipedia.org/wiki/Ruby_(programming_language)" target="_blank">Ruby</a>’s
				exclamation point suffix and is a reminder that the operation is destructive; will alter the instance.
			</p>
<pre><code>
var 
cat = new <a href="Q.html">Q</a>.<a href="Q-ComplexNumber.html">ComplexNumber</a>( 1,  2 ),
dog = new <a href="Q.html">Q</a>.<a href="Q-ComplexNumber.html">ComplexNumber</a>( 3, -4 )

cat.<a href="Q-ComplexNumber.html#.toText">toText</a>()   <span class="comment">//  Returns '1 + 2i'</span>
dog.<a href="Q-ComplexNumber.html#.toText">toText</a>()   <span class="comment">//  Returns '3 - 4i'</span>

cat.<a href="Q-ComplexNumber.html#.add"><strong>add</strong></a>( dog ) <span class="comment">//  Non-destructive.</span>
cat.<a href="Q-ComplexNumber.html#.toText">toText</a>()   <span class="comment">//  Still returns '1 + 2i'</span>

cat.<a href="Q-ComplexNumber.html#.add$"><strong>add$</strong></a>( dog )<span class="comment">//  Destructive. Note the ‘$’ suffix.</span>
cat.<a href="Q-ComplexNumber.html#.toText">toText</a>()   <span class="comment">//  Now returns '4 - 2i'</span>
</pre></code>
			<p>
				The notable exception to this is the “Python-inspired”
				circuit editing syntax
				which uses convenience functions <strong>not</strong>
				suffixed with a dollar sign.
				This allows creating a circuit in Q to more closely resemble
				editing a Python script for Amazon Braket, IBM Qiskit, and so on:
			</p>
<pre><code>
<a href="Q.html">Q</a>( 2, 2 )
	.h( 1, 1 )
	.x( 2, [ 1, 2 ])

</code></pre>
			<h4>CSS style</h4>
			<p>
				Similar to our JavaScript style,
				our CSS eschews modules and shadow DOM containers
				in favor of carefully named global variables.
				We feel it should be easy for you, the developer, 
				to be able to remix and reconfigure Q with ease.
				Reuse the Q classes, customize them, or leave them be.
				(Any box is a 
				<a href="https://en.wikipedia.org/wiki/Black_box" target="_blank">“black box”</a> if you don’t look inside it.)
				Our CSS variables are prefixed with “<code>--Q</code>”
				and several categories, such as color palette values,
				are exposed for your convenience.
			</p>
		</main>
	</body>
</html>