<ul>
<li><a href="#contribution-procedure">Contribution Procedure</a>
<ul>
<li><a href="#fork-the-repository">Fork the Repository</a></li>
<li><a href="#clone-the-fork">Clone the Fork</a></li>
<li><a href="#create-new-branch">Create New Branch</a></li>
<li><a href="#add-upstream">Add Upstream</a></li>
<li><a href="#creating-markdown">Creating Markdown</a></li>
<li><a href="#valid-metadata">Valid Metadata</a></li>
<li><a href="#valid-content-types">Valid Content Types</a></li>
<li><a href="#testing-locally">Testing Locally</a></li>
<li><a href="#add-changes">Add Changes</a></li>
<li><a href="#commit-changes">Commit Changes</a></li>
<li><a href="#push-changes">Push Changes</a></li>
<li><a href="#create-a-pull-request">Create a Pull Request</a></li>
</ul>
</li>
</ul>
<p>We are delighted that you are interested in making Spin Up Hub better! Thank you! This
document will guide you through making your first contribution to the project.</p>
<p>First, any contribution and interaction on any Fermyon project MUST follow our
<a href="https://www.fermyon.com/code-of-conduct">code of conduct</a>. Thank you for being
part of an inclusive and open community!</p>
<h2>Contribution Procedure</h2>
<h3>Fork the Repository</h3>
<p>The first step is to fork the <a href="https://github.com/fermyon/developer">developer repository</a>, from Fermyon’s GitHub, to your own GitHub account.</p>
<p><img src="/static/image/fork_developer_repo.png" alt="Fork the repository" /></p>
<p>Ensure that you are forking the developer repository <strong>to your own</strong> GitHub account; where you have full editing privileges.</p>
<h3>Clone the Fork</h3>
<p>Copy the URL from the UI in readiness for running the <code>git clone</code> command.</p>
<p><img src="/static/image/clone_developer_repo.png" alt="Fork the repository" /></p>
<p>Go ahead and clone the new fork that you just created (the one which resides in your own GitHub account):</p>
<!-- @nocpy -->
<pre><code class="language-bash">$ cd ~
$ git clone git@github.com:yourusername/developer.git
$ cd developer
</code></pre>
<h3>Create New Branch</h3>
<p>Create a new branch that will house all of your changes for this specific contribution:</p>
<!-- @nocpy -->
<pre><code class="language-bash">$ git checkout -b my_new_branch
</code></pre>
<h3>Add Upstream</h3>
<p>Create a new remote for the upstream (a pointer to the original repository to which you are contributing):</p>
<!-- @nocpy -->
<pre><code class="language-bash">$ git remote add upstream https://github.com/fermyon/developer
</code></pre>
<h3>Creating Markdown</h3>
<p>Create a <strong><code>.md</code></strong> Markdown file in the <strong><code>content/api/hub</code></strong> folder in your fork. (Adhering to the naming convention of other files helps keep things tidy and manageable.)</p>
<p>Below is a copyable example to get you started:</p>
<!-- @nocpy -->
<pre><code class="language-toml">title = "Rust HTTP trigger template"
template = "render_hub_content_body"
date = "2022-10-15T00:22:56Z"
content-type = "text/html"
tags = ["rust", "http"]

[extra]
author = "fermyon"
type = "hub_document"
category = "Template"
language = "Rust"
created_at = "2022-10-15T00:22:56Z"
last_updated = "2022-10-15T00:22:56Z"
spin_version = ">v0.2"
summary =  "A template to create an HTTP handler in Rust"
url = "https://github.com/fermyon/spin/tree/main/templates/http-rust"

---

