VMware {code} sample storage options and types

Currently Sample Exchange exclusively supports open source samples, and those samples must live on Github.
There are a number of ways that those samples can be contributed on sample exchange, and which mechanism you choose will depend on how you plan to maintain the sample moving forward. This sections details the tradeoffs and advantages of different approaches.

Types of samples - options for sample storage

Below is a quick explanation of the different types of samples SX supports. There are detailed pros/cons for each below.

Sample Type Overview
Link to Github Repository This is the preferred way to contribute a sample. You can contribute an entire repository from the root, or can contribute one or more paths (folders or individual files) from the repository as a sample.
Link to Github Gist "Gist" is the name for Github's concept of a snippet of code. The gist exists in your personal Github account.
Upload Sample This method does not require a Github account. You can select either a single sample file, or a zip of multiple files. The content is hosted in a repository created in the vmwarecode organization on Github on your behalf. Before you jump into using this type (because it is the easiest), stop to consider maintaining the code in the future. If this is a project you intend to maintain over time, it is best to create a Github repository for it.
Paste Sample This is a quick and dirty copy paste of a snippet of script/code. The content is hosted in a repository created in the vmwarecode organization on Github on your behalf. If you are showing how to do something and don't really intend on maintaining it in the future, this is fine. This type also doesn't require you to have a Github account.

Storing the sample in a personal or organization Github account

For the Link to Github Repository type, you can choose whether to store the sample in your personal Github account, or in a VMware or other organization account. Which you choose depends on what you plan to do with the sample long term. Here are some guidelines:

  • In general, if this sample is ever going to be an "official sample" for a given product, then the right thing to do is place it in a repository in a VMware Github organization (there are multiple depending on the type of content).
  • If people are going to work on the samples, then it probably should be in a vmware organization.
  • If there are going to be multiple related samples in the same repository, it sounds like the repo should be in a vmware organization.

Pros and Cons

In this use case the sample is located in a Git repository located on Github. The repository can be located in either your personal account, or a vmware organization account. Sample Exchange does no copying, it simply points at your existing repository.

pros

  • You have full control over the sample
  • Changes to the sample are automatically picked up by Sample Exchange.
  • Users that "watch" your sample are notified of any changes by Sample Exchange
  • Users get the full features of Sample Exchange for your sample (links to related products/apis/tools/docs, easy browsing/downloads, discoverability in Google)
  • Users can use "git clone" to get access to your sample and all of the goodness that this implies (ability to contribute back, picking up fixes, version control, ...)

cons

  • Currently the only con to this approach occurs if the sample consists of multiple files that are in a sub-folder of the repository. In this case if the user elects to download the sample, Sample Exchange provides a zip of the entire repository including the sample files, but also including all other repository content (which may be unrelated). This is a limitation of Github APIs... Note that there is a work around in place that does provide only the particular sample file if the sample consists of a single file.

A Gist is Github's notion of a code "snippet". There are separate facilities that can be used to create a Gist in your Github account. If you have created one, you can easily contribute it on Sample Exchange.
Other than the mechanism for contribution being different, this is identical from Sample Exchange's perspective to the repository use case above.

Upload Sample

In this use case, Sample Exchange allows you to contribute a single sample file or a zip file containing multiple files directly.
Behind the scenes, Sample Exchange creates a repository on your behalf in the "vmwarecode" account that is owned by VMware and posts the sample content for you. If you have a Github account that is linked to your VMware {code} account (which you do by going through the "Link to Github Repository" flow one time) you will also be made a collaborator on the created repository for your convenience.

pros

  • User does not have to have a Github account, or know anything about using Git
  • The original contributor can update the content by logging into Sample Exchange, editing the sample, and selecting a new zip/file

cons

  • The repository that is created for you is owned by "vmwarecode", a VMware organization account, not you. As such you cannot use Github or Git to edit the sample

Paste Sample

In this use case you directly type a sample or paste a block of code directly from the clipboard into the submission UI on Sample Exchange. This is the most simple flow.

pros

  • Super easy, no knowledge of Git or Github required at all
  • Sample can be updated in Sample exchange by editing the sample and pasting updated content

cons

  • You must use Sample Exchange to edit the sample, you cannot use Github

results matching ""

    No results matching ""