709 lines
42 KiB
HTML
709 lines
42 KiB
HTML
|
||
|
||
<!DOCTYPE html>
|
||
<!--[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 name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<title>Contribution Guidelines — Project ACRN™ v 0.1-rc2 documentation</title>
|
||
|
||
|
||
|
||
|
||
<link rel="shortcut icon" href="_static/ACRN-favicon-32x32.png"/>
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
|
||
|
||
|
||
|
||
<link rel="stylesheet" href="_static/acrn-custom.css" type="text/css" />
|
||
|
||
|
||
|
||
<link rel="index" title="Index"
|
||
href="genindex.html"/>
|
||
<link rel="search" title="Search" href="search.html"/>
|
||
<link rel="top" title="Project ACRN™ v 0.1-rc2 documentation" href="index.html"/>
|
||
<link rel="next" title="API Documentation" href="api/index.html"/>
|
||
<link rel="prev" title="Release Notes" href="release_notes.html"/>
|
||
|
||
|
||
<script src="_static/js/modernizr.min.js"></script>
|
||
|
||
</head>
|
||
|
||
<body class="wy-body-for-nav" role="document">
|
||
|
||
|
||
<div class="wy-grid-for-nav">
|
||
|
||
|
||
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
|
||
<div class="wy-side-scroll">
|
||
<div class="wy-side-nav-search">
|
||
|
||
|
||
|
||
<a href="index.html" class="icon icon-home"> Project ACRN™
|
||
|
||
|
||
|
||
|
||
<img src="_static/ACRN_Logo_300w.png" class="logo" />
|
||
|
||
</a>
|
||
|
||
|
||
|
||
|
||
<div class="version">
|
||
v 0.1-rc2
|
||
</div>
|
||
|
||
|
||
|
||
|
||
<div role="search">
|
||
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
|
||
<input type="text" name="q" placeholder="Search docs" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
|
||
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<ul class="current">
|
||
<li class="toctree-l1"><a class="reference internal" href="introduction/index.html">Introduction to Project ACRN</a><ul>
|
||
<li class="toctree-l2"><a class="reference internal" href="introduction/index.html#licensing">Licensing</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="introduction/index.html#acrn-device-model-service-os-and-user-os">ACRN Device Model, Service OS, and User OS</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="introduction/index.html#boot-sequence">Boot Sequence</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="introduction/index.html#acrn-hypervisor-architecture">ACRN Hypervisor Architecture</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="introduction/index.html#acrn-device-model-architecture">ACRN Device Model Architecture</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="introduction/index.html#device-pass-through">Device pass through</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="introduction/index.html#hardware-support-for-device-passthrough">Hardware support for device passthrough</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="introduction/index.html#hypervisor-support-for-device-passthrough">Hypervisor support for device passthrough</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="introduction/index.html#acrn-i-o-mediator">ACRN I/O mediator</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="introduction/index.html#virtio-framework-architecture">Virtio framework architecture</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1"><a class="reference internal" href="hardware.html">Supported Hardware</a><ul>
|
||
<li class="toctree-l2"><a class="reference internal" href="hardware.html#intel-apollo-lake-nuc">Intel Apollo Lake NUC</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1"><a class="reference internal" href="getting_started/index.html">Getting Started Guide</a><ul>
|
||
<li class="toctree-l2"><a class="reference internal" href="getting_started/index.html#hardware-setup">Hardware setup</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="getting_started/index.html#software-setup">Software setup</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="getting_started/index.html#firmware-update-on-the-nuc">Firmware update on the NUC</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="getting_started/index.html#set-up-a-clear-linux-operating-system">Set up a Clear Linux Operating System</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="getting_started/index.html#add-the-acrn-hypervisor-to-the-efi-partition">Add the ACRN hypervisor to the EFI Partition</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="getting_started/index.html#create-a-network-bridge">Create a Network Bridge</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="getting_started/index.html#set-up-reference-uos">Set up Reference UOS</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="getting_started/index.html#build-acrn-from-source">Build ACRN from Source</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1"><a class="reference internal" href="primer/index.html">Developer Primer</a><ul>
|
||
<li class="toctree-l2"><a class="reference internal" href="primer/index.html#source-tree-structure">Source Tree Structure</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#acrn-hypervisor-source-tree">ACRN hypervisor source tree</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#acrn-device-model-source-tree">ACRN Device Model source tree</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#acrn-documentation-source-tree">ACRN documentation source tree</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="primer/index.html#cpu-virtualization">CPU virtualization</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#host-gdt">Host GDT</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#host-idt">Host IDT</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#guest-smp-booting">Guest SMP Booting</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#vmx-configuration">VMX configuration</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#cpuid-and-guest-tsc-calibration">CPUID and Guest TSC calibration</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#rdtsc-rdtscp">RDTSC/RDTSCP</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#cr-register-virtualization">CR Register virtualization</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#msr-bitmap">MSR BITMAP</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#i-o-bitmap">I/O BITMAP</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#exceptions">Exceptions</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="primer/index.html#memory-virtualization">Memory virtualization</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#physical-memory-layout">Physical Memory Layout</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#pv-mmu-memory-mapping-in-the-hypervisor">PV (MMU) Memory Mapping in the Hypervisor</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#pv-mmu-memory-mapping-in-vms">PV (MMU) Memory Mapping in VMs</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#host-guest-ept-memory-mapping">Host-Guest (EPT) Memory Mapping</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="primer/index.html#graphic-mediation">Graphic mediation</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="primer/index.html#i-o-emulation">I/O emulation</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#device-assignment-management">Device Assignment Management</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#pio-mmio-trap-flow">PIO/MMIO trap Flow</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="primer/index.html#virtual-interrupt">Virtual interrupt</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#virtual-lapic">Virtual LAPIC</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#virtual-ioapic">Virtual IOAPIC</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#virtual-pic">Virtual PIC</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#virtual-interrupt-injection">Virtual Interrupt Injection</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="primer/index.html#vt-x-and-vt-d">VT-x and VT-d</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="primer/index.html#hypercall">Hypercall</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="primer/index.html#device-emulation">Device emulation</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="primer/index.html#virtio-devices">Virtio Devices</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#virtio-rnd">Virtio-rnd</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#virtio-blk">Virtio-blk</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#virtio-net">Virtio-net</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="primer/index.html#virtio-console">Virtio-console</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1"><a class="reference internal" href="release_notes.html">Release Notes</a><ul>
|
||
<li class="toctree-l2"><a class="reference internal" href="release_notes.html#version-0-1-release-march-2018">Version 0.1 release (March 2018)</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1 current"><a class="current reference internal" href="#">Contribution Guidelines</a><ul>
|
||
<li class="toctree-l2"><a class="reference internal" href="#licensing">Licensing</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#developer-certification-of-origin-dco">Developer Certification of Origin (DCO)</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="#dco-sign-off-methods">DCO Sign-Off Methods</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#prerequisites">Prerequisites</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#repository-layout">Repository layout</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#submitting-issues">Submitting Issues</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#contribution-tools-and-git-setup">Contribution Tools and Git Setup</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="#signed-off-by">Signed-off-by</a></li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#coding-style">Coding Style</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#contribution-workflow">Contribution Workflow</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="#commit-guidelines">Commit Guidelines</a><ul>
|
||
<li class="toctree-l3"><a class="reference internal" href="#commit-message-body">Commit Message Body</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="#other-commit-expectations">Other Commit Expectations</a></li>
|
||
<li class="toctree-l3"><a class="reference internal" href="#identifying-contribution-origin">Identifying Contribution Origin</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
<li class="toctree-l1"><a class="reference internal" href="api/index.html">API Documentation</a><ul>
|
||
<li class="toctree-l2"><a class="reference internal" href="api/hypercall_api.html">Hypercall APIs</a></li>
|
||
<li class="toctree-l2"><a class="reference internal" href="api/devicemodel_api.html">Device Model APIs</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</nav>
|
||
|
||
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
|
||
|
||
|
||
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
|
||
|
||
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
|
||
<a href="index.html">Project ACRN™</a>
|
||
|
||
</nav>
|
||
|
||
|
||
|
||
<div class="wy-nav-content">
|
||
<div class="rst-content">
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
<div role="navigation" aria-label="breadcrumbs navigation">
|
||
|
||
<ul class="wy-breadcrumbs">
|
||
|
||
<li><a href="index.html">Docs</a> »</li>
|
||
|
||
<li>Contribution Guidelines</li>
|
||
|
||
|
||
<li class="wy-breadcrumbs-aside">
|
||
|
||
|
||
|
||
</li>
|
||
|
||
</ul>
|
||
|
||
|
||
<hr/>
|
||
</div>
|
||
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
|
||
<div itemprop="articleBody">
|
||
|
||
<div class="section" id="contribution-guidelines">
|
||
<span id="contribute"></span><h1>Contribution Guidelines<a class="headerlink" href="#contribution-guidelines" title="Permalink to this headline">¶</a></h1>
|
||
<p>As an open-source project, we welcome and encourage the community to
|
||
submit patches directly to project ACRN. In our collaborative open
|
||
source environment, standards and methods for submitting changes help
|
||
reduce the chaos that can result from an active development community.</p>
|
||
<p>This document explains how to participate in project conversations, log
|
||
bugs and enhancement requests, and submit patches to the project so your
|
||
patch will be accepted quickly in the codebase.</p>
|
||
<div class="section" id="licensing">
|
||
<h2>Licensing<a class="headerlink" href="#licensing" title="Permalink to this headline">¶</a></h2>
|
||
<p>Licensing is very important to open source projects. It helps ensure the
|
||
software continues to be available under the terms that the author
|
||
desired.</p>
|
||
<p>Project ACRN uses a BSD-3-Clause license, as found in the license_header in
|
||
the project’s GitHub repo.</p>
|
||
<p>A license tells you what rights you have as a developer, as provided by
|
||
the copyright holder. It is important that the contributor fully
|
||
understands the licensing rights and agrees to them. Sometimes the
|
||
copyright holder isn’t the contributor, such as when the contributor is
|
||
doing work on behalf of a company.</p>
|
||
</div>
|
||
<div class="section" id="developer-certification-of-origin-dco">
|
||
<span id="dco"></span><h2>Developer Certification of Origin (DCO)<a class="headerlink" href="#developer-certification-of-origin-dco" title="Permalink to this headline">¶</a></h2>
|
||
<p>To make a good faith effort to ensure licensing criteria are met,
|
||
project ACRN requires the Developer Certificate of Origin (DCO) process
|
||
to be followed.</p>
|
||
<p>The DCO is an attestation attached to every contribution made by every
|
||
developer. In the commit message of the contribution, (described more
|
||
fully later in this document), the developer simply adds a
|
||
<code class="docutils literal"><span class="pre">Signed-off-by</span></code> statement and thereby agrees to the DCO.</p>
|
||
<p>When a developer submits a patch, it is a commitment that the
|
||
contributor has the right to submit the patch per the license. The DCO
|
||
agreement is shown below and at <a class="reference external" href="http://developercertificate.org/">http://developercertificate.org/</a>.</p>
|
||
<div class="highlight-none"><div class="highlight"><pre><span></span>Developer's Certificate of Origin 1.1
|
||
|
||
By making a contribution to this project, I certify that:
|
||
|
||
(a) The contribution was created in whole or in part by me and I
|
||
have the right to submit it under the open source license
|
||
indicated in the file; or
|
||
|
||
(b) The contribution is based upon previous work that, to the
|
||
best of my knowledge, is covered under an appropriate open
|
||
source license and I have the right under that license to
|
||
submit that work with modifications, whether created in whole
|
||
or in part by me, under the same open source license (unless
|
||
I am permitted to submit under a different license), as
|
||
Indicated in the file; or
|
||
|
||
(c) The contribution was provided directly to me by some other
|
||
person who certified (a), (b) or (c) and I have not modified
|
||
it.
|
||
|
||
(d) I understand and agree that this project and the contribution
|
||
are public and that a record of the contribution (including
|
||
all personal information I submit with it, including my
|
||
sign-off) is maintained indefinitely and may be redistributed
|
||
consistent with this project or the open source license(s)
|
||
involved.
|
||
</pre></div>
|
||
</div>
|
||
<div class="section" id="dco-sign-off-methods">
|
||
<h3>DCO Sign-Off Methods<a class="headerlink" href="#dco-sign-off-methods" title="Permalink to this headline">¶</a></h3>
|
||
<p>The DCO requires a sign-off message in the following format appear on each
|
||
commit in the pull request:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Signed</span><span class="o">-</span><span class="n">off</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">Acrnus</span> <span class="n">Jones</span> <span class="o"><</span><span class="n">acrnusj</span><span class="nd">@gmail</span><span class="o">.</span><span class="n">com</span><span class="o">></span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The DCO text can either be manually added to your commit body, or you can add
|
||
either <code class="docutils literal"><span class="pre">-s</span></code> or <code class="docutils literal"><span class="pre">--signoff</span></code> to your usual Git commit commands. If you forget
|
||
to add the sign-off you can also amend a previous commit with the sign-off by
|
||
running <code class="docutils literal"><span class="pre">git</span> <span class="pre">commit</span> <span class="pre">--amend</span> <span class="pre">-s</span></code>. If you’ve pushed your changes to GitHub
|
||
already you’ll need to force push your branch after this with <code class="docutils literal"><span class="pre">git</span> <span class="pre">push</span> <span class="pre">-f</span></code>.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="prerequisites">
|
||
<h2>Prerequisites<a class="headerlink" href="#prerequisites" title="Permalink to this headline">¶</a></h2>
|
||
<p>As a contributor, you’ll want to be familiar with project ACRN, how to
|
||
configure, install, and use it as explained in the <a class="reference external" href="https://projectacrn.org">project ACRN website</a>
|
||
and how to set up your development environment as introduced in the
|
||
project ACRN <a class="reference external" href="https://projectacrn.github.io/getting_started/">Getting Started Guide</a>.</p>
|
||
<p>You should be familiar with common developer tools such as Git and CMake, and
|
||
platforms such as GitHub.</p>
|
||
<p>If you haven’t already done so, you’ll need to create a (free) GitHub account
|
||
on <a class="reference external" href="https://github.com">https://github.com</a> and have Git tools available on your development system.</p>
|
||
</div>
|
||
<div class="section" id="repository-layout">
|
||
<h2>Repository layout<a class="headerlink" href="#repository-layout" title="Permalink to this headline">¶</a></h2>
|
||
<p>To clone the ACRN hypervisor repository use:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">projectacrn</span><span class="o">/</span><span class="n">acrn</span><span class="o">-</span><span class="n">hypervisor</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>To clone the ACRN device model repository use:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">projectacrn</span><span class="o">/</span><span class="n">acrn</span><span class="o">-</span><span class="n">devicemodel</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The project ACRN directory structure is described in the <a class="reference external" href="https://projectacrn.github.io/hypervisor_primer">Hypervisor
|
||
Primer</a> document. In addition to the ACRN hypervisor and device model itself,
|
||
you’ll also find the sources for technical documentation, sample code
|
||
and supported board configurations. All of these are available for
|
||
developers to contribute to and enhance.</p>
|
||
</div>
|
||
<div class="section" id="submitting-issues">
|
||
<h2>Submitting Issues<a class="headerlink" href="#submitting-issues" title="Permalink to this headline">¶</a></h2>
|
||
<p>Before starting on a patch, first check in our issues in the <a class="reference external" href="https://lists.projectacrn.org/g/acrn-dev">ACRN-dev
|
||
mailing list</a> system to see what’s been reported on the issue you’d
|
||
like to address. Have a conversation on the <a class="reference external" href="https://lists.projectacrn.org/g/acrn-dev">ACRN-dev mailing list</a> to
|
||
see what others think of your issue (and proposed solution). You may
|
||
find others that have encountered the issue you’re finding, or that have
|
||
similar ideas for changes or additions. Send a message to the <a class="reference external" href="https://lists.projectacrn.org/g/acrn-dev">ACRN-dev
|
||
mailing list</a> to introduce and discuss your idea with the development
|
||
community.</p>
|
||
<p>It’s always a good practice to search for existing or related issues
|
||
before submitting your own. When you submit an issue (bug or feature
|
||
request), the triage team will review and comment on the submission,
|
||
typically within a few business days.</p>
|
||
<blockquote>
|
||
<div></div></blockquote>
|
||
</div>
|
||
<div class="section" id="contribution-tools-and-git-setup">
|
||
<span id="contribution-tools"></span><h2>Contribution Tools and Git Setup<a class="headerlink" href="#contribution-tools-and-git-setup" title="Permalink to this headline">¶</a></h2>
|
||
<div class="section" id="signed-off-by">
|
||
<h3>Signed-off-by<a class="headerlink" href="#signed-off-by" title="Permalink to this headline">¶</a></h3>
|
||
<p>The name in the commit message <code class="docutils literal"><span class="pre">Signed-off-by:</span></code> line and your email must
|
||
match the change authorship information. Make sure your <code class="file docutils literal"><span class="pre">.gitconfig</span></code>
|
||
is set up correctly:</p>
|
||
<div class="highlight-console"><div class="highlight"><pre><span></span><span class="go">git config --global user.name "David Developer"</span>
|
||
<span class="go">git config --global user.email "david.developer@company.com"</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="coding-style">
|
||
<h2>Coding Style<a class="headerlink" href="#coding-style" title="Permalink to this headline">¶</a></h2>
|
||
<p>Use these coding guidelines to ensure that your development complies with the
|
||
project’s style and naming conventions.</p>
|
||
<p>In general, follow the <a class="reference external" href="https://kernel.org/doc/html/latest/process/coding-style.html">Linux kernel coding style</a>, with the
|
||
following exceptions:</p>
|
||
<ul class="simple">
|
||
<li>Add braces to every <code class="docutils literal"><span class="pre">if</span></code> and <code class="docutils literal"><span class="pre">else</span></code> body, even for single-line code
|
||
blocks. Use the <code class="docutils literal"><span class="pre">--ignore</span> <span class="pre">BRACES</span></code> flag to make <em>checkpatch</em> stop
|
||
complaining.</li>
|
||
<li>Use spaces instead of tabs to align comments after declarations, as needed.</li>
|
||
<li>Use C89-style single line comments, <code class="docutils literal"><span class="pre">/*</span>  <span class="pre">*/</span></code>. The C99-style single line
|
||
comment, <code class="docutils literal"><span class="pre">//</span></code>, is not allowed.</li>
|
||
<li>Use <code class="docutils literal"><span class="pre">/**</span>  <span class="pre">*/</span></code> for doxygen comments that need to appear in the documentation.</li>
|
||
</ul>
|
||
</div>
|
||
<div class="section" id="contribution-workflow">
|
||
<span id="id1"></span><h2>Contribution Workflow<a class="headerlink" href="#contribution-workflow" title="Permalink to this headline">¶</a></h2>
|
||
<p>One general practice we encourage, is to make small,
|
||
controlled changes. This practice simplifies review, makes merging and
|
||
rebasing easier, and keeps the change history clear and clean.</p>
|
||
<p>When contributing to project ACRN, it is also important you provide as much
|
||
information as you can about your change, update appropriate documentation,
|
||
and test your changes thoroughly before submitting.</p>
|
||
<p>The general GitHub workflow used by project ACRN developers uses a combination of
|
||
command line Git commands and browser interaction with GitHub. As it is with
|
||
Git, there are multiple ways of getting a task done. We’ll describe a typical
|
||
workflow here:</p>
|
||
<ol class="arabic">
|
||
<li><p class="first"><a class="reference external" href="https://github.com/projectacrn/acrn-hypervisor#fork-destination-box">Create a Fork of acrn-hypervisor</a>
|
||
to your personal account on GitHub. (Click on the fork button in the top
|
||
right corner of the project acrn-hypervisor repo page in GitHub.)</p>
|
||
</li>
|
||
<li><p class="first">On your development computer, clone the fork you just made:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/<</span><span class="n">your</span> <span class="n">github</span> <span class="nb">id</span><span class="o">>/</span><span class="n">acrn</span><span class="o">-</span><span class="n">hypervisor</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>This would be a good time to let Git know about the upstream repo too:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">upstream</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">projectacrn</span><span class="o">/</span><span class="n">acrn</span><span class="o">-</span><span class="n">hypervisor</span><span class="o">.</span><span class="n">git</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>and verify the remote repos:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">remote</span> <span class="o">-</span><span class="n">v</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p class="first">Create a topic branch (off of master) for your work (if you’re addressing
|
||
an issue, we suggest including the issue number in the branch name):</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span>
|
||
<span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">fix_comment_typo</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p class="first">Make changes, test locally, change, test, test again, …</p>
|
||
</li>
|
||
<li><p class="first">When things look good, start the pull request process by adding your changed
|
||
files:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">add</span> <span class="p">[</span><span class="n">file</span><span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="n">that</span> <span class="n">changed</span><span class="p">,</span> <span class="n">add</span> <span class="o">-</span><span class="n">p</span> <span class="k">if</span> <span class="n">you</span> <span class="n">want</span> <span class="n">to</span> <span class="n">be</span> <span class="n">more</span> <span class="n">specific</span><span class="p">]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>You can see files that are not yet staged using:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">status</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p class="first">Verify changes to be committed look as you expected:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">diff</span> <span class="o">--</span><span class="n">cached</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p class="first">Commit your changes to your local repo:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">commit</span> <span class="o">-</span><span class="n">s</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The <code class="docutils literal"><span class="pre">-s</span></code> option automatically adds your <code class="docutils literal"><span class="pre">Signed-off-by:</span></code> to your commit
|
||
message. Your commit will be rejected without this line that indicates your
|
||
agreement with the <a class="reference internal" href="#dco">DCO</a>. See the <a class="reference internal" href="#commit-guidelines">Commit Guidelines</a> section
|
||
below for specific guidelines for writing your commit messages.</p>
|
||
</li>
|
||
<li><p class="first">Push your topic branch with your changes to your fork in your personal
|
||
GitHub account:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">push</span> <span class="n">origin</span> <span class="n">fix_comment_typo</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p class="first">In your web browser, go to your forked repo and click on the Compare & pull
|
||
request button for the branch you just worked on and you want to open a pull
|
||
request with.</p>
|
||
</li>
|
||
<li><p class="first">Review the pull request changes, and verify that you are opening a pull request
|
||
for the appropriate branch. The title and message from your commit message should
|
||
appear as well.</p>
|
||
</li>
|
||
<li><p class="first">GitHub will assign one or more suggested reviewers (based on the CODEOWNERS file
|
||
in the repo). If you are a project member, you can select additional reviewers
|
||
now too.</p>
|
||
</li>
|
||
<li><p class="first">Click on the submit button and your pull request is sent and awaits review.
|
||
Email will be sent as review comments are made, or you can check on your
|
||
pull request at <a class="reference external" href="https://github.com/projectacrn/acrn-hypervisor/pulls">https://github.com/projectacrn/acrn-hypervisor/pulls</a>.</p>
|
||
</li>
|
||
<li><p class="first">While you’re waiting for your pull request to be accepted and merged, you can
|
||
create another branch to work on another issue. (Be sure to make your new branch
|
||
off of master and not the previous branch.):</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span>
|
||
<span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">fix_another_issue</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>and use the same process described above to work on this new topic branch.</p>
|
||
</li>
|
||
<li><p class="first">If reviewers do request changes to your patch, you can interactively rebase
|
||
commit(s) to fix review issues. In your development repo:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">fetch</span> <span class="o">--</span><span class="nb">all</span>
|
||
<span class="n">git</span> <span class="n">rebase</span> <span class="o">--</span><span class="n">ignore</span><span class="o">-</span><span class="n">whitespace</span> <span class="n">upstream</span><span class="o">/</span><span class="n">master</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The <code class="docutils literal"><span class="pre">--ignore-whitespace</span></code> option stops git apply (called by rebase) from changing
|
||
any whitespace. Continuing:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">rebase</span> <span class="o">-</span><span class="n">i</span> <span class="o"><</span><span class="n">offending</span><span class="o">-</span><span class="n">commit</span><span class="o">-</span><span class="nb">id</span><span class="o">></span>
|
||
</pre></div>
|
||
</div>
|
||
<p>In the interactive rebase editor, replace pick with edit to select a specific
|
||
commit (if there’s more than one in your pull request), or remove the line to
|
||
delete a commit entirely. Then edit files to fix the issues in the review.</p>
|
||
<p>As before, inspect and test your changes. When ready, continue the
|
||
patch submission:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">add</span> <span class="p">[</span><span class="n">file</span><span class="p">(</span><span class="n">s</span><span class="p">)]</span>
|
||
<span class="n">git</span> <span class="n">rebase</span> <span class="o">--</span><span class="k">continue</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>Update commit comment if needed, and continue:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">push</span> <span class="o">--</span><span class="n">force</span> <span class="n">origin</span> <span class="n">fix_comment_typo</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>By force pushing your update, your original pull request will be updated with
|
||
your changes so you won’t need to resubmit the pull request.</p>
|
||
<p>You can follow the same workflow for contributing to acrn-devicemodel.</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
<div class="section" id="commit-guidelines">
|
||
<h2>Commit Guidelines<a class="headerlink" href="#commit-guidelines" title="Permalink to this headline">¶</a></h2>
|
||
<p>Changes are submitted as Git commits. Each commit message must contain:</p>
|
||
<ul>
|
||
<li><p class="first">A short and descriptive subject line that is less than 72 characters,
|
||
followed by a blank line. The subject line must include a prefix that
|
||
identifies the subsystem being changed, followed by a colon, and a short
|
||
title, for example: <code class="docutils literal"><span class="pre">doc:</span> <span class="pre">update</span> <span class="pre">commit</span> <span class="pre">guidelines</span> <span class="pre">instructions</span></code>.
|
||
(If you’re updating an existing file, you can use
|
||
<code class="docutils literal"><span class="pre">git</span> <span class="pre">log</span> <span class="pre"><filename></span></code> to see what developers used as the prefix for
|
||
previous patches of this file.)</p>
|
||
</li>
|
||
<li><p class="first">A change description with your logic or reasoning for the changes, followed
|
||
by a blank line.</p>
|
||
</li>
|
||
<li><p class="first">A Signed-off-by line, <code class="docutils literal"><span class="pre">Signed-off-by:</span> <span class="pre"><name></span> <span class="pre"><email></span></code> typically added
|
||
automatically by using <code class="docutils literal"><span class="pre">git</span> <span class="pre">commit</span> <span class="pre">-s</span></code></p>
|
||
</li>
|
||
<li><p class="first">If the change addresses an issue, include a line of the form:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Fixes</span> <span class="c1">#<brief description about the reported issue>.</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<p>All changes and topics sent to GitHub must be well-formed, as described above.</p>
|
||
<div class="section" id="commit-message-body">
|
||
<h3>Commit Message Body<a class="headerlink" href="#commit-message-body" title="Permalink to this headline">¶</a></h3>
|
||
<p>When editing the commit message, please briefly explain what your change
|
||
does and why it’s needed. A change summary of <code class="docutils literal"><span class="pre">"Fixes</span> <span class="pre">stuff"</span></code> will be rejected.</p>
|
||
<div class="admonition warning">
|
||
<p class="first admonition-title">Warning</p>
|
||
<p class="last">An empty change summary body is not permitted. Even for trivial changes, please
|
||
include a summary body in the commmit message.</p>
|
||
</div>
|
||
<p>The description body of the commit message must include:</p>
|
||
<ul class="simple">
|
||
<li><strong>what</strong> the change does,</li>
|
||
<li><strong>why</strong> you chose that approach,</li>
|
||
<li><strong>what</strong> assumptions were made, and</li>
|
||
<li><strong>how</strong> you know it works – for example, which tests you ran.</li>
|
||
</ul>
|
||
<p>For examples of accepted commit messages, you can refer to the acrn-hypervisor GitHub
|
||
<a class="reference external" href="https://github.com/projectacrn/acrn-hypervisor/commits/master">changelog</a>.</p>
|
||
</div>
|
||
<div class="section" id="other-commit-expectations">
|
||
<h3>Other Commit Expectations<a class="headerlink" href="#other-commit-expectations" title="Permalink to this headline">¶</a></h3>
|
||
<ul class="simple">
|
||
<li>Commits must build cleanly when applied on top of each other, thus avoiding
|
||
breaking bisectability.</li>
|
||
<li>Each commit must address a single identifiable issue and must be
|
||
logically self-contained. Unrelated changes should be submitted as
|
||
separate commits.</li>
|
||
<li>You may submit pull request RFCs (requests for comments) to send work
|
||
proposals, progress snapshots of your work, or to get early feedback on
|
||
features or changes that will affect multiple areas in the code base.</li>
|
||
</ul>
|
||
</div>
|
||
<div class="section" id="identifying-contribution-origin">
|
||
<h3>Identifying Contribution Origin<a class="headerlink" href="#identifying-contribution-origin" title="Permalink to this headline">¶</a></h3>
|
||
<p>When adding a new file to the tree, it is important to detail the source of
|
||
origin on the file, provide attributions, and detail the intended usage. In
|
||
cases where the file is an original to acrn-hypervisor, the commit message should
|
||
include the following (“Original” is the assumption if no Origin tag is
|
||
present):</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Origin</span><span class="p">:</span> <span class="n">Original</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>In cases where the file is imported from an external project, the commit
|
||
message shall contain details regarding the original project, the location of
|
||
the project, the SHA-id of the origin commit for the file, the intended
|
||
purpose, and if the file will be maintained by the acrn-hypervisor project,
|
||
(whether or not project ACRN will contain a localized branch or if
|
||
it is a downstream copy).</p>
|
||
<p>For example, a copy of a locally maintained import:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Origin</span><span class="p">:</span> <span class="n">Contiki</span> <span class="n">OS</span>
|
||
<span class="n">License</span><span class="p">:</span> <span class="n">BSD</span> <span class="mi">3</span><span class="o">-</span><span class="n">Clause</span>
|
||
<span class="n">URL</span><span class="p">:</span> <span class="n">http</span><span class="p">:</span><span class="o">//</span><span class="n">www</span><span class="o">.</span><span class="n">contiki</span><span class="o">-</span><span class="n">os</span><span class="o">.</span><span class="n">org</span><span class="o">/</span>
|
||
<span class="n">commit</span><span class="p">:</span> <span class="mi">853207</span><span class="n">acfdc6549b10eb3e44504b1a75ae1ad63a</span>
|
||
<span class="n">Purpose</span><span class="p">:</span> <span class="n">Introduction</span> <span class="n">of</span> <span class="n">networking</span> <span class="n">stack</span><span class="o">.</span>
|
||
<span class="n">Maintained</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">acrn</span><span class="o">-</span><span class="n">hypervisor</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>For example, a copy of an externally maintained import:</p>
|
||
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="n">Origin</span><span class="p">:</span> <span class="n">Tiny</span> <span class="n">Crypt</span>
|
||
<span class="n">License</span><span class="p">:</span> <span class="n">BSD</span> <span class="mi">3</span><span class="o">-</span><span class="n">Clause</span>
|
||
<span class="n">URL</span><span class="p">:</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="mi">01</span><span class="n">org</span><span class="o">/</span><span class="n">tinycrypt</span>
|
||
<span class="n">commit</span><span class="p">:</span> <span class="mi">08</span><span class="n">ded7f21529c39e5133688ffb93a9d0c94e5c6e</span>
|
||
<span class="n">Purpose</span><span class="p">:</span> <span class="n">Introduction</span> <span class="n">of</span> <span class="n">TinyCrypt</span>
|
||
<span class="n">Maintained</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">External</span>
|
||
</pre></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
<div class="articleComments">
|
||
|
||
</div>
|
||
</div>
|
||
<footer>
|
||
|
||
|
||
<hr/>
|
||
|
||
<div role="contentinfo">
|
||
<p>
|
||
© Copyright 2018, Project ACRN.
|
||
Last updated on Mar 10, 2018.
|
||
|
||
</p>
|
||
</div>
|
||
|
||
</footer>
|
||
|
||
</div>
|
||
</div>
|
||
|
||
</section>
|
||
|
||
</div>
|
||
|
||
|
||
|
||
|
||
|
||
<script type="text/javascript">
|
||
var DOCUMENTATION_OPTIONS = {
|
||
URL_ROOT:'./',
|
||
VERSION:'v 0.1-rc2',
|
||
COLLAPSE_INDEX:false,
|
||
FILE_SUFFIX:'.html',
|
||
HAS_SOURCE: true,
|
||
SOURCELINK_SUFFIX: '.txt'
|
||
};
|
||
</script>
|
||
<script type="text/javascript" src="_static/jquery.js"></script>
|
||
<script type="text/javascript" src="_static/underscore.js"></script>
|
||
<script type="text/javascript" src="_static/doctools.js"></script>
|
||
|
||
|
||
|
||
|
||
|
||
<script type="text/javascript" src="_static/js/theme.js"></script>
|
||
|
||
|
||
|
||
|
||
<script type="text/javascript">
|
||
jQuery(function () {
|
||
SphinxRtdTheme.StickyNav.enable();
|
||
});
|
||
</script>
|
||
|
||
|
||
</body>
|
||
</html> |