10.d. Sharing Your App with the Wixel Community

Preparing your app for the community

Please make sure that you have set up the following sections in your WXL file:

• description – this should fully describe what your app does or link to a web site with a complete description. Since other people will be trying this on their Wixels, make sure to bring our attention to anything that may cause damage or incompatibility. Most importantly, any IO ports used as outputs should be explicitly listed in the description.

• license – this specifies the terms under which others may distribute copies or modifications of your app. We recommend and use the MIT license, which is simple and allows widespread use of your code. Note that if you have used the Wixel SDK to build your app, you need to include our license, though you may add your own restrictions if necessary. We recommend using the following template, which will make it easy for us to share your app or to include it in the Wixel SDK:

Copyright (c) 2011 <YOUR NAME>.  Documentation for this app is available at:

http://<YOUR SITE>/

Copyright (c) 2011 Pololu Corporation.  For more information, see

http://www.pololu.com/
http://forum.pololu.com/

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

Announcing your app on the Wixel forum

When you are ready for the community to try out a version of your app, you may announce it on the Wixel forum, attaching your WXL file. It is helpful to paste a copy of your description into your post so that we can see what your app is about before downloading it.

Contributing your source code

Sharing your source code greatly increases the value of your app, since other members of the community will be able to adapt it to their own projects or learn from your code. You might also have made changes to the common sections of the Wixel SDK that you would like us to incorporate, or you might have discovered and want to share your fixes. For all of these reasons, we are maintaining the Pololu Wixel SDK Repository on GitHub as a central location for sharing Wixel code. You can easily use this site to fork your own version of the Wixel SDK, show us what you are working on, submit changes, and so on.

GitHub uses the Git Version Control System for tracking versions and branches of code, so we highly recommend learning how to use Git if you want to share your code with the Wixel community or even just to get the latest version for your own use. Teaching Git is beyond the scope of this User’s Guide, but there are many good tutorials available on the web. For example, the Git tutorial provided by GitHub will help you get started.

For the rest of this section, we will assume that you are comfortable with Git.

If you have been following the instructions in this document, your code is located within the wixel-sdk folder along with the rest of the Wixel SDK. This folder is actually a clone of our Git repository, which means that it includes history and version information as well as a link back to our repository (a remote), within the folder .git. As long as you have not modified the contents of .git, you should be able to use Git to commit your changes, pull updates from us, and push your changes to a public repository. To make sure that Git is working correctly, try typing the following command at the command prompt from within the wixel-sdk folder:

git log

This should display a list of recent commits in the repository. Alternatively, you can use the program gitk or you can use the “Show Log” command of TortoiseGit to view a much more detailed, graphical representation of the log. After reviewing the log, you can add and commit all of your new files:

git add <list of new files...>
git commit -a

Alternatively, you can use the “Commit…” command of TortoiseGit. Either way, you will be shown a list of new or modified files and prompted for a commit message. Please check this over carefully and write a good description of your changes, because it is very hard to change your commits after you make them public.

In some cases, you might want to start over with a fresh copy of the Wixel SDK, which you can make by typing

git clone -o pololu git://github.com/pololu/wixel-sdk.git

into a command prompt. At any time, you can download the latest updates from us and merge them into your code by typing the following command:

git pull pololu

Initially, you will commit your changes to your local repository, but when you are ready to publish them, you should set up your own repository on GitHub to make them accessible to the community. To do this, sign up for a GitHub account and fork our repository into a repository on your account. Please do this by clicking the “fork” button at the top of our repository so that it will be connected within the GitHub system – this way we will see your changes and can easily incorporate them into the SDK. After making your fork, you can push all of the changes from your local repository to GitHub with

git remote add myrepo <GitHub URL>
git push myrepo

where <GitHub URL> is the SSH or HTTP URL shown on your GitHub page.

Finally, you will probably want to post a link to your GitHub repository on the Wixel forum. This will help others find out about it and give you feedback on your contribution.