VMware Sample Exchange BETA Contribution Guide
Sample Exchange is a new feature built as an extension of VMware Developer Center which provides anyone the ability to browse, download, search, and contribute sample code that builds on VMware APIs. This document is a guide for those that wish to contribute samples on Sample Exchange.
Sample Exchange is not a repository that is hosting samples itself. Sample Exchange provides a catalog of samples that live in other repositories such as Github. Sample Exchange provides discoverability and a work flow around requesting samples as well as easy contribution of samples, but does no hosting itself.
How to Contribute
- Go to the Sample Exchange home page
- Sign in using MyVMware credentials
Click on the “Sign In” button in the upper right corner. You can browse any of the content without being signed in, but in order to contribute you must sign in with your “MyVMware” credentials. Note also that you must have a VMware Communities account associated with your MyVMware account (anyone that has ever signed in to communities.vmware.com already has this).
- On the Samples tab, click “Add New Sample”
- Select the type of Sample you will contribute
See section 1.1 for details of the supported types. For this example we contribute content coming from an existing Github Repository (the preferred method).
Note: If you have not previously associated your MyVMware account with your Github account you can do so via the "Link your account with Github" link. This step uses Github OAUTH services to get a "token" that Sample Exchange can use to gain read access to your Github repositories and Gists.
- Select Sample Content
Browse for the sample content you would like to share. Here I select the Repository and browse to a particular file. Note that the goal of Sample Exchange is to deliver lots of useful content, so when samples are decoupled you should contribute them individually as opposed to selecting an entire repository or folder of unrelated files.
- Fill Out Sample Metadata
Fill out additional metadata for the file. NOTE: pp we do attempt to analyze the file itself to automatically provide defaults for things like sample name, description, tags, and such. In this case, the metadata contained in comments in the PowerShell script I selected was used to populate the values below for me! You can find details on the supported conventions on this page.
Sample storage and types of contributions supported
In the current Beta release, only content that lives on Github is supported. There are four different contribution types with different storage implications for each:
- Paste Sample (a snippet of code)
This is the simple case that you have a small snippet of code that does not live in Github and you want to contribute it. In this you type/paste the content into an edit box, provide some metadata and contribute. In the back-end, we create a Github “Gist” for the sample in the context of a Developer Center Github account on your behalf.
- Upload Sample (A zip of files)
If your sample is a collection of files that do not live in an existing Github repository, you can contribute a zip archive containing the files. You select a local zip file, provide some metadata for the sample, and contribute. In the back-end we create a Github repository for the sample in the context of a Developer Center Github account
- Github Gist
“Gist” is Github’s term for a small snippet of code. You can create Gist’s in your own Github account in the same way that you create repositories. If you have a snippet of code that may be long lived and that may change over time, if would be preferable to create a Gist in your account and then contribute that.
- Github Repository
Sample Exchange supports contributing an entire repository, a directory within a repository (and all content underneath it), or a single file in a repository. This is the preferable way to contribute any sample, because it allows sample exchange to automatically synchronize with any updates to the sample content.
File conventions for automatically extracting sample meta-data
There are few things more frustrating than doing the same work multiple times (especially for a programmer that likes to automate things!). To that end Sample Exchange does what it can to automatically determine a reasonable name, description, platform, and tags for any given sample. Knowing these details, you as a contributor can also adopt the conventions and ease the process of contributing samples.
Details of the conventions supported are described below.
A single file contributed as a sample
If you select a single file to contribute as a sample, we analyze the file itself to determine defaults for the metadata. Below is a description of the algorithm used so you can understand how best to set up your sample. Items found later in the list override defaults earlier in the list, i.e. if you provide data explicitly it will override the defaults that were determined heuristically.
- Attempt to use the file name as the sample name. Extension is dropped. Any underscores or dashes are turned into spaces. Camel case is split into spaces. First letters of any word are capitalized. Any VMware product names are then fixed (e.g. Vsphere -> vSphere). This produces fairly good results if the file name is reasonable.
- Description defaults to the sample name above
- Any comment block at the beginning of the file is used as a description (only for languages that support block comments, e.g. Java, Python). Any comments appearing after any non-comment are ignored, i.e. if you want to use the comment at the beginning of the file it must appear before any other normal text. This can be multi-line.
- The leading comment lines, either via single line comments (e.g. starting with # for Python, Ruby, Perl, etc) or block comments are checked for supported metadata values. See section 3.1.1
Supported Metadata names
The convention is <name>:<value> where <name> must be at the beginning of the line, or immediately after a single line comment char such as # for shell scripts/python/etc.
- Name: Explicit provision of the sample name. If this is provided it overrides the name as taken from the file name.
- Description: Explicit provision of a description for the sample. This does have to be on one line when provided this way. If provided it does override the value of the initial comment block.
- Version: A version number for the sample, or possibly the platform that it is for.
- Tags: An optional comma separated list of tags that should be applied to the sample
- Platforms: A comma separated list of platform/category values for the sample. e.g. "vSphere Perl", “vSphere Management”, “VMware PowerCLI”
- Reference: If provided and is a valid URL, get the title from the web page and use this as the description of the sample. This can be very effective if you have a particular sample that is described in a blog post for instance.
EXAMPLE 1: William Lam's changeVMStoragePolicy.pl sample
- The name of the sample is defaulted from the file name "Change VM Storage Policy".
- Initial line comments are analyzed for tags. From this we find a “Reference” tag. This page is resolved and the title used for a description, "Exploring VSAN APIs Part 6 – Modifying Virtual Machine VM Storage Policy". You can see the beginning of the file in Figure 1 changeVMStoragePolicy.pl example
EXAMPLE 2: Pyvmomi virtual_machine_power_cycle_and_question.py sample
- The name of the sample is defaulted from the file name "Change VM Storage Policy".
- Initial line comments are analyzed for tags. From this we find a “Reference” tag. This page is resolved and the title used for a description, "Exploring VSAN APIs Part 6 – Modifying Virtual Machine VM Storage Policy". You can see the beginning of the file in Figure 1 changeVMStoragePolicy.pl example.
Additional PowerShell Conventions
PowerShell has its own pseudo-standard conventions for metadata embedded in leading comments. You can use the convention above (e.g. “Name:”, “Description:”), or you can use the standard Microsoft convention (or both).
- .LABEL Any following text is used as the name of the sample
- .DESCRIPTION Any following multi-line text is used as the description of the sample.
- .SYNOPSIS: Any following multi-line text is use as the description of the sample. (treated as an alias for .DESCRIPTION)
Case of the identifiers doesn't matter.
This PowerShell script contains Microsoft format Metadata in the initial block comment. The follow sequence happens in order to automatically determine the default values.
- Name of sample is defaulted to "Execute ESXCLI PA" from the file name
- Initial block comment is scanned and .LABEL overrides the name as "Execute ESXCLI commands"
- DESCRIPTION in block comment overrides description to be "Allows execution of ESXCLI commands against an vSphere host through PowerActions."
Resisting to be notified of new/updated content
Sample Exchange does have a mechanism to be notified of new content, but it may not be immediately obvious how it works and the best way to use it. Internally Sample Exchange maintains a list of “watches” on content. You can watch a particular sample, or request, or can even watch a search that matches many (or all) samples. These watches are added automatically for you depending on your preferences, and you can add/remove them at any time.
To set notification preferences and register for notifications, you must be logged in to Sample Exchange. Once logged in, in the top right corner of the search results, under the “Add New Sample” button you will see a “Manage Favorites” link.
Clicking on the “Manage Favorites” link will bring up the Notifications tab in your User Profile. There are three preferences that you can set that control adding watches on Sample Exchange content:
- Contributing: If selected, any time that you add a sample or request, a watch on this sample or request is automatically added for you. You will be notified any time the sample changes. Of course you presumably know this since you are making the changes, but this does also include notifying you any time that a comment is made on your content by others so is useful to have selected. It is selected by default.
- Participating: If this preference is selected and you comment on a sample or request, a watch will be added for you on that content and you will be notified any time that it is updated or another user creates a new comment. You can delete this watch at any time.
- Watching: If this preference is selected and you favorite a sample, request, or a search, a watch is added to that item or search. After this, any time that the content changes, you will be notified.
Currently notifications are sent in a digest twice per day, so the frequency is not overwhelming. In the future the frequency will be controlled via a user preference.
Subscribing for Notifications for new or changed samples
You can be notified any time samples you are interested in are added or changed. To do this, simply select the filters you wish on the left hand side of the sample screen and optionally enter any keywords to search for. When the search results are displayed, click the “Add to Favorites” link (see Figure 6).
Once per day this search will be run on your behalf in Sample Exchange and any time that results change, you will be notified.
In Figure 5 under “Sample Exchange Favorites” you will see a list of all content that you have either manually favorited via clicking “Add to Favorites”, or has been watched automatically as a result of your “Contributing” and “Participating” preferences. To unsubscribe for a particular notification, uncheck the item. As soon as focus leaves the page the watch on the given item is removed. If you would like to subscribe for the notification again, you then must go to the item (sample, request, or search) and favorite the item again.
Why are you doing this, why don't we just put content on Github?
It is important to understand that Sample Exchange is not a repository of samples, rather it is an extension of the existing Developer Center site that provides a set of services around a repository of sample meta-data. The samples themselves in fact live elsewhere (currently only on Github). The value add that Sample Exchange is providing is that it is a single pane of glass providing access to sample content irrespective of where it is stored. It is a single place for people to find and contribute samples. Also, content on Github is rather poorly indexed by Google at the moment, and as a result is somewhat difficult to discover. Coupling together requests for samples, questions/answers related to samples, tags and other sample meta-data, API documentation, tools and more in the sample portal is going to result in more traffic and greater discoverability for the samples.
Why do you want write access to my Github account?
We actually don’t need or use write access to your Github account. This is an artifact of software reuse from a Github component we had developed and used elsewhere. This will be fixed in the next production release of Sample Exchange. In fact Sample Exchange only needs read access to your Github account, and we only read repositories or Gists that you contribute.
I see a contribution from me, but I didn't actually contribute it, how did that happen?
We took some liberties and wrote a tool that iterated through samples that were already on github and contributed them. The tool actually tries to use git blame to figure out who the primary author of a given sample and contributed it as them if we could figure out their account info automatically. If we messed this up, please send us an email at firstname.lastname@example.org and we will fix it.
I see a sample that in fact I wrote but it is contributed by someone else.
In the initial contribution of content we used a tool that we wrote that tries to use git blame to figure out who the primary author of a given sample and contributed it as them if we could figure out their account info automatically. It is entirely possible that the content may in fact have been copied from your repository and we could not detect this, or perhaps our algorithm isn't perfect. In any case we want to give credit where it is due. If this is the case, please tell us your MyVMware account info, communities account name, and Github account and we will fix it. Send an email to email@example.com.
How do I contribute samples that are in the VMware org account on Github?
If you have a github account and your account is a member of the VMware org, you may already be able to contribute the content already. Select "Import from Github - Repository" and you should see the VMware org repository. Select that and then select the folder or file you want to contribute. If you are not a member of the org but there is content that you want to contribute, please contact firstname.lastname@example.org to help you with the contribution. Currently the web UI only supports contributing content from your github account or other org repositories that you are a member of, but we can contribute from other accounts manually via another tool VMware has internally.
My Sample already has metadata/docs embedded in the sources, do I really have to type all that in again?
Hopefully not! We do have a component in place in the back end that analyzes your sample and provides default values for you, see section 3. The algorithms are not perfect (gasp!) and we suspect that there are other conventions that we don't support yet. If that is the case please let us know at email@example.com.
My sample is in a branch other than master can I contribute it?
Currently Sample Exchange only supports adding samples that are located on the “master” branch of a given repository. This support is coming though.