<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 = &quot;Rust HTTP trigger template&quot; template = &quot;render_hub_content_body&quot; date = &quot;2022-10-15T00:22:56Z&quot; content-type = &quot;text/html&quot; tags = [&quot;rust&quot;, &quot;http&quot;] [extra] author = &quot;fermyon&quot; type = &quot;hub_document&quot; category = &quot;Template&quot; language = &quot;Rust&quot; created_at = &quot;2022-10-15T00:22:56Z&quot; last_updated = &quot;2022-10-15T00:22:56Z&quot; spin_version = &quot;&gt;v0.2&quot; summary = &quot;A template to create an HTTP handler in Rust&quot; url = &quot;https://github.com/fermyon/spin/tree/main/templates/http-rust&quot; --- </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., &gt;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 &quot;yourusername&quot; </code></pre> <!-- @nocpy --> <pre><code class="language-bash">$ git config user.email &quot;youremail@somemail.com&quot; </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 &quot;Updating Spin Up Hub&quot; </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>