</code></pre>
<p>Be sure to make a description of the hub item in the body (below the <strong><code>---</code></strong> line). The content that you write below the <strong><code>---</code></strong> line will be the content shown when the card is expanded in a modal view. For example:</p>
<pre><code class="language-md">This is the default HTTP trigger template for Rust. It installs by default with the [Spin install script](https://developer.fermyon.com/spin/install#installing-spin).

This guide walks you through how to use it: [HTTP Components](https://developer.fermyon.com/spin/rust-components#http-components)
</code></pre>
<h3>Valid Metadata</h3>
<p>Please see the following table for valid metadata fields to use in your contribution (complete with descriptions, examples and comments for each):</p>
<table><thead><tr><th>Metadata</th><th>Description</th><th>Example</th><th>Comment</th></tr></thead><tbody>
<tr><td>Submitter</td><td>The GitHub handle of the person submitting the content.</td><td>karthik2804 (as link to GitHub profile).</td><td></td></tr>
<tr><td>Date created</td><td>The data the submission was made.</td><td></td><td>This can never be changed. The data can be shown in the modal.</td></tr>
<tr><td>Content Type</td><td>Drop-down of categories (see below).</td><td></td><td>These will be the hardcoded filters in the UI overview.</td></tr>
<tr><td>Link</td><td>Link to where to find the source.</td><td></td><td>If this is a release of something from GitHub, would the link be to the release, or the repo?</td></tr>
<tr><td>Date Updated</td><td>Last date the content was updated.</td><td></td><td>This is potentially a filterable value, to be show on the card.</td></tr>
<tr><td>Programming Language</td><td>The programming language used to produce the content.</td><td></td><td>Used for filtering and search.</td></tr>
<tr><td>Should be shown on the card.</td><td></td><td></td><td></td></tr>
<tr><td>Description</td><td>The description of the content.</td><td></td><td>This is not metadata, but the body text in the md file.</td></tr>
<tr><td>Will be shown in the modal.</td><td></td><td></td><td></td></tr>
<tr><td>Key Words / Tags</td><td>Words to help indexing.</td><td></td><td>Will we do manual consolidation? i.e., person adds key-value and another adds key-values</td></tr>
<tr><td>Spin Version Compatibility</td><td>Versions of Spin supporting this artifact.</td><td></td><td>e.g., >1.0.0</td></tr>
<tr><td>Summary</td><td>A summary of the description, to be shown on the card.</td><td></td><td>Could be used as a hover-over context.</td></tr>
</tbody></table>
<h3>Valid Content Types</h3>
<p>The following is a list of the types of content that a user can submit to the Spin Up Hub.</p>
<ul>
<li><strong>Examples</strong>
<ul>
<li>Spin Application examples</li>
<li>Code snippets</li>
</ul>
</li>
<li><strong>(Spin) Templates</strong>
<ul>
<li>Complete components such as the <a href="https://github.com/fermyon/spin-fileserver">Spin static-fileserver</a></li>
</ul>
</li>
<li><strong>(Spin) Plugins</strong>
<ul>
<li>Triggers and tools</li>
<li>See Lee-Orr’s Message trigger: <a href="https://github.com/lee-orr/spin-message-trigger">https://github.com/lee-orr/spin-message-trigger</a></li>
</ul>
</li>
<li><strong>Libraries</strong>
<ul>
<li>Spin SDKs i.e. <a href="https://github.com/fermyon/spin-python-sdk">https://github.com/fermyon/spin-python-sdk</a></li>
<li>See the following example of a library by Thorsten Hans: <a href="https://github.com/ThorstenHans/spin-contrib-http">https://github.com/ThorstenHans/spin-contrib-http</a></li>
</ul>
</li>
</ul>
<h3>Testing Locally</h3>
<p>After your file has been created, you can test it on localhost before committing.</p>
<!-- @nocpy -->
<pre><code class="language-console">$ npm install
$ cd spin-up-hub
$ npm install
$ cd ..
$ spin build
$ npm run spin
</code></pre>
<h3>Add Changes</h3>
<p>Once your changes have been checked, go ahead and add your changes by moving to a top-level directory, under which your changes exist i.e. <code>cd ~/developer</code>.</p>
<p>Add your changes by running the following command, from the root of the developer repository:</p>
<!-- @nocpy -->
<pre><code class="language-bash">$ git add .
</code></pre>
<h3>Commit Changes</h3>
<p>Before committing, please ensure that your GitHub installation is configured sufficiently so that you can <code>--signoff</code> as part of the <code>git commit</code> command. For example, please ensure that the <code>user.name</code> and <code>user.email</code> are configured in your terminal. You can check if these are set by typing <code>git config --list</code>.</p>
<p>If you need to set these values please use the following commands:</p>
<!-- @nocpy -->
<pre><code class="language-bash">$ git config user.name "yourusername"
</code></pre>
<!-- @nocpy -->
<pre><code class="language-bash">$ git config user.email "youremail@somemail.com"
</code></pre>
<p>More information can be found at this GitHub documentation page called <a href="https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits">signing commits</a>.</p>
<p>Type the following commit command to ensure that you sign off (–signoff), sign the data (-S) - recommended, and also leave a short message (-m):</p>
<!-- @nocpy -->
<pre><code class="language-bash">$ git commit -S --signoff -m "Updating Spin Up Hub"
</code></pre>
<blockquote>
<p>Note: the <code>--signoff</code> option will only add a Signed-off-by trailer by the committer at the end of the commit log message. In addition to this, it is recommended that you use the <code>-S</code> option which will GPG-sign your commits. For more information about using GPG in GitHub see <a href="https://docs.github.com/en/authentication/managing-commit-signature-verification/adding-a-gpg-key-to-your-github-account">this GitHub documentation</a>.</p>
</blockquote>
<h3>Push Changes</h3>
<p>At this stage, it is a good idea to just quickly check what GitHub thinks the origin is. For example, if we type <code>git remote -v</code> we can see that the origin is our repo; which we a) forked the original repo into and b) which we then cloned to our local disk so that we could edit:</p>
<!-- @nocpy -->
<pre><code class="language-bash">$ git remote -v
</code></pre>
<p>The above command will return output similar to the following:</p>
<!-- @nocpy -->
<pre><code class="language-bash">origin	git@github.com:yourusername/developer.git (fetch)
origin	git@github.com:yourusername/developer.git (push)
upstream	https://github.com/fermyon/developer (fetch)
upstream	https://github.com/fermyon/developer (push)
</code></pre>
<p>Once you are satisfied go ahead and push your changes:</p>
<!-- @nocpy -->
<pre><code class="language-bash">$ git push -u origin my_new_branch
</code></pre>
<h3>Create a Pull Request</h3>
<p>If you return to your GitHub repository in your browser, you will notice that a PR has automatically been generated for you.</p>
<p>Clicking on the green “Compare and pull request” button will allow you to add a title and description as part of the PR. </p>
<p><img src="/static/image/compare_and_pull_request.png" alt="Compare and pull request" /></p>
<p>You can also add any information in the textbox provided below the title. For example, screen captures and/or code/console/terminal snippets of your contribution working correctly and/or tests passing etc.</p>
<p>Once you have finished creating your PR, please keep an eye on the PR; answering any questions as part of the collaboration process.</p>
<p><strong>Thank You</strong></p>
<p>Thanks for contributing.</p>