blob: dbf4d551f832062853d69168985218b515298fd6 [file] [log] [blame]
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
<link rel="stylesheet" href="/packages/assets/bootstrap/bootstrap.min.css">
<title>Contributions welcome</title>
<link rel="stylesheet" href="/packages/assets/css/style.css">
<script src="/packages/assets/js/code.js"></script>
<meta name="twitter:card" content="summary"/>
<meta name="twitter:image" content="https://eclipse.org/packages/images/icon/twitter_icon.png"/>
<meta name="twitter:title" content="Contributions welcome"/>
<meta name="twitter:description" content=""/>
<link rel="icon" type="image/svg+xml" href="/packages/images/icon/icon.svg" sizes="any">
<link rel="icon" href="/packages/images/icon/icon.png" sizes="192x192">
<link rel="apple-touch-icon-precomposed" href="/packages/images/icon/icon_apple.png" sizes="180x180">
</head>
<body>
<header>
<nav class="navbar navbar-expand-md fixed-top navbar-light bg-light">
<div class="container">
<a class="navbar-brand" href="/packages/">
<img src="/packages/images/icon_brand_navbar.svg" width="30" height="30" alt="Eclipse IoT Packages™">
</a>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbarCollapse" aria-controls="navbarCollapse" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div class="collapse navbar-collapse" id="navbarCollapse">
<ul class="navbar-nav mr-auto"><li class="nav-item">
<a
class="nav-link"
href="/packages/">Home</a>
</li>
<li class="nav-item">
<a
class="nav-link"
href="/packages/about/">About</a>
</li>
<li class="nav-item">
<a
class="nav-link"
href="/packages/faq/">FAQ</a>
</li>
<li class="nav-item">
<a
class="nav-link active"
href="/packages/contribute/">Contribute</a>
</li>
<li class="nav-item">
<a
class="nav-link"
href="/packages/prereqs/">Prerequisites</a>
</li>
<li class="nav-item">
<a
class="nav-link"
href="/packages/repository/">Repository</a>
</li>
</ul>
</div>
</div>
</nav></header>
<main id="main" role="main" >
<div class="container mt-5">
<div class="row">
<div class="col-12 col-sm-9 col-xl-8">
<h1>Contributions welcome</h1>
<p class="lead">Contributions to this project are very welcome. And contributions can come in many different forms, one of it is code.</p></div>
</div>
</div>
<div class="container">
<h2 id="providing-feedback">Providing feedback</h2>
<p>Feedback is always welcome. The more constructive it is, the more impact it will have.</p>
<p>The easiest way to provide feedback is through
<a href="https://github.com/eclipse/packages/issues">GitHub issues</a> of the project.</p>
<h2 id="join-the-community-call">Join the community call</h2>
<p>Starting <time datetime="2019-12-02">2019-12-02</time>, we have a quick (30min), bi-weekly
community call at <time datetime="16:00">16:00</time> CET. This is an open call,
everyone is welcome to join.</p>
<p>The URL to the call is: <a href="https://eclipse.zoom.us/j/317801130?pwd=UGpXL29PejRrZWIzT2pKRFJGVUNqUT09">https://eclipse.zoom.us/j/317801130?pwd=UGpXL29PejRrZWIzT2pKRFJGVUNqUT09</a>.</p>
<p>You may also directly subscribe to the <a href="https://calendar.google.com/calendar/embed?src=u5j68s710reqmr37vd78jdlbm4%40group.calendar.google.com">community calendar</a>.</p>
<h2 id="contact-us-on-gitter">Contact us on Gitter</h2>
<p>We also do have a channel on Gitter: <a href="https://gitter.im/eclipse/packages" title="Gitter Channel">https://gitter.im/eclipse/packages</a>.</p>
<h2 id="improving-an-existing-package">Improving an existing package</h2>
<p>There is always room for improvement. Found a bug, have an idea how to make things better.
Make a change and create a pull request.</p>
<h2 id="extending-an-existing-package">Extending an existing package</h2>
<p>Got a cool idea on adding something new to an existing package? It makes sense to create an issue on GitHub,
and discuss your proposal. The existing maintainers of a package might want to understand how this fits
into their package, what the benefit is, and what is required. Get in touch, get on the same page, and start coding.</p>
<h2 id="creating-a-new-package">Creating a new package</h2>
<p>Found some Eclipse IoT projects that would make a great package? Then don’t hesitate to create a
PR against this repository which contains your new package. Please make sure that your PR’s description
explains why you think this new package should be created. Note that by adding a new package you
are expected to take ownership of the package as well.</p>
<h2 id="requirements-for-packages">Requirements for packages</h2>
<p>Regardless of whether you want to contribute a small change only or a completely new package, there
are some qualitative requirements that all packages and the charts they contain must meet.</p>
<p>All IoT Packages must</p>
<ul>
<li>be comprised of at least two Eclipse IoT projects that provide a real benefit when being
integrated with each other in this way.</li>
<li>only contain artifacts that are distributed under a license that is compatible with the EPLv2.</li>
<li>only contain stable, released versions of project artifacts (no milestones or snapshots).</li>
<li>must
<ul>
<li>contain a README covering a basic introduction and the idea behind the package,</li>
<li>include the Helm charts constituting the components of the package,</li>
<li>provide some guidance regarding what users might want to do with the package after installation.</li>
<li>include the <code class="language-plaintext highlighter-rouge">iot-package</code> key word in their <em>Chart.yaml</em></li>
</ul>
</li>
</ul>
<p>IoT Packages are implemented by means of Helm charts that are combined and configured in
a particular way. An IoT Package must not <em>contain</em> the Helm charts of the projects it comprises,
but instead must only <em>refer</em> to the projects’ Helm charts which are maintained and distributed separately.
This allows for a modular approach where projects can easily be (re)used in multiple IoT Packages.</p>
<p>The IoT Packages GitHub repository can be used to maintain both individual charts for Eclipse IoT Projects
as well as packages that are comprised of multiple projects:</p>
<ul>
<li>The <code class="language-plaintext highlighter-rouge">charts</code> folder contains Helm charts for Eclipse IoT projects. Each sub-folder contains a chart for
one project.</li>
<li>The <code class="language-plaintext highlighter-rouge">packages</code> folder contains the IoT packages. Each sub-folder represents one package.</li>
</ul>
<h2 id="requirements-for-charts">Requirements for charts</h2>
<p>All Helm charts in the repository must meet the following technical and documentation requirements.</p>
<h3 id="technical-requirements">Technical requirements</h3>
<p>Helm charts</p>
<ul>
<li>must not contain other charts that they depend on</li>
<li>must pass the Helm linter (<code class="language-plaintext highlighter-rouge">helm lint</code>)</li>
<li>must successfully launch with default values (<code class="language-plaintext highlighter-rouge">helm install .</code>)
<ul>
<li>all pods go to the running state (or NOTES.txt provides further instructions if a required value is missing e.g. <a href="https://github.com/helm/charts/blob/master/stable/minecraft/templates/NOTES.txt#L3">minecraft</a>)</li>
<li>all services have at least one endpoint</li>
</ul>
</li>
<li>must contain pointers to source GitHub repositories for images used in the chart</li>
<li>must not use container images that have any major security vulnerabilities</li>
<li>must be up-to-date with the latest stable Helm/Kubernetes features
<ul>
<li>use Deployments in favor of ReplicationControllers</li>
</ul>
</li>
<li>should follow Kubernetes best practices
<ul>
<li>include Health Checks wherever practical</li>
<li>allow configurable <a href="http://kubernetes.io/docs/user-guide/compute-resources/#resource-requests-and-limits-of-pod-and-container">resource requests and limits</a></li>
</ul>
</li>
<li>must provide a method for data persistence (if applicable)</li>
<li>must support application upgrades</li>
<li>must allow customization of the application configuration by means of Helm properties</li>
<li>must provide a secure default configuration</li>
<li>must not leverage alpha features of Kubernetes</li>
<li>must include a <a href="https://github.com/helm/helm/blob/master/docs/charts.md#chart-license-readme-and-notes">NOTES.txt</a> explaining how to use the application after install</li>
<li>must follow <a href="https://github.com/helm/helm/tree/master/docs/chart_best_practices">best practices</a>
(especially for <a href="https://github.com/helm/helm/blob/master/docs/chart_best_practices/labels.md">labels</a>
and <a href="https://github.com/helm/helm/blob/master/docs/chart_best_practices/values.md">values</a>)</li>
</ul>
<h3 id="documentation-requirements">Documentation Requirements</h3>
<p>Helm charts</p>
<ul>
<li>must include a <code class="language-plaintext highlighter-rouge">README.md</code>, containing:
<ul>
<li>a short description of the chart</li>
<li>any prerequisites or requirements</li>
</ul>
</li>
<li>must include a short <code class="language-plaintext highlighter-rouge">NOTES.txt</code>, containing:
<ul>
<li>any relevant post-installation information for the chart</li>
<li>instructions on how to access the application or service provided by the chart</li>
</ul>
</li>
<li>must contain a <code class="language-plaintext highlighter-rouge">values.yaml</code> file which contains a reasonable default configuration and explains
how the properties can be used to customize the chart</li>
<li>must include the <code class="language-plaintext highlighter-rouge">iot-chart</code> key word in their <em>Chart.yaml</em></li>
</ul>
<h2 id="merge-approval-and-release-process">Merge approval and release process</h2>
<p>All pull requests will be verified by a CI job which runs the linter and tries to install the chart to at least the three most recent minor releases of kubernetes.
At least one maintainer needs to explicitly approve the PR before it can be merged.</p>
<p>Once the Chart has been merged, a CI job will automatically package and release the Chart in the <a href="https://eclipse.org/packages/repository/">Eclipse IoT Packages repository</a>.</p>
<h2 id="when-to-increase-a-charts-version-number">When to increase a chart’s version number?</h2>
<p>Based on the assumption that a chart’s external interface and behavior is determined by the
configuration properties it supports, the following (non-exhaustive) table lists some types
of changes that should be reflected by a corresponding increase of the patch, minor or major
version of the chart.</p>
<table>
<thead>
<tr>
<th>Type of change</th>
<th>Requires increase of</th>
</tr>
</thead>
<tbody>
<tr>
<td>Update the <code class="language-plaintext highlighter-rouge">README.md</code> file</td>
<td>patch version</td>
</tr>
<tr>
<td>Chart introduces a property for explicitly configuring an already existing fixed value</td>
<td>patch version</td>
</tr>
<tr>
<td>Chart introduces a property for configuring a new feature with a reasonable default value</td>
<td>minor version</td>
</tr>
<tr>
<td>Chart renames an existing configuration property</td>
<td>major version</td>
</tr>
<tr>
<td>Chart removes an existing configuration property</td>
<td>major version</td>
</tr>
</tbody>
</table>
<h2 id="the-legal-side-of-things">The legal side of things</h2>
<p>If you plan on contributing code, you will need to
<a href="https://accounts.eclipse.org/user/register">create an Eclipse Foundation account</a>,
and <a href="https://accounts.eclipse.org/user/eca">sign the Eclipse Contributor Agreement</a>.</p>
<p>Is this required? Yes! Is there a way around it? No! Why is this necessary? Because legal
issues are as though as software engineering issues, and this is the way to solve them.</p>
</div>
</main>
<footer class="page-footer">
<div class="container">
<div class="row">
<div class="col-6 col-md">
<h5>Eclipse IoT Packages</h5>
<ul class="list-unstyled">
<li>
<a class="text-muted" href="/packages/">Home</a>
</li>
<li>
<a class="text-muted" href="/packages/about">About</a>
</li>
<li>
<a class="text-muted" href="/packages/contribute">Contribute</a>
</li>
<li>
<a class="text-muted" href="https://eclipse.org/security">Security</a>
</li>
</ul>
</div>
<div class="col-6 col-md">
<h5>Eclipse IoT</h5>
<ul class="list-unstyled">
<li>
<a class="text-muted" href="https://iot.eclipse.org">Top Level Project</a>
</li>
<li>
<a class="text-muted" href="https://www.eclipse.org/org/workinggroups/iotwg_charter.php">Working group</a>
</li>
</ul>
</div>
<div class="col-6 col-md">
<h5>Legal</h5>
<ul class="list-unstyled">
<li>
<a class="text-muted" href="https://www.eclipse.org/legal/privacy.php">Privacy Policy</a>
</li>
<li>
<a class="text-muted" href="https://www.eclipse.org/legal/termsofuse.php">Terms of Use</a>
</li>
<li>
<a class="text-muted" href="https://www.eclipse.org/legal/copyright.php">Copyright Agent</a>
</li>
<li>
<a class="text-muted" href="https://www.eclipse.org/legal/epl-2.0/">Eclipse Public License</a>
</li>
<li>
<a class="text-muted" href="https://www.eclipse.org/legal">Legal Resources</a>
</li>
</ul>
</div>
<div class="col-6 col-md">
<h5>Eclipse Foundation</h5>
<ul class="list-unstyled">
<li>
<a class="text-muted" href="https://eclipse.org/org">About us</a>
</li>
<li>
<a class="text-muted" href="https://www.eclipse.org/org/foundation/contact.php">Contact us</a>
</li>
<li>
<a class="text-muted" href="https://www.eclipse.org/org/foundation/directors.php">Board of Directors</a>
</li>
</ul>
</div>
</div>
<div class="row">
<div class="col-12 col-md text-muted">Copyright © Eclipse Foundation, Inc. All Rights Reserved.</div>
</div>
</div>
</footer>
<script src="/packages/assets/popper.min.js"></script>
<script src="/packages/assets/jquery.min.js"></script>
<script src="/packages/assets/bootstrap/bootstrap.min.js"></script>
<script src="/packages/assets/clipboard.min.js"></script>
<script src="/packages/assets/clipboard.js"></script>
</body>
</html>